pulse-code 1.1.2__tar.gz → 1.1.3__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 (134) hide show
  1. {pulse_code-1.1.2/src/pulse_code.egg-info → pulse_code-1.1.3}/PKG-INFO +31 -8
  2. pulse_code-1.1.2/PKG-INFO → pulse_code-1.1.3/README.md +25 -21
  3. {pulse_code-1.1.2 → pulse_code-1.1.3}/pyproject.toml +7 -6
  4. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/cli.py +381 -4
  5. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/sources_registry.py +20 -0
  6. pulse_code-1.1.3/src/pulse/sudors_catalog.py +238 -0
  7. pulse_code-1.1.3/src/pulse/sudors_sdk.py +520 -0
  8. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/topics_registry.py +1 -0
  9. pulse_code-1.1.2/README.md → pulse_code-1.1.3/src/pulse_code.egg-info/PKG-INFO +44 -3
  10. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse_code.egg-info/SOURCES.txt +2 -0
  11. pulse_code-1.1.3/src/pulse_code.egg-info/requires.txt +9 -0
  12. pulse_code-1.1.2/src/pulse_code.egg-info/requires.txt +0 -8
  13. {pulse_code-1.1.2 → pulse_code-1.1.3}/LICENSE +0 -0
  14. {pulse_code-1.1.2 → pulse_code-1.1.3}/setup.cfg +0 -0
  15. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/__init__.py +0 -0
  16. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/__main__.py +0 -0
  17. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/catalog.py +0 -0
  18. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/cdc_open_catalog.py +0 -0
  19. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/data/catalog.json +0 -0
  20. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/data/cdc_open_catalog.json +0 -0
  21. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/data/queries_index.json +0 -0
  22. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/data/seer_var_formats.json +0 -0
  23. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/data/variable_labels.json +0 -0
  24. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/dqs_catalog.py +0 -0
  25. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/dqs_sdk.py +0 -0
  26. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/grasp_catalog.py +0 -0
  27. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/grasp_client.py +0 -0
  28. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/grasp_sdk.py +0 -0
  29. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/llm_builder.py +0 -0
  30. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/matcher.py +0 -0
  31. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/nis_catalog.py +0 -0
  32. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/nis_parser.py +0 -0
  33. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/nis_sdk.py +0 -0
  34. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/nssp_client.py +0 -0
  35. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/nssp_sdk.py +0 -0
  36. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/aids-cases-by-age-1981-1999-req.xml +0 -0
  37. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/aids-cases-by-location-1981-1999-req.xml +0 -0
  38. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/aids-cases-by-race-1981-1999-req.xml +0 -0
  39. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/aids-cases-by-sex-1981-1999-req.xml +0 -0
  40. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/aids-cases-by-year-1981-1999-req.xml +0 -0
  41. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/births-by-age-of-mother-2007-2024-req.xml +0 -0
  42. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/births-by-race-2007-2024-req.xml +0 -0
  43. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/births-by-year-1995-2002-req.xml +0 -0
  44. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/births-by-year-2003-2006-req.xml +0 -0
  45. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/births-by-year-2007-2024-req.xml +0 -0
  46. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/cancer-incidence-by-site-by-year-1999-2022-req.xml +0 -0
  47. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/cancer-incidence-by-state-1999-2022-req.xml +0 -0
  48. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/cancer-mortality-by-site-by-year-2018-2023-req.xml +0 -0
  49. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/cancer-mortality-by-state-2018-2023-req.xml +0 -0
  50. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/covid-deaths-by-age-2020-2023-req.xml +0 -0
  51. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/covid-deaths-by-age-sex-2020-2023-req.xml +0 -0
  52. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/covid-deaths-by-race-2020-2023-req.xml +0 -0
  53. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/covid-deaths-by-sex-2020-2023-req.xml +0 -0
  54. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/deaths-by-place-of-death-2018-2024-req.xml +0 -0
  55. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/drug-deaths-by-month-1999-2020-req.xml +0 -0
  56. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/drug-deaths-by-month-2018-2024-req.xml +0 -0
  57. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/drug-deaths-by-year-1999-2020-req.xml +0 -0
  58. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/drug-deaths-by-year-2018-2024-req.xml +0 -0
  59. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/fentanyl-deaths-by-month-1999-2020-req.xml +0 -0
  60. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/fentanyl-deaths-by-month-2018-2024-req.xml +0 -0
  61. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/fetal-deaths-by-age-of-mother-2005-2024-req.xml +0 -0
  62. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/fetal-deaths-by-cause-by-year-2014-2024-req.xml +0 -0
  63. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/fetal-deaths-by-race-2005-2024-req.xml +0 -0
  64. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/fetal-deaths-by-year-2005-2024-req.xml +0 -0
  65. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/heart-vs-cancer-by-sex-2018-2023-req.xml +0 -0
  66. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/heat-wave-days-by-county-req.xml +0 -0
  67. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/infant-mortality-2018-2023-req.xml +0 -0
  68. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/infant-mortality-by-cause-by-year-2007-2023-req.xml +0 -0
  69. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/maternal-mortality-by-race-2018-2024-req.xml +0 -0
  70. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/maternal-mortality-by-year-1999-2020-req.xml +0 -0
  71. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/maternal-mortality-by-year-2018-2024-req.xml +0 -0
  72. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/mortality-by-race-sex-2018-2023-req.xml +0 -0
  73. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/mortality-by-year-cause-1979-1998-req.xml +0 -0
  74. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/mortality-by-year-cause-1999-2020-req.xml +0 -0
  75. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/mortality-by-year-cause-2021-2024-req.xml +0 -0
  76. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/opioid-deaths-by-age-2018-2024-req.xml +0 -0
  77. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/opioid-deaths-by-sex-2018-2024-req.xml +0 -0
  78. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/opioid-overdose-deaths-2018-2024-req.xml +0 -0
  79. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/pm25-by-state-2003-2011-req.xml +0 -0
  80. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/pm25-by-year-2003-2011-req.xml +0 -0
  81. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/provisional-births-by-month-2023-req.xml +0 -0
  82. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/racial-mortality-gap-2018-2023-req.xml +0 -0
  83. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/std-cases-by-disease-by-year-1984-2014-req.xml +0 -0
  84. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/std-cases-by-state-1984-2014-req.xml +0 -0
  85. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/suicide-by-sex-1999-2020-req.xml +0 -0
  86. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/suicide-by-sex-2021-2024-req.xml +0 -0
  87. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/tb-cases-by-year-1993-2023-req.xml +0 -0
  88. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/tick-borne-diseases-by-age-2016-2023-req.xml +0 -0
  89. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/tick-borne-diseases-by-race-2016-2023-req.xml +0 -0
  90. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/tick-borne-diseases-by-sex-2016-2023-req.xml +0 -0
  91. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/tick-borne-diseases-by-state-2016-2023-req.xml +0 -0
  92. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/tick-borne-diseases-by-year-2016-2023-req.xml +0 -0
  93. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/underlying-cause-mortality-by-year-1999-2020-req.xml +0 -0
  94. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/unintentional-injuries-by-age-2018-2023-req.xml +0 -0
  95. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/seer_catalog.py +0 -0
  96. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/seer_client.py +0 -0
  97. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/seer_sdk.py +0 -0
  98. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/soda_client.py +0 -0
  99. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D10-base.xml +0 -0
  100. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D104-base.xml +0 -0
  101. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D117-base.xml +0 -0
  102. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D128-base.xml +0 -0
  103. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D140-base.xml +0 -0
  104. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D141-base.xml +0 -0
  105. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D149-base.xml +0 -0
  106. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D157-base.xml +0 -0
  107. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D158-base.xml +0 -0
  108. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D159-base.xml +0 -0
  109. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D16-base.xml +0 -0
  110. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D176-base.xml +0 -0
  111. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D178-base.xml +0 -0
  112. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D18-base.xml +0 -0
  113. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D192-base.xml +0 -0
  114. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D204-base.xml +0 -0
  115. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D23-base.xml +0 -0
  116. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D27-base.xml +0 -0
  117. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D31-base.xml +0 -0
  118. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D60-base.xml +0 -0
  119. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D61-base.xml +0 -0
  120. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D66-base.xml +0 -0
  121. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D69-base.xml +0 -0
  122. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D73-base.xml +0 -0
  123. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D74-base.xml +0 -0
  124. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D76-base.xml +0 -0
  125. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D77-base.xml +0 -0
  126. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D8-base.xml +0 -0
  127. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D80-base.xml +0 -0
  128. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D81-base.xml +0 -0
  129. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/wisqars_catalog.py +0 -0
  130. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/wisqars_sdk.py +0 -0
  131. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/wonder_client.py +0 -0
  132. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse_code.egg-info/dependency_links.txt +0 -0
  133. {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse_code.egg-info/entry_points.txt +0 -0
  134. {pulse_code-1.1.2 → pulse_code-1.1.3}/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.3
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
9
+ Requires-Dist: anthropic==1.4.0
10
+ Requires-Dist: openai==3.11.0
11
+ Requires-Dist: openpyxl==3.1.5
12
+ Requires-Dist: pydantic==2.13.5
12
13
  Requires-Dist: python-dotenv==1.2.3
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.27.2
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,23 +1,24 @@
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.3"
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",
13
+ "anthropic==1.4.0",
14
+ "openai==3.11.0",
15
+ "openpyxl==3.1.5",
16
+ "pydantic==2.13.5",
16
17
  "python-dotenv==1.2.3",
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.27.2",
21
22
  ]
