pulse-code 1.1.2__tar.gz → 1.1.4__tar.gz

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 (136) hide show
  1. {pulse_code-1.1.2/src/pulse_code.egg-info → pulse_code-1.1.4}/PKG-INFO +32 -9
  2. pulse_code-1.1.2/PKG-INFO → pulse_code-1.1.4/README.md +25 -21
  3. {pulse_code-1.1.2 → pulse_code-1.1.4}/pyproject.toml +10 -9
  4. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/catalog.py +2 -3
  5. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/cdc_open_catalog.py +1 -2
  6. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/cli.py +806 -145
  7. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/data/seer_var_formats.json +1 -1
  8. pulse_code-1.1.4/src/pulse/dqs_catalog.py +379 -0
  9. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/dqs_sdk.py +12 -11
  10. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/grasp_catalog.py +60 -14
  11. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/grasp_client.py +12 -4
  12. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/grasp_sdk.py +16 -5
  13. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/llm_builder.py +23 -23
  14. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/matcher.py +1 -1
  15. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/nis_catalog.py +52 -13
  16. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/nis_parser.py +5 -2
  17. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/nis_sdk.py +20 -6
  18. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/nssp_client.py +3 -1
  19. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/nssp_sdk.py +13 -3
  20. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/sources_registry.py +21 -1
  21. pulse_code-1.1.4/src/pulse/sudors_catalog.py +238 -0
  22. pulse_code-1.1.4/src/pulse/sudors_sdk.py +520 -0
  23. pulse_code-1.1.4/src/pulse/topics_registry.py +562 -0
  24. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/wisqars_catalog.py +18 -2
  25. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/wonder_client.py +6 -6
  26. pulse_code-1.1.2/README.md → pulse_code-1.1.4/src/pulse_code.egg-info/PKG-INFO +44 -3
  27. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse_code.egg-info/SOURCES.txt +2 -0
  28. pulse_code-1.1.4/src/pulse_code.egg-info/requires.txt +9 -0
  29. pulse_code-1.1.2/src/pulse/dqs_catalog.py +0 -116
  30. pulse_code-1.1.2/src/pulse/topics_registry.py +0 -302
  31. pulse_code-1.1.2/src/pulse_code.egg-info/requires.txt +0 -8
  32. {pulse_code-1.1.2 → pulse_code-1.1.4}/LICENSE +0 -0
  33. {pulse_code-1.1.2 → pulse_code-1.1.4}/setup.cfg +0 -0
  34. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/__init__.py +0 -0
  35. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/__main__.py +0 -0
  36. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/data/catalog.json +0 -0
  37. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/data/cdc_open_catalog.json +0 -0
  38. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/data/queries_index.json +0 -0
  39. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/data/variable_labels.json +0 -0
  40. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/aids-cases-by-age-1981-1999-req.xml +0 -0
  41. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/aids-cases-by-location-1981-1999-req.xml +0 -0
  42. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/aids-cases-by-race-1981-1999-req.xml +0 -0
  43. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/aids-cases-by-sex-1981-1999-req.xml +0 -0
  44. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/aids-cases-by-year-1981-1999-req.xml +0 -0
  45. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/births-by-age-of-mother-2007-2024-req.xml +0 -0
  46. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/births-by-race-2007-2024-req.xml +0 -0
  47. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/births-by-year-1995-2002-req.xml +0 -0
  48. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/births-by-year-2003-2006-req.xml +0 -0
  49. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/births-by-year-2007-2024-req.xml +0 -0
  50. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/cancer-incidence-by-site-by-year-1999-2022-req.xml +0 -0
  51. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/cancer-incidence-by-state-1999-2022-req.xml +0 -0
  52. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/cancer-mortality-by-site-by-year-2018-2023-req.xml +0 -0
  53. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/cancer-mortality-by-state-2018-2023-req.xml +0 -0
  54. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/covid-deaths-by-age-2020-2023-req.xml +0 -0
  55. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/covid-deaths-by-age-sex-2020-2023-req.xml +0 -0
  56. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/covid-deaths-by-race-2020-2023-req.xml +0 -0
  57. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/covid-deaths-by-sex-2020-2023-req.xml +0 -0
  58. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/deaths-by-place-of-death-2018-2024-req.xml +0 -0
  59. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/drug-deaths-by-month-1999-2020-req.xml +0 -0
  60. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/drug-deaths-by-month-2018-2024-req.xml +0 -0
  61. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/drug-deaths-by-year-1999-2020-req.xml +0 -0
  62. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/drug-deaths-by-year-2018-2024-req.xml +0 -0
  63. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/fentanyl-deaths-by-month-1999-2020-req.xml +0 -0
  64. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/fentanyl-deaths-by-month-2018-2024-req.xml +0 -0
  65. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/fetal-deaths-by-age-of-mother-2005-2024-req.xml +0 -0
  66. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/fetal-deaths-by-cause-by-year-2014-2024-req.xml +0 -0
  67. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/fetal-deaths-by-race-2005-2024-req.xml +0 -0
  68. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/fetal-deaths-by-year-2005-2024-req.xml +0 -0
  69. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/heart-vs-cancer-by-sex-2018-2023-req.xml +0 -0
  70. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/heat-wave-days-by-county-req.xml +0 -0
  71. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/infant-mortality-2018-2023-req.xml +0 -0
  72. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/infant-mortality-by-cause-by-year-2007-2023-req.xml +0 -0
  73. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/maternal-mortality-by-race-2018-2024-req.xml +0 -0
  74. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/maternal-mortality-by-year-1999-2020-req.xml +0 -0
  75. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/maternal-mortality-by-year-2018-2024-req.xml +0 -0
  76. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/mortality-by-race-sex-2018-2023-req.xml +0 -0
  77. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/mortality-by-year-cause-1979-1998-req.xml +0 -0
  78. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/mortality-by-year-cause-1999-2020-req.xml +0 -0
  79. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/mortality-by-year-cause-2021-2024-req.xml +0 -0
  80. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/opioid-deaths-by-age-2018-2024-req.xml +0 -0
  81. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/opioid-deaths-by-sex-2018-2024-req.xml +0 -0
  82. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/opioid-overdose-deaths-2018-2024-req.xml +0 -0
  83. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/pm25-by-state-2003-2011-req.xml +0 -0
  84. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/pm25-by-year-2003-2011-req.xml +0 -0
  85. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/provisional-births-by-month-2023-req.xml +0 -0
  86. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/racial-mortality-gap-2018-2023-req.xml +0 -0
  87. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/std-cases-by-disease-by-year-1984-2014-req.xml +0 -0
  88. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/std-cases-by-state-1984-2014-req.xml +0 -0
  89. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/suicide-by-sex-1999-2020-req.xml +0 -0
  90. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/suicide-by-sex-2021-2024-req.xml +0 -0
  91. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/tb-cases-by-year-1993-2023-req.xml +0 -0
  92. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/tick-borne-diseases-by-age-2016-2023-req.xml +0 -0
  93. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/tick-borne-diseases-by-race-2016-2023-req.xml +0 -0
  94. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/tick-borne-diseases-by-sex-2016-2023-req.xml +0 -0
  95. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/tick-borne-diseases-by-state-2016-2023-req.xml +0 -0
  96. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/tick-borne-diseases-by-year-2016-2023-req.xml +0 -0
  97. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/underlying-cause-mortality-by-year-1999-2020-req.xml +0 -0
  98. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/queries/unintentional-injuries-by-age-2018-2023-req.xml +0 -0
  99. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/seer_catalog.py +0 -0
  100. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/seer_client.py +0 -0
  101. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/seer_sdk.py +0 -0
  102. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/soda_client.py +0 -0
  103. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/templates/D10-base.xml +0 -0
  104. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/templates/D104-base.xml +0 -0
  105. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/templates/D117-base.xml +0 -0
  106. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/templates/D128-base.xml +0 -0
  107. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/templates/D140-base.xml +0 -0
  108. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/templates/D141-base.xml +0 -0
  109. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/templates/D149-base.xml +0 -0
  110. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/templates/D157-base.xml +0 -0
  111. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/templates/D158-base.xml +0 -0
  112. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/templates/D159-base.xml +0 -0
  113. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/templates/D16-base.xml +0 -0
  114. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/templates/D176-base.xml +0 -0
  115. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/templates/D178-base.xml +0 -0
  116. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/templates/D18-base.xml +0 -0
  117. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/templates/D192-base.xml +0 -0
  118. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/templates/D204-base.xml +0 -0
  119. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/templates/D23-base.xml +0 -0
  120. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/templates/D27-base.xml +0 -0
  121. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/templates/D31-base.xml +0 -0
  122. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/templates/D60-base.xml +0 -0
  123. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/templates/D61-base.xml +0 -0
  124. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/templates/D66-base.xml +0 -0
  125. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/templates/D69-base.xml +0 -0
  126. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/templates/D73-base.xml +0 -0
  127. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/templates/D74-base.xml +0 -0
  128. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/templates/D76-base.xml +0 -0
  129. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/templates/D77-base.xml +0 -0
  130. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/templates/D8-base.xml +0 -0
  131. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/templates/D80-base.xml +0 -0
  132. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/templates/D81-base.xml +0 -0
  133. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse/wisqars_sdk.py +0 -0
  134. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse_code.egg-info/dependency_links.txt +0 -0
  135. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse_code.egg-info/entry_points.txt +0 -0
  136. {pulse_code-1.1.2 → pulse_code-1.1.4}/src/pulse_code.egg-info/top_level.txt +0 -0
