pulse-code 1.0.1__tar.gz → 1.1.0__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.0/PKG-INFO +355 -0
- pulse_code-1.1.0/README.md +337 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/pyproject.toml +6 -5
- pulse_code-1.1.0/src/pulse/cdc_open_catalog.py +74 -0
- pulse_code-1.1.0/src/pulse/cli.py +2313 -0
- pulse_code-1.1.0/src/pulse/data/cdc_open_catalog.json +1089 -0
- pulse_code-1.1.0/src/pulse/data/seer_var_formats.json +631 -0
- pulse_code-1.1.0/src/pulse/grasp_catalog.py +145 -0
- pulse_code-1.1.0/src/pulse/grasp_client.py +124 -0
- pulse_code-1.1.0/src/pulse/grasp_sdk.py +334 -0
- pulse_code-1.1.0/src/pulse/nis_catalog.py +242 -0
- pulse_code-1.1.0/src/pulse/nis_parser.py +147 -0
- pulse_code-1.1.0/src/pulse/nis_sdk.py +272 -0
- pulse_code-1.1.0/src/pulse/nssp_client.py +103 -0
- pulse_code-1.1.0/src/pulse/nssp_sdk.py +130 -0
- pulse_code-1.1.0/src/pulse/seer_catalog.py +107 -0
- pulse_code-1.1.0/src/pulse/seer_client.py +77 -0
- pulse_code-1.1.0/src/pulse/seer_sdk.py +250 -0
- pulse_code-1.1.0/src/pulse/soda_client.py +84 -0
- pulse_code-1.1.0/src/pulse/sources_registry.py +143 -0
- pulse_code-1.1.0/src/pulse/topics_registry.py +208 -0
- pulse_code-1.1.0/src/pulse/wisqars_catalog.py +150 -0
- pulse_code-1.1.0/src/pulse/wisqars_sdk.py +221 -0
- pulse_code-1.1.0/src/pulse_code.egg-info/PKG-INFO +355 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse_code.egg-info/SOURCES.txt +19 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse_code.egg-info/requires.txt +3 -3
- pulse_code-1.0.1/PKG-INFO +0 -249
- pulse_code-1.0.1/README.md +0 -232
- pulse_code-1.0.1/src/pulse/cli.py +0 -984
- pulse_code-1.0.1/src/pulse_code.egg-info/PKG-INFO +0 -249
- {pulse_code-1.0.1 → pulse_code-1.1.0}/LICENSE +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/setup.cfg +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/__init__.py +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/__main__.py +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/catalog.py +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/data/catalog.json +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/data/queries_index.json +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/data/variable_labels.json +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/llm_builder.py +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/matcher.py +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/aids-cases-by-year-1981-1999-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/births-by-year-1995-2002-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/births-by-year-2003-2006-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/births-by-year-2007-2024-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/cancer-incidence-by-site-by-year-1999-2022-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/cancer-mortality-by-site-by-year-2018-2023-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/covid-deaths-by-race-2020-2023-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/drug-deaths-by-month-1999-2020-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/drug-deaths-by-month-2018-2024-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/drug-deaths-by-year-1999-2020-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/drug-deaths-by-year-2018-2024-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/fentanyl-deaths-by-month-1999-2020-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/fentanyl-deaths-by-month-2018-2024-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/fetal-deaths-by-cause-by-year-2014-2024-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/fetal-deaths-by-year-2005-2024-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/heart-vs-cancer-by-sex-2018-2023-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/heat-wave-days-by-county-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/infant-mortality-2018-2023-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/infant-mortality-by-cause-by-year-2007-2023-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/maternal-mortality-by-year-1999-2020-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/maternal-mortality-by-year-2018-2024-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/mortality-by-race-sex-2018-2023-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/mortality-by-year-cause-1979-1998-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/mortality-by-year-cause-1999-2020-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/mortality-by-year-cause-2021-2024-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/opioid-overdose-deaths-2018-2024-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/pm25-by-year-2003-2011-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/provisional-births-by-month-2023-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/racial-mortality-gap-2018-2023-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/std-cases-by-disease-by-year-1984-2014-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/suicide-by-sex-1999-2020-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/suicide-by-sex-2021-2024-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/tb-cases-by-year-1993-2023-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/tick-borne-diseases-by-year-2016-2023-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/underlying-cause-mortality-by-year-1999-2020-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/queries/unintentional-injuries-by-age-2018-2023-req.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/templates/D10-base.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/templates/D104-base.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/templates/D117-base.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/templates/D128-base.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/templates/D140-base.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/templates/D141-base.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/templates/D149-base.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/templates/D157-base.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/templates/D158-base.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/templates/D159-base.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/templates/D16-base.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/templates/D176-base.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/templates/D178-base.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/templates/D18-base.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/templates/D192-base.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/templates/D204-base.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/templates/D23-base.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/templates/D27-base.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/templates/D31-base.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/templates/D60-base.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/templates/D61-base.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/templates/D66-base.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/templates/D69-base.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/templates/D73-base.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/templates/D74-base.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/templates/D76-base.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/templates/D77-base.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/templates/D8-base.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/templates/D80-base.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/templates/D81-base.xml +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse/wonder_client.py +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse_code.egg-info/dependency_links.txt +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse_code.egg-info/entry_points.txt +0 -0
- {pulse_code-1.0.1 → pulse_code-1.1.0}/src/pulse_code.egg-info/top_level.txt +0 -0
|
@@ -0,0 +1,355 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: pulse-code
|
|
3
|
+
Version: 1.1.0
|
|
4
|
+
Summary: CDC WONDER query CLI — explore, build, and refine public health data queries
|
|
5
|
+
License-Expression: CC0-1.0
|
|
6
|
+
Requires-Python: >=3.14
|
|
7
|
+
Description-Content-Type: text/markdown
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Requires-Dist: anthropic==0.120.2
|
|
10
|
+
Requires-Dist: openai==2.50.0
|
|
11
|
+
Requires-Dist: pydantic==2.13.4
|
|
12
|
+
Requires-Dist: python-dotenv==1.2.2
|
|
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.0
|
|
17
|
+
Dynamic: license-file
|
|
18
|
+
|
|
19
|
+
# Pulse
|
|
20
|
+
|
|
21
|
+
[](https://pypi.org/project/pulse-code/)
|
|
22
|
+
[](https://pypi.org/project/pulse-code/)
|
|
23
|
+
[](https://github.com/fartbagxp/pulse-code/actions/workflows/publish.yml)
|
|
24
|
+
[](https://fartbagxp.github.io/pulse-code/)
|
|
25
|
+
[](LICENSE)
|
|
26
|
+
|
|
27
|
+
CDC public health data query CLI. Explore datasets, run bundled queries, and use Claude to build and refine custom XML queries — across CDC WONDER, NCI SEER cancer statistics, CDC Open Data, WISQARS injury data, ATSDR GRASP disease surveillance, NSSP ED visits, and NIS vaccination surveys.
|
|
28
|
+
|
|
29
|
+
## What is this?
|
|
30
|
+
|
|
31
|
+

|
|
32
|
+
|
|
33
|
+
[CDC WONDER](https://wonder.cdc.gov/) (Wide-ranging ONline Data for Epidemiologic Research) is the government's primary interface for public health statistics: drug overdose deaths, maternal mortality, birth rates, COVID deaths by race, suicide trends, vaccine adverse events, and much more. Its XML API is powerful but opaque.
|
|
34
|
+
|
|
35
|
+
`pulse` makes it usable:
|
|
36
|
+
|
|
37
|
+
- **Explore** all datasets with clear descriptions of what they cover and when
|
|
38
|
+
- **Search** by topic to find the right dataset or a working example query
|
|
39
|
+
- **Run** bundled, validated XML queries directly against the CDC API
|
|
40
|
+
- **Build** new queries from natural language using Claude
|
|
41
|
+
- **Refine** existing queries with conversational feedback
|
|
42
|
+
|
|
43
|
+
Beyond WONDER, `pulse` gives direct access to six more live CDC/NCI/ATSDR sources — no LLM required for those, just a dataset lookup and a query: `seer`, `cdc-open`, `wisqars`, `grasp`, `nssp`, and `nis`.
|
|
44
|
+
|
|
45
|
+
## Setup
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
# From PyPI (requires Python 3.14+)
|
|
49
|
+
pip install pulse-code
|
|
50
|
+
|
|
51
|
+
# Or from source
|
|
52
|
+
uv sync
|
|
53
|
+
|
|
54
|
+
# For build/query/refine/compare/chat commands, set your Anthropic API key:
|
|
55
|
+
export ANTHROPIC_API_KEY=sk-ant-...
|
|
56
|
+
# or put it in a .env file:
|
|
57
|
+
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
### LLM provider
|
|
61
|
+
|
|
62
|
+
`pulse` defaults to Anthropic Claude but can also run against an Azure
|
|
63
|
+
OpenAI Foundry deployment (e.g. GPT-5.4). Select the provider with
|
|
64
|
+
`LLM_PROVIDER` (defaults to `anthropic`):
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
# Anthropic (default), needs ANTHROPIC_API_KEY as above
|
|
68
|
+
|
|
69
|
+
# Azure OpenAI Foundry
|
|
70
|
+
export LLM_PROVIDER=azure_openai
|
|
71
|
+
export AZURE_OPENAI_API_KEY=...
|
|
72
|
+
export AZURE_OPENAI_ENDPOINT=https://<your-resource>.openai.azure.com
|
|
73
|
+
export AZURE_OPENAI_DEPLOYMENT=<your-gpt-5.4-deployment-name>
|
|
74
|
+
export AZURE_OPENAI_API_VERSION=<api-version-your-resource-supports>
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
All four `AZURE_OPENAI_*` variables are required when `LLM_PROVIDER=azure_openai`;
|
|
78
|
+
`pulse` will tell you which ones are missing. These can also go in a `.env`
|
|
79
|
+
file alongside `ANTHROPIC_API_KEY`.
|
|
80
|
+
|
|
81
|
+
If the LLM endpoint isn't directly reachable (e.g. an Azure OpenAI resource
|
|
82
|
+
with public network access disabled, requiring a private endpoint), bridge
|
|
83
|
+
the connection through a proxy with `LLM_HTTP_PROXY`. Applies to both
|
|
84
|
+
providers, and supports `http://`, `https://`, `socks5://`, and `socks5h://`
|
|
85
|
+
(DNS resolved through the proxy):
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
export LLM_HTTP_PROXY=socks5h://user:pass@host:port
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
## Commands
|
|
92
|
+
|
|
93
|
+
The CLI has five top-level commands: **`topics`** (browse by subject across all
|
|
94
|
+
sources), **`source`** (browse/query one source), **`search`** (free-text find),
|
|
95
|
+
plus **`doctor`** and **`generate`**. Every data source lives under `source`:
|
|
96
|
+
`pulse source` for an overview, `pulse source <name>` for its datasets, and
|
|
97
|
+
`pulse source <name> <verb> …` to query it (e.g. `pulse source seer mortality`).
|
|
98
|
+
|
|
99
|
+
### `pulse source wonder datasets` — what's available
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
pulse source wonder datasets # all datasets
|
|
103
|
+
pulse source wonder datasets --topic Mortality # filter by topic
|
|
104
|
+
pulse source wonder datasets --json # JSON output
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Shows all 26+ CDC WONDER datasets with: topic, year range, what the data covers, number of bundled example queries, and whether age-adjusted rates are available.
|
|
108
|
+
|
|
109
|
+
**Topics:** Mortality · Infant Mortality · Natality · Environment · Vaccine Safety · Infectious Disease
|
|
110
|
+
|
|
111
|
+
### `pulse source wonder info <ID>` — deep dive on a dataset
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
pulse source wonder info D176 # Provisional Mortality (2018–present)
|
|
115
|
+
pulse source wonder info D66 # Natality / birth data
|
|
116
|
+
pulse source wonder info D8 # VAERS vaccine adverse events
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Shows: subject description, available measures, key grouping dimensions, and all bundled example queries for that dataset.
|
|
120
|
+
|
|
121
|
+
### `pulse search "<topic>"` — find what you need
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
pulse search "opioid overdose deaths by state"
|
|
125
|
+
pulse search "maternal mortality by race"
|
|
126
|
+
pulse search "birth rates 2010 to 2020"
|
|
127
|
+
pulse search "tick-borne disease cases" --queries # queries only
|
|
128
|
+
pulse search "recent COVID deaths" --datasets # datasets only
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
### `pulse source wonder list-queries` — all bundled example queries
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
pulse source wonder list-queries
|
|
135
|
+
pulse source wonder list-queries --dataset D176 # filter by dataset
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
23 working XML queries covering: drug/opioid/fentanyl deaths, maternal mortality, births, COVID deaths by race, suicide, tick-borne diseases, racial mortality gap, infant mortality, heart disease vs. cancer, and more.
|
|
139
|
+
|
|
140
|
+
### `pulse source seer` — NCI SEER cancer statistics
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
pulse source seer sites --search breast # look up a cancer site code
|
|
144
|
+
pulse source seer mortality --site 55 --sex female -f csv
|
|
145
|
+
pulse source seer mortality --site 47 --compare-by race -f csv
|
|
146
|
+
pulse source seer incidence --site 55 --stage 104 -f csv
|
|
147
|
+
pulse source seer by-age --site 1 -f csv
|
|
148
|
+
pulse source seer compare-sites 55 47 66 -f csv # breast vs. lung vs. melanoma
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Cancer incidence and U.S. mortality rates/counts by site, sex, race, and age group, back to 1975 — calls the same unauthenticated JSON endpoints [SEER*Explorer](https://seer.cancer.gov/statistics-network/explorer/) itself uses. No API key needed.
|
|
152
|
+
|
|
153
|
+
### `pulse source cdc-open` — CDC Open Data (data.cdc.gov)
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
pulse source cdc-open list # 60+ datasets: mortality, vaccination, wastewater, NNDSS, HAI, and more
|
|
157
|
+
pulse source cdc-open list --search wastewater
|
|
158
|
+
pulse source cdc-open query leading_death --where "year='2015'" -f csv
|
|
159
|
+
pulse source cdc-open query bi63-dtpu --where "state='California'" --limit 500 -f json
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
Raw [SODA](https://dev.socrata.com/) queries (`--where`, `--select`, `--group`, `--order`) against any of the registered Socrata datasets, by registry key or by Socrata ID directly. No API key needed (set `CDC_DATA_APP_TOKEN` for a higher rate limit).
|
|
163
|
+
|
|
164
|
+
### `pulse source wisqars` — WISQARS injury & violence data
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
pulse source wisqars list
|
|
168
|
+
pulse source wisqars mortality --intent Suicide --mechanism Firearm -f csv # 1999-2016
|
|
169
|
+
pulse source wisqars national --intent FA_Deaths --type year -f csv # 2019-present
|
|
170
|
+
pulse source wisqars state --intent Drug_OD --year 2023 -f table
|
|
171
|
+
pulse source wisqars county --state Texas --intent FA_Deaths --year 2023
|
|
172
|
+
pulse source wisqars tract --state Texas --intent All_Homicide --year 2022 # census-tract granularity
|
|
173
|
+
pulse source wisqars query t6u2-f84c --where "intent='Drug_OD' AND type='year'"
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
Fatal firearm/suicide/homicide/drug-overdose data from [WISQARS](https://wisqars.cdc.gov/) at national, state, county, and census-tract granularity, backed by data.cdc.gov Socrata datasets (same client as `cdc-open`). No API key needed.
|
|
177
|
+
|
|
178
|
+
### `pulse source grasp` — ATSDR GRASP disease surveillance
|
|
179
|
+
|
|
180
|
+
```bash
|
|
181
|
+
pulse source grasp list
|
|
182
|
+
pulse source grasp hantavirus cases --outcome Dead -f table # pre-1993-present
|
|
183
|
+
pulse source grasp hantavirus by-year -f table
|
|
184
|
+
pulse source grasp hantavirus by-state -f table
|
|
185
|
+
pulse source grasp fluview ili-data --region nat --region ca --region tx --epiweeks 202001-202026
|
|
186
|
+
pulse source grasp fluview ili-by-region --epiweeks 201940-202020 -f table
|
|
187
|
+
pulse source grasp fluview clinical-data --region nat --epiweeks 202001-202026
|
|
188
|
+
pulse source grasp flusurv data --location CA --location OH --epiweeks 202001-202020 -f csv
|
|
189
|
+
pulse source grasp flusurv by-season --location CA -f table
|
|
190
|
+
pulse source grasp flusurv by-location --season 2019-20 -f table
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
Hantavirus case data, FluView ILINet influenza-like-illness activity, WHO/NREVSS clinical lab flu positivity, and FluSurv-NET hospitalization rates — sourced from [gis.cdc.gov/grasp](https://gis.cdc.gov/grasp/) and the CMU Delphi Epidata API. No API key needed. Note: repeatable options like `--region`/`--location` take one value per flag (`--region nat --region ca`), unlike `health`'s argparse CLI which accepts space-separated lists after a single flag.
|
|
194
|
+
|
|
195
|
+
### `pulse source nssp` — emergency department visit surveillance
|
|
196
|
+
|
|
197
|
+
```bash
|
|
198
|
+
pulse source nssp query covid --geo-type state --geo-value ca -f csv
|
|
199
|
+
pulse source nssp query influenza --geo-type nation --geo-value us
|
|
200
|
+
pulse source nssp national --start 202401 -f csv # all 4 pathogens, national
|
|
201
|
+
pulse source nssp hhs rsv --region 4 -f table
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
Weekly % of ED visits attributed to COVID/flu/RSV from the [National Syndromic Surveillance Program](https://www.cdc.gov/nssp/), via the CMU Delphi Epidata API. Time values use epiweek format (`YYYYWW`, e.g. `202518` = week 18 of 2025). No API key needed.
|
|
205
|
+
|
|
206
|
+
### `pulse source nis` — National Immunization Survey (vaccination coverage)
|
|
207
|
+
|
|
208
|
+
```bash
|
|
209
|
+
pulse source nis list child # available years, 2011-2022
|
|
210
|
+
pulse source nis stream child 2022 --limit 10 -f json # raw respondent microdata
|
|
211
|
+
pulse source nis rates child 2022 -f table # state-level UTD rates
|
|
212
|
+
pulse source nis rates teen 2022 --vaccines P_UTDHPV13 -f csv
|
|
213
|
+
pulse source nis national child 2022 # national UTD summary
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
Childhood (19–35mo) and teen (13–17yr) vaccination coverage from CDC's annual random-digit-dial survey. Files are large fixed-width `.dat` files (50–200MB) streamed directly — nothing is written to disk. **Known issue:** CDC has restructured its NIS file hosting since this registry's URLs were last verified (some years now live under `www.cdc.gov/nis/media/files/...` or `ftp.cdc.gov/pub/Vaccines_NIS/` instead of the legacy `ftp.cdc.gov/.../nis/NISPUF{YY}-formats.sas` path baked into `nis_catalog.py`), so live `stream`/`rates`/`national` calls currently 404 for at least the 2015+ years — the same pre-existing gap affects `health`'s own `nis` module. The CLI plumbing and DAT-streaming parser are unit-tested and correct; only the hardcoded per-year URLs need refreshing against CDC's current hosting.
|
|
217
|
+
|
|
218
|
+
### `pulse source wonder run <query>` — execute a query
|
|
219
|
+
|
|
220
|
+
```bash
|
|
221
|
+
# Run a bundled query by filename (no path needed)
|
|
222
|
+
pulse source wonder run drug-deaths-by-year-2018-2024-req.xml
|
|
223
|
+
|
|
224
|
+
# Output formats
|
|
225
|
+
pulse source wonder run opioid-overdose-deaths-2018-2024-req.xml -f csv
|
|
226
|
+
pulse source wonder run mortality-by-year-cause-2021-2024-req.xml -f json
|
|
227
|
+
pulse source wonder run births-by-year-2007-2024-req.xml -f table -o births.csv
|
|
228
|
+
|
|
229
|
+
# Run your own query file
|
|
230
|
+
pulse source wonder run /path/to/my-query.xml
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
Hits the live CDC WONDER API. No login required; CDC requires a ~2-minute cooldown between queries.
|
|
234
|
+
|
|
235
|
+
### `pulse source wonder build "<description>"` — build a query with Claude
|
|
236
|
+
|
|
237
|
+
```bash
|
|
238
|
+
# Requires ANTHROPIC_API_KEY
|
|
239
|
+
pulse source wonder build "drug overdose deaths by state and year 2018-2023"
|
|
240
|
+
pulse source wonder build "maternal mortality by race, 2018-2023" -o maternal-race.xml
|
|
241
|
+
pulse source wonder build "birth rates by age of mother 2010 to 2024" --no-suggest
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
Suggests closest existing queries first, then calls Claude to build a new XML query. The LLM selects the right dataset and generates overrides merged onto a validated base template.
|
|
245
|
+
|
|
246
|
+
### `pulse source wonder query "<description>"` — build and run in one step
|
|
247
|
+
|
|
248
|
+
```bash
|
|
249
|
+
pulse source wonder query "fentanyl deaths by state 2020-2024" -f csv
|
|
250
|
+
pulse source wonder query "infant mortality by race 2018-2023" --save-xml infant-race.xml
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
### `pulse source wonder refine <file> "<feedback>"` — iterate on a query
|
|
254
|
+
|
|
255
|
+
```bash
|
|
256
|
+
pulse source wonder refine opioid-overdose-deaths-2018-2024-req.xml "break it down by state"
|
|
257
|
+
pulse source wonder refine drug-deaths-by-year-2018-2024-req.xml "add sex breakdown" -o drug-sex.xml
|
|
258
|
+
pulse source wonder refine drug-deaths-by-year-2018-2024-req.xml "show monthly not yearly" --run -f csv
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
## Testing
|
|
262
|
+
|
|
263
|
+
```bash
|
|
264
|
+
uv run pytest # unit tests only, fast, no network (default)
|
|
265
|
+
uv run pytest -m integration # + integration tests (see below)
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
Unit tests cover catalog/matcher lookups, XML template merging (including
|
|
269
|
+
the CDC WONDER radio-button-trap regression), AAR constraints, provider
|
|
270
|
+
selection, and the offline-network-free CLI commands.
|
|
271
|
+
|
|
272
|
+
Integration tests (`tests/integration/`) are excluded by default and split
|
|
273
|
+
into two kinds:
|
|
274
|
+
|
|
275
|
+
- **`test_socks_proxy_integration.py`**: always runs. Spins up a local
|
|
276
|
+
SOCKS5 relay and a local mock LLM HTTP server, so it actually exercises
|
|
277
|
+
`LLM_HTTP_PROXY` end-to-end (real SOCKS handshake, real HTTP
|
|
278
|
+
request/response) without needing real Azure/Anthropic credentials.
|
|
279
|
+
- **`test_llm_provider_live.py`**: hits whatever `ANTHROPIC_API_KEY` /
|
|
280
|
+
`LLM_PROVIDER=azure_openai` + `AZURE_OPENAI_*` / `LLM_HTTP_PROXY` you
|
|
281
|
+
actually have configured. Skips if credentials aren't set; also skips
|
|
282
|
+
(rather than fails) if the provider is reachable but blocked at the
|
|
283
|
+
network layer (e.g. an Azure OpenAI resource with public access disabled
|
|
284
|
+
and no working proxy). That's an environment gap, not a code defect.
|
|
285
|
+
|
|
286
|
+
## Bundled Datasets (with base templates)
|
|
287
|
+
|
|
288
|
+
| ID | Subject | Years |
|
|
289
|
+
| ----------- | ------------------------------------------------------------- | ------------ |
|
|
290
|
+
| D176 | Provisional mortality: opioids, COVID, suicide, heart disease | 2018–present |
|
|
291
|
+
| D157 | Final mortality, single race (MCD+UCD) | 2018–2023 |
|
|
292
|
+
| D158 | Underlying cause of death, single race: maternal mortality | 2018–2023 |
|
|
293
|
+
| D77 | Multiple cause of death: drug deaths (historical) | 1999–2020 |
|
|
294
|
+
| D76 | Underlying cause of death: suicide, cancer (historical) | 1999–2020 |
|
|
295
|
+
| D141 | MCD with US-Mexico border regions | 1999–2020 |
|
|
296
|
+
| D140 | Compressed mortality ICD-10 | 1999–2016 |
|
|
297
|
+
| D16 | Compressed mortality ICD-9 | 1979–1998 |
|
|
298
|
+
| D74 | Compressed mortality ICD-8 | 1968–1978 |
|
|
299
|
+
| D69 | Linked birth/infant death records | 2007–2023 |
|
|
300
|
+
| D159 | Linked birth/infant death, expanded race | 2017–2023 |
|
|
301
|
+
| D31/D18/D23 | Linked birth/infant death (historical) | 1995–2006 |
|
|
302
|
+
| D66 | Natality: birth rates, birth outcomes | 2007–2024 |
|
|
303
|
+
| D149 | Natality, expanded race detail | 2016–2024 |
|
|
304
|
+
| D192 | Provisional natality (monthly) | 2023–present |
|
|
305
|
+
| D27/D10 | Natality (historical) | 1995–2006 |
|
|
306
|
+
| D8 | VAERS vaccine adverse events | 1990–present |
|
|
307
|
+
| D104 | Heat wave days by county | 1981–2010 |
|
|
308
|
+
| D60/D80/D81 | NLDAS temperature, sunlight, precipitation | 1979–2011 |
|
|
309
|
+
| D73 | PM2.5 fine particulate matter | 2003–2011 |
|
|
310
|
+
| D61 | MODIS land surface temperature | 2003–2008 |
|
|
311
|
+
|
|
312
|
+
## Public Health Questions You Can Answer
|
|
313
|
+
|
|
314
|
+
- How did opioid overdose deaths trend from 1999 to today, broken down by drug type?
|
|
315
|
+
- What is the racial gap in COVID-19 mortality?
|
|
316
|
+
- How does maternal mortality differ by race and state?
|
|
317
|
+
- Which states have the highest suicide rates by sex?
|
|
318
|
+
- How have birth rates changed by age of mother since 1995?
|
|
319
|
+
- Are tick-borne disease cases increasing?
|
|
320
|
+
- How do PM2.5 air quality levels correlate with where people live?
|
|
321
|
+
- What are the most common adverse events reported after COVID vaccines?
|
|
322
|
+
|
|
323
|
+
## Releasing
|
|
324
|
+
|
|
325
|
+
Releases are cut by pushing a tag. `publish.yml` (single workflow, one run
|
|
326
|
+
per tag) handles the rest as three sequential jobs:
|
|
327
|
+
|
|
328
|
+
1. Bump `version` in `pyproject.toml`, commit it.
|
|
329
|
+
2. `git tag vX.Y.Z && git push origin vX.Y.Z`
|
|
330
|
+
3. **`build`** builds the sdist/wheel, failing fast if the tag doesn't match
|
|
331
|
+
`pyproject.toml`'s version.
|
|
332
|
+
4. **`release`** (needs `build`) creates the GitHub Release with the built
|
|
333
|
+
artifacts attached, the source of truth for what shipped.
|
|
334
|
+
5. **`publish`** (needs `release`) publishes those same artifacts to PyPI
|
|
335
|
+
(`pulse-code`) via trusted publishing (OIDC) against the `prod`
|
|
336
|
+
environment, with no API tokens stored in the repo.
|
|
337
|
+
|
|
338
|
+
The `needs:` chain means a failure at any step blocks everything after it.
|
|
339
|
+
For example, a PyPI hiccup can't leave a GitHub Release around for a package that
|
|
340
|
+
isn't actually installable. If the `publish` job fails after `release`
|
|
341
|
+
succeeds, use "Re-run failed jobs" on that workflow run rather than
|
|
342
|
+
re-tagging. PyPI publishing is immutable: once a version is published it
|
|
343
|
+
can't be re-uploaded, so a bad release means bumping to a new version.
|
|
344
|
+
|
|
345
|
+
## Related projects
|
|
346
|
+
|
|
347
|
+
`pulse` is the exploration layer of a three-repo pipeline:
|
|
348
|
+
|
|
349
|
+
```bash
|
|
350
|
+
pulse-code → health → health-charts
|
|
351
|
+
(explore) (archive) (visualize)
|
|
352
|
+
```
|
|
353
|
+
|
|
354
|
+
- **[fartbagxp/health](https://github.com/fartbagxp/health)**, a collection of CDC data pipelines (WONDER, data.cdc.gov, NCHS, SEER, WISQARS, GRASP, NSSP, NIS, and more) and the CDC WONDER XML API client and LLM query builder this tool builds on. `pulse`'s SEER, CDC Open Data, WISQARS, GRASP, NSSP, and NIS clients are lightweight, standalone reimplementations of `health`'s equivalent modules — kept dependency-free (just `requests`) rather than depending on `health` directly, which also pulls in `pandas`/`playwright`/`lxml` for its archival pipelines. `pulse` now covers every source `health` does. Where `pulse` is for one-off, ad hoc exploration, `health` is where a query graduates once someone wants it archived on a recurring schedule: 23 of the 36 saved WONDER queries in `src/pulse/queries/` are also saved in `health`'s `src/wonder/queries/`, each wrapped there in a small `fetch_*.py` script that runs on a schedule and commits the result as a CSV under `data/raw/wonder/`. The other 13 (cancer incidence/mortality by site, fetal deaths, PM2.5, TB, STI cases, heat-wave days, etc.) are exploration-only for now, candidates for `health` if any of them turn into a recurring need.
|
|
355
|
+
- **[fartbagxp/health-charts](https://github.com/fartbagxp/health-charts)**, the dashboard at the end of the pipeline. It reads the CSVs `health` archives (including the ones seeded by `pulse`'s queries above) directly from GitHub and renders them as an interactive chart site.
|