22
23
 
23
24
  [dependency-groups]
@@ -59,6 +59,28 @@ from pulse.seer_sdk import (
59
59
  )
60
60
  from pulse.soda_client import SodaClient
61
61
  from pulse.sources_registry import SOURCE_DATASET_FNS
62
+ from pulse.sudors_catalog import ABOUT_URL as SUDORS_ABOUT_URL
63
+ from pulse.sudors_catalog import BASE_URL as SUDORS_BASE_URL
64
+ from pulse.sudors_catalog import CODING_MANUAL_URL as SUDORS_CODING_MANUAL_URL
65
+ from pulse.sudors_catalog import DASHBOARD_URL as SUDORS_DASHBOARD_URL
66
+ from pulse.sudors_catalog import dataset as sudors_dataset
67
+ from pulse.sudors_catalog import datasets as sudors_datasets
68
+ from pulse.sudors_catalog import search as sudors_search
69
+ from pulse.sudors_sdk import LOADERS as SUDORS_LOADERS
70
+ from pulse.sudors_sdk import USER_AGENT as SUDORS_USER_AGENT
71
+ from pulse.sudors_sdk import (
72
+ SudorsError,
73
+ filter_rows,
74
+ get_circumstances,
75
+ get_deaths_by_month,
76
+ get_demographics,
77
+ get_drugs_detected,
78
+ get_drugs_involved,
79
+ get_release,
80
+ get_trend,
81
+ get_trend_statistics,
82
+ )
83
+ from pulse.sudors_sdk import jurisdictions as sudors_jurisdictions
62
84
  from pulse.topics_registry import TOPICS, find_topic
63
85
  from pulse.wisqars_catalog import DATASETS as WISQARS_DATASETS
64
86
  from pulse.wisqars_catalog import INJURY_INTENTS, INJURY_MECHANISMS, MAPPING_INTENTS, MAPPING_PERIOD_TYPES
@@ -238,6 +260,12 @@ nis_app = typer.Typer(
238
260
  no_args_is_help=False,
239
261
  invoke_without_command=True,
240
262
  )
263
+ sudors_app = typer.Typer(
264
+ help="SUDORS fatal overdose surveillance — drugs from toxicology, plus death circumstances.",
265
+ add_completion=False,
266
+ no_args_is_help=False,
267
+ invoke_without_command=True,
268
+ )
241
269
  app.add_typer(source_app, name="source")
242
270
  source_app.add_typer(wonder_app, name="wonder")
243
271
  source_app.add_typer(seer_app, name="seer")
@@ -250,6 +278,7 @@ grasp_app.add_typer(grasp_fluview_app, name="fluview")
250
278
  grasp_app.add_typer(grasp_flusurv_app, name="flusurv")
251
279
  source_app.add_typer(nssp_app, name="nssp")
252
280
  source_app.add_typer(nis_app, name="nis")
281
+ source_app.add_typer(sudors_app, name="sudors")
253
282
  console = Console()
254
283
  err = Console(stderr=True)
255
284
 
@@ -1262,6 +1291,13 @@ def _render_source_overview(json_out: bool) -> None:
1262
1291
  "count": 2,
1263
1292
  "years": "2011–2022",
1264
1293
  },
1294
+ {
1295
+ "name": "SUDORS",
1296
+ "command": "pulse source sudors drugs / circumstances / demographics / months / trend",
1297
+ "coverage": "Fatal overdose detail from toxicology & death investigations — drugs ICD-10 cannot name",
1298
+ "count": len(sudors_datasets()),
1299
+ "years": "2020–2024",
1300
+ },
1265
1301
  ]
1266
1302
 
1267
1303
  if json_out:
@@ -1325,6 +1361,16 @@ def cdc_open_callback(
1325
1361
  _render_source_datasets("cdc-open", json_out)
1326
1362
 
1327
1363
 
1364
+ @sudors_app.callback(invoke_without_command=True)
1365
+ def sudors_callback(
1366
+ ctx: typer.Context,
1367
+ json_out: Annotated[bool, typer.Option("--json")] = False,
1368
+ ):
1369
+ """Bare `pulse source sudors` lists SUDORS' slices; subcommands query them."""
1370
+ if ctx.invoked_subcommand is None:
1371
+ _render_source_datasets("sudors", json_out)
1372
+
1373
+
1328
1374
  @dqs_app.callback(invoke_without_command=True)
1329
1375
  def dqs_callback(
1330
1376
  ctx: typer.Context,
@@ -1390,17 +1436,25 @@ _DOCTOR_ENDPOINTS = [
1390
1436
  # not the legacy path's .sas — that split is what nis_catalog.py now
1391
1437
  # routes on via NISYear.format_type.
1392
1438
  ("NIS", "https://ftp.cdc.gov/pub/VACCINES_NIS/NISPUF22.R"),
1439
+ # SUDORS has no API — a real dashboard payload is the only thing to probe, and
1440
+ # a 404 here is exactly the signal that matters: it means CDC moved or renamed
1441
+ # the dashboard's data path out from under us. www.cdc.gov 403s the default
1442
+ # probe agent, so this row asks under the same UA the SDK uses; a 403 here
1443
+ # would then be a real regression rather than the usual noise. (WONDER is the
1444
+ # mirror image — it 403s the probe agent but 500s under the SDK's — so it
1445
+ # keeps the default.)
1446
+ ("SUDORS", f"{SUDORS_BASE_URL}/footnotes-text.json", SUDORS_USER_AGENT),
1393
1447
  ]
1394
1448
 
1395
1449
 
1396
- def _check_url(url: str, timeout: float = 8.0) -> tuple[bool, str]:
1450
+ def _check_url(url: str, timeout: float = 8.0, user_agent: str = "pulse-doctor") -> tuple[bool, str]:
1397
1451
  import time
1398
1452
 
1399
1453
  import requests
1400
1454
 
1401
1455
  start = time.monotonic()
1402
1456
  try:
1403
- resp = requests.get(url, timeout=timeout, headers={"User-Agent": "pulse-doctor"})
1457
+ resp = requests.get(url, timeout=timeout, headers={"User-Agent": user_agent})
1404
1458
  elapsed = (time.monotonic() - start) * 1000
1405
1459
  # A 404 means the specific resource moved/vanished (a real break, as
1406
1460
  # opposed to e.g. a 403 on a root path that just wants different
@@ -1442,8 +1496,8 @@ def cmd_doctor():
1442
1496
 
1443
1497
  console.print("[dim]Checking live reachability of each source (~5-10s)…[/dim]")
1444
1498
  all_reachable = True
1445
- for name, url in _DOCTOR_ENDPOINTS:
1446
- ok, detail = _check_url(url)
1499
+ for name, url, *rest in _DOCTOR_ENDPOINTS:
1500
+ ok, detail = _check_url(url, user_agent=rest[0]) if rest else _check_url(url)
1447
1501
  all_reachable = all_reachable and ok
1448
1502
  t.add_row(name, "[green]OK[/green]" if ok else "[red]FAIL[/red]", detail)
1449
1503
 
@@ -1974,6 +2028,329 @@ def cmd_dqs_trend(
1974
2028
  _print_rows(rows, format, output)
1975
2029
 
1976
2030
 
2031
+ # ── sudors ────────────────────────────────────────────────────────────────────
2032
+ #
2033
+ # SUDORS has no API. Every command here reads the public dashboard's own JSON
2034
+ # payloads (and, for `trend`, CDC's workbook) and reshapes them to flat rows, so
2035
+ # the numbers are always the live release rather than a snapshot pinned in this
2036
+ # repo.
2037
+
2038
+
2039
+ def _sudors_render(rows: list[dict], format, output) -> None:
2040
+ """Render SUDORS rows, pointing at the usual cause when a filter empties them."""
2041
+ if not rows:
2042
+ err.print(
2043
+ "[yellow]No rows matched.[/yellow] Jurisdictions differ by year — "
2044
+ "try [bold]pulse source sudors jurisdictions --year <year>[/bold]."
2045
+ )
2046
+ raise typer.Exit(1)
2047
+ _print_rows(rows, format, output)
2048
+
2049
+
2050
+ def _sudors_rows(fn, year, jurisdiction, limit, format, output) -> None:
2051
+ """Fetch, narrow, and render — the shape every SUDORS query command shares."""
2052
+ try:
2053
+ rows = filter_rows(fn(), year=year, jurisdiction=jurisdiction, limit=limit)
2054
+ except SudorsError as e:
2055
+ err.print(f"[red]Error from CDC SUDORS:[/red] {e}")
2056
+ raise typer.Exit(1)
2057
+ _sudors_render(rows, format, output)
2058
+
2059
+
2060
+ @sudors_app.command("list")
2061
+ def cmd_sudors_list(
2062
+ search: Annotated[Optional[str], typer.Option("--search", "-s", help="Substring match on key/name/grain/description")] = None,
2063
+ json_out: Annotated[bool, typer.Option("--json")] = False,
2064
+ ):
2065
+ """List/search the SUDORS slices this CLI can pull."""
2066
+ ds = sudors_search(search) if search else sudors_datasets()
2067
+
2068
+ if json_out:
2069
+ print(
2070
+ json.dumps(
2071
+ [
2072
+ {
2073
+ "key": d.key,
2074
+ "name": d.name,
2075
+ "topic": d.topic,
2076
+ "grain": d.grain,
2077
+ "sources": list(d.sources),
2078
+ "workbook": d.workbook,
2079
+ "description": d.description,
2080
+ }
2081
+ for d in ds
2082
+ ],
2083
+ indent=2,
2084
+ )
2085
+ )
2086
+ return
2087
+
2088
+ t = Table(box=box.ROUNDED, show_header=True, header_style="bold cyan", expand=True)
2089
+ t.add_column("Key", style="yellow", width=24, no_wrap=True)
2090
+ t.add_column("Name", width=38)
2091
+ t.add_column("Grain", ratio=1)
2092
+ t.add_column("From", width=9, no_wrap=True)
2093
+ for d in ds:
2094
+ t.add_row(d.key, d.name, d.grain, "workbook" if d.workbook else "json")
2095
+
2096
+ console.print()
2097
+ console.print(t)
2098
+ console.print(
2099
+ f"\n[dim]{len(ds)} slices | [bold]pulse source sudors get <key>[/bold] for any of them | "
2100
+ f"[bold]drugs / circumstances / demographics / months / trend[/bold] for the shortcuts[/dim]\n"
2101
+ )
2102
+
2103
+
2104
+ @sudors_app.command("drugs")
2105
+ def cmd_sudors_drugs(
2106
+ detected: Annotated[
2107
+ bool,
2108
+ typer.Option(
2109
+ "--detected",
2110
+ help="Drugs found on toxicology (xylazine, nitazenes, carfentanil...) instead of drugs ruled as causing death",
2111
+ ),
2112
+ ] = False,
2113
+ year: Annotated[Optional[int], typer.Option("--year", "-y", help="Data year")] = None,
2114
+ jurisdiction: Annotated[Optional[str], typer.Option("--jurisdiction", "-j", help="State name, or 'Overall'")] = None,
2115
+ limit: Annotated[Optional[int], typer.Option("--limit")] = None,
2116
+ format: Annotated[str, typer.Option("-f", "--format")] = "table",
2117
+ output: Annotated[Optional[Path], typer.Option("-o", "--output")] = None,
2118
+ ):
2119
+ """
2120
+ Drugs involved in overdose deaths.
2121
+
2122
+ By default, the drug classes a medical examiner or coroner ruled as causing
2123
+ death. With --detected, the drugs postmortem toxicology found whether or not
2124
+ they were ruled a cause — the cut ICD-10 cannot express, since T40.4 collapses
2125
+ every synthetic opioid but methadone into one code and xylazine has none.
2126
+ """
2127
+ _sudors_rows(get_drugs_detected if detected else get_drugs_involved, year, jurisdiction, limit, format, output)
2128
+
2129
+
2130
+ @sudors_app.command("circumstances")
2131
+ def cmd_sudors_circumstances(
2132
+ section: Annotated[Optional[str], typer.Option("--section", help="Substring match on the circumstance section")] = None,
2133
+ year: Annotated[Optional[int], typer.Option("--year", "-y")] = None,
2134
+ jurisdiction: Annotated[Optional[str], typer.Option("--jurisdiction", "-j", help="State name, or 'Overall'")] = None,
2135
+ limit: Annotated[Optional[int], typer.Option("--limit")] = None,
2136
+ format: Annotated[str, typer.Option("-f", "--format")] = "table",
2137
+ output: Annotated[Optional[Path], typer.Option("-o", "--output")] = None,
2138
+ ):
2139
+ """
2140
+ Circumstances surrounding the death — what SUDORS exists for.
2141
+
2142
+ Bystander present, naloxone administered, prior overdose, recent release from
2143
+ an institutional setting, route of use, current SUD treatment. None of it is
2144
+ on a death certificate, so none of it is in WONDER. Percentages are among
2145
+ decedents with known information and are floor estimates.
2146
+ """
2147
+ try:
2148
+ rows = filter_rows(get_circumstances(), year=year, jurisdiction=jurisdiction)
2149
+ except SudorsError as e:
2150
+ err.print(f"[red]Error from CDC SUDORS:[/red] {e}")
2151
+ raise typer.Exit(1)
2152
+ if section:
2153
+ want = section.strip().lower()
2154
+ rows = [r for r in rows if want in (r.get("section") or "").lower()]
2155
+ if limit:
2156
+ rows = rows[:limit]
2157
+ _sudors_render(rows, format, output)
2158
+
2159
+
2160
+ @sudors_app.command("demographics")
2161
+ def cmd_sudors_demographics(
2162
+ dimension: Annotated[Optional[str], typer.Option("--dimension", "-d", help="One of: sex, age, race_ethnicity")] = None,
2163
+ year: Annotated[Optional[int], typer.Option("--year", "-y")] = None,
2164
+ jurisdiction: Annotated[Optional[str], typer.Option("--jurisdiction", "-j", help="State name, or 'Overall'")] = None,
2165
+ limit: Annotated[Optional[int], typer.Option("--limit")] = None,
2166
+ format: Annotated[str, typer.Option("-f", "--format")] = "table",
2167
+ output: Annotated[Optional[Path], typer.Option("-o", "--output")] = None,
2168
+ ):
2169
+ """
2170
+ Deaths by sex, age band, and race/ethnicity.
2171
+
2172
+ Sex and race/ethnicity rates are age-standardized to the 2010 U.S. Census;
2173
+ age-band rates are crude. Census switched to differential privacy for 2021
2174
+ population estimates, so 2021+ rates are not strictly comparable to 2020.
2175
+ """
2176
+ try:
2177
+ rows = filter_rows(get_demographics(), year=year, jurisdiction=jurisdiction)
2178
+ except SudorsError as e:
2179
+ err.print(f"[red]Error from CDC SUDORS:[/red] {e}")
2180
+ raise typer.Exit(1)
2181
+ if dimension:
2182
+ want = dimension.strip().lower()
2183
+ rows = [r for r in rows if r.get("dimension") == want]
2184
+ if not rows:
2185
+ err.print("[yellow]Unknown --dimension.[/yellow] Use one of: sex, age, race_ethnicity.")
2186
+ raise typer.Exit(1)
2187
+ if limit:
2188
+ rows = rows[:limit]
2189
+ _sudors_render(rows, format, output)
2190
+
2191
+
2192
+ @sudors_app.command("months")
2193
+ def cmd_sudors_months(
2194
+ drug: Annotated[Optional[str], typer.Option("--drug", help="Substring match on the drug class")] = None,
2195
+ year: Annotated[Optional[int], typer.Option("--year", "-y")] = None,
2196
+ jurisdiction: Annotated[Optional[str], typer.Option("--jurisdiction", "-j", help="State name, or 'Overall'")] = None,
2197
+ limit: Annotated[Optional[int], typer.Option("--limit")] = None,
2198
+ format: Annotated[str, typer.Option("-f", "--format")] = "table",
2199
+ output: Annotated[Optional[Path], typer.Option("-o", "--output")] = None,
2200
+ ):
2201
+ """Monthly death counts by drug class — SUDORS' only sub-annual cut."""
2202
+ try:
2203
+ rows = filter_rows(get_deaths_by_month(), year=year, jurisdiction=jurisdiction)
2204
+ except SudorsError as e:
2205
+ err.print(f"[red]Error from CDC SUDORS:[/red] {e}")
2206
+ raise typer.Exit(1)
2207
+ if drug:
2208
+ want = drug.strip().lower()
2209
+ rows = [r for r in rows if want in (r.get("drug") or "").lower()]
2210
+ if limit:
2211
+ rows = rows[:limit]
2212
+ _sudors_render(rows, format, output)
2213
+
2214
+
2215
+ @sudors_app.command("trend")
2216
+ def cmd_sudors_trend(
2217
+ measure: Annotated[Optional[str], typer.Option("--measure", "-m", help="Substring match on the measure name, e.g. imfs_rate")] = None,
2218
+ trend_range: Annotated[Optional[str], typer.Option("--range", "-r", help="e.g. '2020 to 2024'")] = None,
2219
+ statistics: Annotated[
2220
+ bool, typer.Option("--statistics", help="First-to-last-year change per jurisdiction instead of the year series")
2221
+ ] = False,
2222
+ scope: Annotated[
2223
+ str, typer.Option("--scope", help="'chart' (jurisdictions in every year) or 'map' (first and last only), or 'all'")
2224
+ ] = "chart",
2225
+ jurisdiction: Annotated[Optional[str], typer.Option("--jurisdiction", "-j", help="Narrow to one jurisdiction")] = None,
2226
+ limit: Annotated[Optional[int], typer.Option("--limit")] = None,
2227
+ format: Annotated[str, typer.Option("-f", "--format")] = "table",
2228
+ output: Annotated[Optional[Path], typer.Option("-o", "--output")] = None,
2229
+ ):
2230
+ """
2231
+ The cross-year-comparable series — the only SUDORS table safe to plot over time.
2232
+
2233
+ The annual `Overall` row is a different set of jurisdictions every year
2234
+ (34 in 2020, 43 in 2024), so plotting it charts coverage as much as mortality.
2235
+ Each trend range here instead holds its jurisdictions fixed across every year
2236
+ in it. `measure` joins against `pulse source sudors get data-dictionary`.
2237
+
2238
+ CDC publishes two aggregates per range. The default --scope chart is the
2239
+ strict one behind the line and bar views; --scope map relaxes inclusion to the
2240
+ first and last year (what the choropleths use) and so must not be plotted as a
2241
+ series. --scope all returns both.
2242
+ """
2243
+ try:
2244
+ rows = get_trend_statistics() if statistics else get_trend()
2245
+ except SudorsError as e:
2246
+ err.print(f"[red]Error from CDC SUDORS:[/red] {e}")
2247
+ raise typer.Exit(1)
2248
+
2249
+ if scope != "all":
2250
+ rows = [r for r in rows if r.get("scope") == scope]
2251
+ if trend_range:
2252
+ want = trend_range.strip().lower()
2253
+ rows = [r for r in rows if want in (r.get("trend_range") or "").lower()]
2254
+ if jurisdiction:
2255
+ want = jurisdiction.strip().lower()
2256
+ rows = [r for r in rows if want in (r.get("jurisdiction") or "").lower()]
2257
+ if measure:
2258
+ want = measure.strip().lower()
2259
+ rows = [r for r in rows if want in (r.get("measure") or "").lower()]
2260
+ if limit:
2261
+ rows = rows[:limit]
2262
+
2263
+ if not rows:
2264
+ err.print(
2265
+ "[yellow]No rows matched.[/yellow] Ranges are '2020 to 2024', '2021 to 2024', "
2266
+ "'2022 to 2024', '2023 to 2024'; measures look like alldrug_deaths, imfs_rate, xylazine_percent."
2267
+ )
2268
+ raise typer.Exit(1)
2269
+ _print_rows(rows, format, output)
2270
+
2271
+
2272
+ @sudors_app.command("jurisdictions")
2273
+ def cmd_sudors_jurisdictions(
2274
+ year: Annotated[Optional[int], typer.Option("--year", "-y", help="Only jurisdictions reporting that year")] = None,
2275
+ json_out: Annotated[bool, typer.Option("--json")] = False,
2276
+ ):
2277
+ """
2278
+ Which jurisdictions reported, for a year or across the whole release.
2279
+
2280
+ Inclusion requires reporting every overdose death that year and having
2281
+ circumstance data on at least 75% of them, so the list changes annually.
2282
+ """
2283
+ try:
2284
+ names = sudors_jurisdictions(year)
2285
+ except SudorsError as e:
2286
+ err.print(f"[red]Error from CDC SUDORS:[/red] {e}")
2287
+ raise typer.Exit(1)
2288
+
2289
+ if json_out:
2290
+ print(json.dumps(names, indent=2))
2291
+ return
2292
+
2293
+ label = f"reporting in {year}" if year else "in the release"
2294
+ console.print(f"\n[bold]{len(names)} jurisdictions[/bold] {label} [dim](includes the combined 'Overall' row)[/dim]\n")
2295
+ for name in names:
2296
+ console.print(f" • {name}")
2297
+ console.print()
2298
+
2299
+
2300
+ @sudors_app.command("get")
2301
+ def cmd_sudors_get(
2302
+ key: Annotated[str, typer.Argument(help="Registry key — see `pulse source sudors list`")],
2303
+ year: Annotated[Optional[int], typer.Option("--year", "-y")] = None,
2304
+ jurisdiction: Annotated[Optional[str], typer.Option("--jurisdiction", "-j")] = None,
2305
+ limit: Annotated[Optional[int], typer.Option("--limit")] = None,
2306
+ format: Annotated[str, typer.Option("-f", "--format")] = "table",
2307
+ output: Annotated[Optional[Path], typer.Option("-o", "--output")] = None,
2308
+ ):
2309
+ """Pull any registered slice by key, including the ones without a shortcut command."""
2310
+ loader = SUDORS_LOADERS.get(key)
2311
+ if loader is None:
2312
+ err.print(f"[red]Unknown slice:[/red] {key}")
2313
+ err.print(f"[dim]Available: {', '.join(SUDORS_LOADERS)}[/dim]")
2314
+ raise typer.Exit(1)
2315
+ ds = sudors_dataset(key)
2316
+ if ds:
2317
+ err.print(f"[bold]{ds.name}[/bold] [dim]({ds.grain})[/dim]")
2318
+ _sudors_rows(loader, year, jurisdiction, limit, format, output)
2319
+
2320
+
2321
+ @sudors_app.command("release")
2322
+ def cmd_sudors_release(
2323
+ json_out: Annotated[bool, typer.Option("--json")] = False,
2324
+ ):
2325
+ """Which release this is: the data-entry cutoff and the newest final data year."""
2326
+ try:
2327
+ info = get_release()
2328
+ except SudorsError as e:
2329
+ err.print(f"[red]Error from CDC SUDORS:[/red] {e}")
2330
+ raise typer.Exit(1)
2331
+
2332
+ if json_out:
2333
+ print(json.dumps(info, indent=2))
2334
+ return
2335
+
2336
+ console.print(
2337
+ Panel(
2338
+ f"[bold]Data-entry cutoff:[/bold] {info['data_entry_cutoff']}\n"
2339
+ f"[bold]Newest final data year:[/bold] {info['latest_data_year']}\n"
2340
+ f"[bold]Deaths in decedent's own jurisdiction:[/bold] {info['pct_deaths_in_residence_jurisdiction']}\n"
2341
+ f"[bold]IMF deaths toxicology-confirmed:[/bold] {info['pct_imf_deaths_toxicology_confirmed']}\n\n"
2342
+ f"[dim]Anything entered after the cutoff is not in this release, so a jurisdiction's own\n"
2343
+ f"dashboard may report more recent numbers. SUDORS restates annually.[/dim]\n\n"
2344
+ f"[dim]Dashboard: {SUDORS_DASHBOARD_URL}\n"
2345
+ f"About: {SUDORS_ABOUT_URL}\n"
2346
+ f"Coding manual: {SUDORS_CODING_MANUAL_URL}[/dim]",
2347
+ title="SUDORS release",
2348
+ border_style="cyan",
2349
+ box=box.ROUNDED,
2350
+ )
2351
+ )
2352
+
2353
+
1977
2354
  # ── wisqars ───────────────────────────────────────────────────────────────────
1978
2355
 
1979
2356
  _WISQARS_FORMAT = Annotated[str, typer.Option("-f", "--format", help="table|csv|json")]