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.
- {pulse_code-1.1.2/src/pulse_code.egg-info → pulse_code-1.1.3}/PKG-INFO +31 -8
- pulse_code-1.1.2/PKG-INFO → pulse_code-1.1.3/README.md +25 -21
- {pulse_code-1.1.2 → pulse_code-1.1.3}/pyproject.toml +7 -6
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/cli.py +381 -4
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/sources_registry.py +20 -0
- pulse_code-1.1.3/src/pulse/sudors_catalog.py +238 -0
- pulse_code-1.1.3/src/pulse/sudors_sdk.py +520 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/topics_registry.py +1 -0
- pulse_code-1.1.2/README.md → pulse_code-1.1.3/src/pulse_code.egg-info/PKG-INFO +44 -3
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse_code.egg-info/SOURCES.txt +2 -0
- pulse_code-1.1.3/src/pulse_code.egg-info/requires.txt +9 -0
- pulse_code-1.1.2/src/pulse_code.egg-info/requires.txt +0 -8
- {pulse_code-1.1.2 → pulse_code-1.1.3}/LICENSE +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/setup.cfg +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/__init__.py +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/__main__.py +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/catalog.py +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/cdc_open_catalog.py +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/data/catalog.json +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/data/cdc_open_catalog.json +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/data/queries_index.json +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/data/seer_var_formats.json +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/data/variable_labels.json +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/dqs_catalog.py +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/dqs_sdk.py +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/grasp_catalog.py +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/grasp_client.py +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/grasp_sdk.py +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/llm_builder.py +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/matcher.py +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/nis_catalog.py +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/nis_parser.py +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/nis_sdk.py +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/nssp_client.py +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/nssp_sdk.py +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/aids-cases-by-age-1981-1999-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/aids-cases-by-location-1981-1999-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/aids-cases-by-race-1981-1999-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/aids-cases-by-sex-1981-1999-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/aids-cases-by-year-1981-1999-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/births-by-age-of-mother-2007-2024-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/births-by-race-2007-2024-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/births-by-year-1995-2002-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/births-by-year-2003-2006-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/births-by-year-2007-2024-req.xml +0 -0
- {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
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/cancer-incidence-by-state-1999-2022-req.xml +0 -0
- {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
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/cancer-mortality-by-state-2018-2023-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/covid-deaths-by-age-2020-2023-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/covid-deaths-by-age-sex-2020-2023-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/covid-deaths-by-race-2020-2023-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/covid-deaths-by-sex-2020-2023-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/deaths-by-place-of-death-2018-2024-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/drug-deaths-by-month-1999-2020-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/drug-deaths-by-month-2018-2024-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/drug-deaths-by-year-1999-2020-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/drug-deaths-by-year-2018-2024-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/fentanyl-deaths-by-month-1999-2020-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/fentanyl-deaths-by-month-2018-2024-req.xml +0 -0
- {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
- {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
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/fetal-deaths-by-race-2005-2024-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/fetal-deaths-by-year-2005-2024-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/heart-vs-cancer-by-sex-2018-2023-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/heat-wave-days-by-county-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/infant-mortality-2018-2023-req.xml +0 -0
- {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
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/maternal-mortality-by-race-2018-2024-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/maternal-mortality-by-year-1999-2020-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/maternal-mortality-by-year-2018-2024-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/mortality-by-race-sex-2018-2023-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/mortality-by-year-cause-1979-1998-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/mortality-by-year-cause-1999-2020-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/mortality-by-year-cause-2021-2024-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/opioid-deaths-by-age-2018-2024-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/opioid-deaths-by-sex-2018-2024-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/opioid-overdose-deaths-2018-2024-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/pm25-by-state-2003-2011-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/pm25-by-year-2003-2011-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/provisional-births-by-month-2023-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/racial-mortality-gap-2018-2023-req.xml +0 -0
- {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
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/std-cases-by-state-1984-2014-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/suicide-by-sex-1999-2020-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/suicide-by-sex-2021-2024-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/tb-cases-by-year-1993-2023-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/tick-borne-diseases-by-age-2016-2023-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/tick-borne-diseases-by-race-2016-2023-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/tick-borne-diseases-by-sex-2016-2023-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/tick-borne-diseases-by-state-2016-2023-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/tick-borne-diseases-by-year-2016-2023-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/underlying-cause-mortality-by-year-1999-2020-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/queries/unintentional-injuries-by-age-2018-2023-req.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/seer_catalog.py +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/seer_client.py +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/seer_sdk.py +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/soda_client.py +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D10-base.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D104-base.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D117-base.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D128-base.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D140-base.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D141-base.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D149-base.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D157-base.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D158-base.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D159-base.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D16-base.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D176-base.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D178-base.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D18-base.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D192-base.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D204-base.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D23-base.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D27-base.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D31-base.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D60-base.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D61-base.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D66-base.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D69-base.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D73-base.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D74-base.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D76-base.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D77-base.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D8-base.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D80-base.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/templates/D81-base.xml +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/wisqars_catalog.py +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/wisqars_sdk.py +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse/wonder_client.py +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse_code.egg-info/dependency_links.txt +0 -0
- {pulse_code-1.1.2 → pulse_code-1.1.3}/src/pulse_code.egg-info/entry_points.txt +0 -0
- {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.
|
|
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.
|
|
10
|
-
Requires-Dist: openai==3.
|
|
11
|
-
Requires-Dist:
|
|
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.
|
|
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
|
[](https://fartbagxp.github.io/pulse-code/)
|
|
25
26
|
[](LICENSE)
|
|
26
27
|
|
|
27
|
-
`pulse` is a command line tool for querying public health data. It covers
|
|
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
|

|
|
30
31
|
|
|
@@ -39,7 +40,7 @@ pulse --help
|
|
|
39
40
|
uv run pulse --help
|
|
40
41
|
```
|
|
41
42
|
|
|
42
|
-
Querying any of the
|
|
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
|
|
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
|
[](https://pypi.org/project/pulse-code/)
|
|
@@ -24,7 +6,7 @@ Dynamic: license-file
|
|
|
24
6
|
[](https://fartbagxp.github.io/pulse-code/)
|
|
25
7
|
[](LICENSE)
|
|
26
8
|
|
|
27
|
-
`pulse` is a command line tool for querying public health data. It covers
|
|
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
|

|
|
30
12
|
|
|
@@ -39,7 +21,7 @@ pulse --help
|
|
|
39
21
|
uv run pulse --help
|
|
40
22
|
```
|
|
41
23
|
|
|
42
|
-
Querying any of the
|
|
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
|
|
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==
|
|
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.
|
|
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.
|
|
14
|
-
"openai==3.
|
|
15
|
-
"
|
|
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.
|
|
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":
|
|
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")]
|