@@ -1,19 +1,20 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pulse-code
3
- Version: 1.1.2
3
+ Version: 1.1.4
4
4
  Summary: CDC WONDER query CLI — explore, build, and refine public health data queries
5
5
  License-Expression: CC0-1.0
6
6
  Requires-Python: >=3.11
7
7
  Description-Content-Type: text/markdown
8
8
  License-File: LICENSE
9
- Requires-Dist: anthropic==1.1.0
10
- Requires-Dist: openai==3.5.0
11
- Requires-Dist: pydantic==2.13.4
12
- Requires-Dist: python-dotenv==1.2.3
9
+ Requires-Dist: anthropic==2.9.0
10
+ Requires-Dist: openai==3.51.0
11
+ Requires-Dist: openpyxl==3.1.5
12
+ Requires-Dist: pydantic==2.14.3
13
+ Requires-Dist: python-dotenv==1.2.4
13
14
  Requires-Dist: requests==2.34.2
14
15
  Requires-Dist: rich==15.0.0
15
16
  Requires-Dist: socksio==1.0.0
16
- Requires-Dist: typer==0.27.1
17
+ Requires-Dist: typer==0.29.1
17
18
  Dynamic: license-file
18
19
 
19
20
  # Pulse
@@ -24,7 +25,7 @@ Dynamic: license-file
24
25
  [![Pages](https://img.shields.io/github/actions/workflow/status/fartbagxp/pulse-code/pages.yml?style=for-the-badge&label=pages)](https://fartbagxp.github.io/pulse-code/)
25
26
  [![License](https://img.shields.io/badge/license-CC0--1.0-blue?style=for-the-badge)](LICENSE)
26
27
 
27
- `pulse` is a command line tool for querying public health data. It covers eight live sources: CDC WONDER, NCI SEER cancer statistics, CDC Open Data, the NCHS Data Query System (Health, United States), WISQARS injury data, ATSDR GRASP disease surveillance, NSSP ED visits, and NIS vaccination surveys. Browse them by topic, run bundled queries, and get CSV, JSON, or a table back.
28
+ `pulse` is a command line tool for querying public health data. It covers nine live sources: CDC WONDER, NCI SEER cancer statistics, CDC Open Data, the NCHS Data Query System (Health, United States), WISQARS injury data, ATSDR GRASP disease surveillance, NSSP ED visits, NIS vaccination surveys, and SUDORS fatal-overdose surveillance. Browse them by topic, run bundled queries, and get CSV, JSON, or a table back.
28
29
 
29
30
  ![pulse-code demo](docs/demo/pulse-demo.gif)
30
31
 
@@ -39,7 +40,7 @@ pulse --help
39
40
  uv run pulse --help
40
41
  ```
41
42
 
42
- Querying any of the eight sources needs no API key or login. The `build`, `query`, `refine`, `compare`, and `chat` commands call an LLM to write CDC WONDER XML for you, so those need a key:
43
+ Querying any of the nine sources needs no API key or login. The `build`, `query`, `refine`, `compare`, and `chat` commands call an LLM to write CDC WONDER XML for you, so those need a key:
43
44
 
44
45
  ```bash
45
46
  export ANTHROPIC_API_KEY=sk-ant-...
@@ -54,7 +55,7 @@ Five top level commands. `topics` browses by subject across all sources, `source
54
55
  Start with a subject if you don't know which source holds what you want:
55
56
 
56
57
  ```bash
57
- pulse topics # every subject across all eight sources
58
+ pulse topics # every subject across all nine sources
58
59
  pulse topics mortality # drill into one
59
60
  pulse search "opioid overdose deaths by state"
60
61
  pulse search "tick-borne disease cases" --queries # queries only
@@ -118,6 +119,28 @@ pulse source dqs query nhis-adult --where "classification='Total'" --limit 500 -
118
119
 
119
120
  The unified query layer over CDC's [Data Query System](https://www.cdc.gov/nchs/dqs/) — the "Health, United States" report family drawn from NHANES, NHIS, NHAMCS, NVSS, NPALS, and NHCS. Every DQS topic is published as a Socrata dataset on data.cdc.gov sharing one tidy schema (`topic / classification / group / subgroup / estimate_type / time_period / estimate / lci / uci`), so a single query verb covers all 28. `classification = 'Total'` is the all-persons row; other classifications are demographic, geographic, or socioeconomic cuts. Fills in areas the other sources don't: chronic-disease and risk-factor prevalence, nutrition, oral health, disability, self-reported health, the health-care system (beds, ED visits, utilization), workforce, spending, and long-term care. Backed by the same Socrata client as `cdc-open`; set `CDC_DATA_APP_TOKEN` for a higher rate limit.
120
121
 
122
+ ### `pulse source sudors`: SUDORS Fatal Overdose Surveillance
123
+
124
+ ```bash
125
+ pulse source sudors list # 13 slices
126
+ pulse source sudors release # which release this is
127
+ pulse source sudors drugs -y 2024 -j Overall -f csv # drugs ruled as causing death
128
+ pulse source sudors drugs --detected -y 2024 -j Overall # xylazine, nitazenes, carfentanil, bromazolam
129
+ pulse source sudors circumstances -y 2024 -j Ohio --section Bystanders
130
+ pulse source sudors demographics -y 2024 -j Ohio -d race_ethnicity
131
+ pulse source sudors months -y 2024 -j Overall --drug fentanyl -f csv
132
+ pulse source sudors trend -r "2020 to 2024" -m alldrug_rate # the comparable series
133
+ pulse source sudors jurisdictions -y 2024
134
+ ```
135
+
136
+ CDC's [State Unintentional Drug Overdose Reporting System](https://www.cdc.gov/overdose-prevention/data-research/facts-stats/about-sudors.html) — death-investigation surveillance across 49 states and DC, abstracting >600 elements per death from the death certificate, the medical examiner/coroner report, and postmortem toxicology.
137
+
138
+ It answers what WONDER structurally cannot. ICD-10 puts every synthetic opioid but methadone in `T40.4`, so WONDER cannot separate illegally-made fentanyls from carfentanil or nitazene analogs, and xylazine and bromazolam have no code at all — SUDORS names each from toxicology. It also carries circumstances no death certificate holds: bystander present, naloxone administered, prior overdose, recent institutional release, route of use.
139
+
140
+ Two things to know. **The annual `Overall` row is not a time series** — a jurisdiction counts toward a year only if it reported every overdose death and had circumstance data on ≥75% of them, and that set changes annually (34 jurisdictions in 2020, 43 in 2024), so plotting it charts coverage as much as mortality; `trend` holds the jurisdiction set fixed instead. And **SUDORS will not reconcile with WONDER**, by design: its case definition adds a literal-text arm (`"overdose"`, `"toxicity"`, `"intoxication"`) on top of X40–X44 / Y10–Y14, and it counts occurrent rather than resident deaths.
141
+
142
+ There is no SUDORS API — these commands read the public dashboard's own JSON payloads, and CDC's workbook for the trend tables. Data years 2020–2024, restated annually.
143
+
121
144
  ### `pulse source wisqars`: Injury and Violence Data
122
145
 
123
146
  ```bash
@@ -1,21 +1,3 @@
1
- Metadata-Version: 2.4
2
- Name: pulse-code
3
- Version: 1.1.2
4
- Summary: CDC WONDER query CLI — explore, build, and refine public health data queries
5
- License-Expression: CC0-1.0
6
- Requires-Python: >=3.11
7
- Description-Content-Type: text/markdown
8
- License-File: LICENSE
9
- Requires-Dist: anthropic==1.1.0
10
- Requires-Dist: openai==3.5.0
11
- Requires-Dist: pydantic==2.13.4
12
- Requires-Dist: python-dotenv==1.2.3
13
- Requires-Dist: requests==2.34.2
14
- Requires-Dist: rich==15.0.0
15
- Requires-Dist: socksio==1.0.0
16
- Requires-Dist: typer==0.27.1
17
- Dynamic: license-file
18
-
19
1
  # Pulse
20
2
 
21
3
  [![PyPI](https://img.shields.io/pypi/v/pulse-code?style=for-the-badge)](https://pypi.org/project/pulse-code/)
@@ -24,7 +6,7 @@ Dynamic: license-file
24
6
  [![Pages](https://img.shields.io/github/actions/workflow/status/fartbagxp/pulse-code/pages.yml?style=for-the-badge&label=pages)](https://fartbagxp.github.io/pulse-code/)
25
7
  [![License](https://img.shields.io/badge/license-CC0--1.0-blue?style=for-the-badge)](LICENSE)
26
8
 
27
- `pulse` is a command line tool for querying public health data. It covers eight live sources: CDC WONDER, NCI SEER cancer statistics, CDC Open Data, the NCHS Data Query System (Health, United States), WISQARS injury data, ATSDR GRASP disease surveillance, NSSP ED visits, and NIS vaccination surveys. Browse them by topic, run bundled queries, and get CSV, JSON, or a table back.
9
+ `pulse` is a command line tool for querying public health data. It covers nine live sources: CDC WONDER, NCI SEER cancer statistics, CDC Open Data, the NCHS Data Query System (Health, United States), WISQARS injury data, ATSDR GRASP disease surveillance, NSSP ED visits, NIS vaccination surveys, and SUDORS fatal-overdose surveillance. Browse them by topic, run bundled queries, and get CSV, JSON, or a table back.
28
10
 
29
11
  ![pulse-code demo](docs/demo/pulse-demo.gif)
30
12
 
@@ -39,7 +21,7 @@ pulse --help
39
21
  uv run pulse --help
40
22
  ```
41
23
 
42
- Querying any of the eight sources needs no API key or login. The `build`, `query`, `refine`, `compare`, and `chat` commands call an LLM to write CDC WONDER XML for you, so those need a key:
24
+ Querying any of the nine sources needs no API key or login. The `build`, `query`, `refine`, `compare`, and `chat` commands call an LLM to write CDC WONDER XML for you, so those need a key:
43
25
 
44
26
  ```bash
45
27
  export ANTHROPIC_API_KEY=sk-ant-...
@@ -54,7 +36,7 @@ Five top level commands. `topics` browses by subject across all sources, `source
54
36
  Start with a subject if you don't know which source holds what you want:
55
37
 
56
38
  ```bash
57
- pulse topics # every subject across all eight sources
39
+ pulse topics # every subject across all nine sources
58
40
  pulse topics mortality # drill into one
59
41
  pulse search "opioid overdose deaths by state"
60
42
  pulse search "tick-borne disease cases" --queries # queries only
@@ -118,6 +100,28 @@ pulse source dqs query nhis-adult --where "classification='Total'" --limit 500 -
118
100
 
119
101
  The unified query layer over CDC's [Data Query System](https://www.cdc.gov/nchs/dqs/) — the "Health, United States" report family drawn from NHANES, NHIS, NHAMCS, NVSS, NPALS, and NHCS. Every DQS topic is published as a Socrata dataset on data.cdc.gov sharing one tidy schema (`topic / classification / group / subgroup / estimate_type / time_period / estimate / lci / uci`), so a single query verb covers all 28. `classification = 'Total'` is the all-persons row; other classifications are demographic, geographic, or socioeconomic cuts. Fills in areas the other sources don't: chronic-disease and risk-factor prevalence, nutrition, oral health, disability, self-reported health, the health-care system (beds, ED visits, utilization), workforce, spending, and long-term care. Backed by the same Socrata client as `cdc-open`; set `CDC_DATA_APP_TOKEN` for a higher rate limit.
120
102
 
103
+ ### `pulse source sudors`: SUDORS Fatal Overdose Surveillance
104
+
105
+ ```bash
106
+ pulse source sudors list # 13 slices
107
+ pulse source sudors release # which release this is
108
+ pulse source sudors drugs -y 2024 -j Overall -f csv # drugs ruled as causing death
109
+ pulse source sudors drugs --detected -y 2024 -j Overall # xylazine, nitazenes, carfentanil, bromazolam
110
+ pulse source sudors circumstances -y 2024 -j Ohio --section Bystanders
111
+ pulse source sudors demographics -y 2024 -j Ohio -d race_ethnicity
112
+ pulse source sudors months -y 2024 -j Overall --drug fentanyl -f csv
113
+ pulse source sudors trend -r "2020 to 2024" -m alldrug_rate # the comparable series
114
+ pulse source sudors jurisdictions -y 2024
115
+ ```
116
+
117
+ CDC's [State Unintentional Drug Overdose Reporting System](https://www.cdc.gov/overdose-prevention/data-research/facts-stats/about-sudors.html) — death-investigation surveillance across 49 states and DC, abstracting >600 elements per death from the death certificate, the medical examiner/coroner report, and postmortem toxicology.
118
+
119
+ It answers what WONDER structurally cannot. ICD-10 puts every synthetic opioid but methadone in `T40.4`, so WONDER cannot separate illegally-made fentanyls from carfentanil or nitazene analogs, and xylazine and bromazolam have no code at all — SUDORS names each from toxicology. It also carries circumstances no death certificate holds: bystander present, naloxone administered, prior overdose, recent institutional release, route of use.
120
+
121
+ Two things to know. **The annual `Overall` row is not a time series** — a jurisdiction counts toward a year only if it reported every overdose death and had circumstance data on ≥75% of them, and that set changes annually (34 jurisdictions in 2020, 43 in 2024), so plotting it charts coverage as much as mortality; `trend` holds the jurisdiction set fixed instead. And **SUDORS will not reconcile with WONDER**, by design: its case definition adds a literal-text arm (`"overdose"`, `"toxicity"`, `"intoxication"`) on top of X40–X44 / Y10–Y14, and it counts occurrent rather than resident deaths.
122
+
123
+ There is no SUDORS API — these commands read the public dashboard's own JSON payloads, and CDC's workbook for the trend tables. Data years 2020–2024, restated annually.
124
+
121
125
  ### `pulse source wisqars`: Injury and Violence Data
122
126
 
123
127
  ```bash
@@ -1,29 +1,30 @@
1
1
  [build-system]
2
- requires = ["setuptools==83.0.0"]
2
+ requires = ["setuptools==84.0.0"]
3
3
  build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "pulse-code"
7
- version = "1.1.2"
7
+ version = "1.1.4"
8
8
  description = "CDC WONDER query CLI — explore, build, and refine public health data queries"
9
9
  readme = "README.md"
10
10
  license = "CC0-1.0"
11
11
  requires-python = ">=3.11"
12
12
  dependencies = [
13
- "anthropic==1.1.0",
14
- "openai==3.5.0",
15
- "pydantic==2.13.4",
16
- "python-dotenv==1.2.3",
13
+ "anthropic==2.9.0",
14
+ "openai==3.51.0",
15
+ "openpyxl==3.1.5",
16
+ "pydantic==2.14.3",
17
+ "python-dotenv==1.2.4",
17
18
  "requests==2.34.2",
18
19
  "rich==15.0.0",
19
20
  "socksio==1.0.0",
20
- "typer==0.27.1",
21
+ "typer==0.29.1",
21
22
  ]
22
23
 
23
24
  [dependency-groups]
24
25
  dev = [
25
- "pre-commit==4.6.2",
26
- "pytest==9.1.1",
26
+ "pre-commit==4.7.0",
27
+ "pytest==9.2.0",
27
28
  ]
28
29
 
29
30
  [tool.setuptools.packages.find]
@@ -5,7 +5,6 @@ from __future__ import annotations
5
5
  import json
6
6
  from dataclasses import dataclass
7
7
  from pathlib import Path
8
- from typing import Optional
9
8
 
10
9
  _DATA_DIR = Path(__file__).parent / "data"
11
10
 
@@ -23,7 +22,7 @@ class Dataset:
23
22
  topic: str
24
23
  subject: str
25
24
  year_start: int
26
- year_end: Optional[int]
25
+ year_end: int | None
27
26
  year_range_label: str
28
27
  tags: list[str]
29
28
  measures: list[Measure]
@@ -83,7 +82,7 @@ class Catalog:
83
82
  def datasets(self) -> list[Dataset]:
84
83
  return list(self._datasets.values())
85
84
 
86
- def dataset(self, dataset_id: str) -> Optional[Dataset]:
85
+ def dataset(self, dataset_id: str) -> Dataset | None:
87
86
  return self._datasets.get(dataset_id.upper())
88
87
 
89
88
  def queries(self) -> list[BundledQuery]:
@@ -13,7 +13,6 @@ from __future__ import annotations
13
13
  import json
14
14
  from dataclasses import dataclass
15
15
  from pathlib import Path
16
- from typing import Optional
17
16
 
18
17
  _CATALOG_PATH = Path(__file__).parent / "data" / "cdc_open_catalog.json"
19
18
 
@@ -53,7 +52,7 @@ def datasets() -> list[CdcOpenDataset]:
53
52
  return list(_load().values())
54
53
 
55
54
 
56
- def dataset(key_or_id: str) -> Optional[CdcOpenDataset]:
55
+ def dataset(key_or_id: str) -> CdcOpenDataset | None:
57
56
  """Look up by registry key (e.g. 'leading_death') or Socrata ID (e.g. 'bi63-dtpu')."""
58
57
  by_key = _load()
59
58
  if key_or_id in by_key: