pulse-code 1.1.0__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.3/PKG-INFO +223 -0
- pulse_code-1.1.3/README.md +204 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/pyproject.toml +10 -9
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/cli.py +561 -5
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/data/cdc_open_catalog.json +51 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/data/queries_index.json +210 -3
- pulse_code-1.1.3/src/pulse/dqs_catalog.py +116 -0
- pulse_code-1.1.3/src/pulse/dqs_sdk.py +102 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/grasp_catalog.py +2 -2
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/grasp_client.py +1 -1
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/grasp_sdk.py +1 -1
- pulse_code-1.1.3/src/pulse/queries/aids-cases-by-age-1981-1999-req.xml +178 -0
- pulse_code-1.1.3/src/pulse/queries/aids-cases-by-location-1981-1999-req.xml +178 -0
- pulse_code-1.1.3/src/pulse/queries/aids-cases-by-race-1981-1999-req.xml +178 -0
- pulse_code-1.1.3/src/pulse/queries/aids-cases-by-sex-1981-1999-req.xml +178 -0
- pulse_code-1.1.3/src/pulse/queries/births-by-age-of-mother-2007-2024-req.xml +334 -0
- pulse_code-1.1.3/src/pulse/queries/births-by-race-2007-2024-req.xml +334 -0
- pulse_code-1.1.3/src/pulse/queries/cancer-incidence-by-state-1999-2022-req.xml +174 -0
- pulse_code-1.1.3/src/pulse/queries/cancer-mortality-by-state-2018-2023-req.xml +166 -0
- pulse_code-1.1.3/src/pulse/queries/covid-deaths-by-age-2020-2023-req.xml +533 -0
- pulse_code-1.1.3/src/pulse/queries/covid-deaths-by-age-sex-2020-2023-req.xml +533 -0
- pulse_code-1.1.3/src/pulse/queries/covid-deaths-by-sex-2020-2023-req.xml +533 -0
- pulse_code-1.1.3/src/pulse/queries/deaths-by-place-of-death-2018-2024-req.xml +538 -0
- pulse_code-1.1.3/src/pulse/queries/fetal-deaths-by-age-of-mother-2005-2024-req.xml +322 -0
- pulse_code-1.1.3/src/pulse/queries/fetal-deaths-by-race-2005-2024-req.xml +322 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/heat-wave-days-by-county-req.xml +1 -1
- pulse_code-1.1.3/src/pulse/queries/maternal-mortality-by-race-2018-2024-req.xml +413 -0
- pulse_code-1.1.3/src/pulse/queries/opioid-deaths-by-age-2018-2024-req.xml +544 -0
- pulse_code-1.1.3/src/pulse/queries/opioid-deaths-by-sex-2018-2024-req.xml +544 -0
- pulse_code-1.1.3/src/pulse/queries/pm25-by-state-2003-2011-req.xml +194 -0
- pulse_code-1.1.3/src/pulse/queries/std-cases-by-state-1984-2014-req.xml +178 -0
- pulse_code-1.1.3/src/pulse/queries/tick-borne-diseases-by-age-2016-2023-req.xml +125 -0
- pulse_code-1.1.3/src/pulse/queries/tick-borne-diseases-by-race-2016-2023-req.xml +125 -0
- pulse_code-1.1.3/src/pulse/queries/tick-borne-diseases-by-sex-2016-2023-req.xml +125 -0
- pulse_code-1.1.3/src/pulse/queries/tick-borne-diseases-by-state-2016-2023-req.xml +125 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/sources_registry.py +36 -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.0 → pulse_code-1.1.3}/src/pulse/topics_registry.py +95 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/wonder_client.py +1 -1
- pulse_code-1.1.3/src/pulse_code.egg-info/PKG-INFO +223 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse_code.egg-info/SOURCES.txt +27 -0
- pulse_code-1.1.3/src/pulse_code.egg-info/requires.txt +9 -0
- pulse_code-1.1.0/PKG-INFO +0 -355
- pulse_code-1.1.0/README.md +0 -337
- pulse_code-1.1.0/src/pulse_code.egg-info/PKG-INFO +0 -355
- pulse_code-1.1.0/src/pulse_code.egg-info/requires.txt +0 -8
- {pulse_code-1.1.0 → pulse_code-1.1.3}/LICENSE +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/setup.cfg +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/__init__.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/__main__.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/catalog.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/cdc_open_catalog.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/data/catalog.json +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/data/seer_var_formats.json +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/data/variable_labels.json +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/llm_builder.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/matcher.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/nis_catalog.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/nis_parser.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/nis_sdk.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/nssp_client.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/nssp_sdk.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/aids-cases-by-year-1981-1999-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/births-by-year-1995-2002-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/births-by-year-2003-2006-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/births-by-year-2007-2024-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/cancer-incidence-by-site-by-year-1999-2022-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/cancer-mortality-by-site-by-year-2018-2023-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/covid-deaths-by-race-2020-2023-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/drug-deaths-by-month-1999-2020-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/drug-deaths-by-month-2018-2024-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/drug-deaths-by-year-1999-2020-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/drug-deaths-by-year-2018-2024-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/fentanyl-deaths-by-month-1999-2020-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/fentanyl-deaths-by-month-2018-2024-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/fetal-deaths-by-cause-by-year-2014-2024-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/fetal-deaths-by-year-2005-2024-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/heart-vs-cancer-by-sex-2018-2023-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/infant-mortality-2018-2023-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/infant-mortality-by-cause-by-year-2007-2023-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/maternal-mortality-by-year-1999-2020-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/maternal-mortality-by-year-2018-2024-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/mortality-by-race-sex-2018-2023-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/mortality-by-year-cause-1979-1998-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/mortality-by-year-cause-1999-2020-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/mortality-by-year-cause-2021-2024-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/opioid-overdose-deaths-2018-2024-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/pm25-by-year-2003-2011-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/provisional-births-by-month-2023-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/racial-mortality-gap-2018-2023-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/std-cases-by-disease-by-year-1984-2014-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/suicide-by-sex-1999-2020-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/suicide-by-sex-2021-2024-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/tb-cases-by-year-1993-2023-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/tick-borne-diseases-by-year-2016-2023-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/underlying-cause-mortality-by-year-1999-2020-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/queries/unintentional-injuries-by-age-2018-2023-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/seer_catalog.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/seer_client.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/seer_sdk.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/soda_client.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/templates/D10-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/templates/D104-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/templates/D117-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/templates/D128-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/templates/D140-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/templates/D141-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/templates/D149-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/templates/D157-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/templates/D158-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/templates/D159-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/templates/D16-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/templates/D176-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/templates/D178-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/templates/D18-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/templates/D192-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/templates/D204-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/templates/D23-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/templates/D27-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/templates/D31-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/templates/D60-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/templates/D61-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/templates/D66-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/templates/D69-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/templates/D73-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/templates/D74-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/templates/D76-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/templates/D77-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/templates/D8-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/templates/D80-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/templates/D81-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/wisqars_catalog.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse/wisqars_sdk.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse_code.egg-info/dependency_links.txt +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse_code.egg-info/entry_points.txt +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.3}/src/pulse_code.egg-info/top_level.txt +0 -0
|
@@ -0,0 +1,223 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: pulse-code
|
|
3
|
+
Version: 1.1.3
|
|
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.4.0
|
|
10
|
+
Requires-Dist: openai==3.11.0
|
|
11
|
+
Requires-Dist: openpyxl==3.1.5
|
|
12
|
+
Requires-Dist: pydantic==2.13.5
|
|
13
|
+
Requires-Dist: python-dotenv==1.2.3
|
|
14
|
+
Requires-Dist: requests==2.34.2
|
|
15
|
+
Requires-Dist: rich==15.0.0
|
|
16
|
+
Requires-Dist: socksio==1.0.0
|
|
17
|
+
Requires-Dist: typer==0.27.2
|
|
18
|
+
Dynamic: license-file
|
|
19
|
+
|
|
20
|
+
# Pulse
|
|
21
|
+
|
|
22
|
+
[](https://pypi.org/project/pulse-code/)
|
|
23
|
+
[](https://pypi.org/project/pulse-code/)
|
|
24
|
+
[](https://github.com/fartbagxp/pulse-code/actions/workflows/publish.yml)
|
|
25
|
+
[](https://fartbagxp.github.io/pulse-code/)
|
|
26
|
+
[](LICENSE)
|
|
27
|
+
|
|
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.
|
|
29
|
+
|
|
30
|
+

|
|
31
|
+
|
|
32
|
+
## Setup
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
# From PyPI (requires Python 3.11+)
|
|
36
|
+
pip install pulse-code
|
|
37
|
+
pulse --help
|
|
38
|
+
|
|
39
|
+
# From uv in this local directory
|
|
40
|
+
uv run pulse --help
|
|
41
|
+
```
|
|
42
|
+
|
|
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:
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
export ANTHROPIC_API_KEY=sk-ant-...
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Azure OpenAI and proxied connections work too; see [docs/llm-providers.md](docs/llm-providers.md).
|
|
50
|
+
|
|
51
|
+
## Usage
|
|
52
|
+
|
|
53
|
+
Five top level commands. `topics` browses by subject across all sources, `source` browses and queries one source, `search` is free text find, `doctor` checks credentials and source reachability, and `generate` writes a health-style `fetch_*.py` starter script from a saved query.
|
|
54
|
+
|
|
55
|
+
Start with a subject if you don't know which source holds what you want:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
pulse topics # every subject across all nine sources
|
|
59
|
+
pulse topics mortality # drill into one
|
|
60
|
+
pulse search "opioid overdose deaths by state"
|
|
61
|
+
pulse search "tick-borne disease cases" --queries # queries only
|
|
62
|
+
pulse search "recent COVID deaths" --datasets # datasets only
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Or go straight at a source. Each one nests the same way:
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
pulse source # what sources exist
|
|
69
|
+
pulse source seer # what that source offers
|
|
70
|
+
pulse source seer mortality # query it
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### `pulse source wonder`: CDC WONDER
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
pulse source wonder datasets # 26+ datasets
|
|
77
|
+
pulse source wonder info D176 # provisional mortality
|
|
78
|
+
pulse source wonder run drug-deaths-by-year-2018-2024-req.xml -f csv
|
|
79
|
+
pulse source wonder query "fentanyl deaths by state 2020-2024" -f csv
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Mortality, natality, VAERS, and environmental datasets going back to 1968, with 59 bundled XML queries and LLM-backed commands that write new ones. CDC requires 15 seconds between queries. Full command reference and the dataset table: [docs/cdc-wonder.md](docs/cdc-wonder.md).
|
|
83
|
+
|
|
84
|
+
### `pulse source seer`: NCI SEER Cancer Statistics
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
pulse source seer sites --search breast # look up a cancer site code
|
|
88
|
+
pulse source seer mortality --site 55 --sex female -f csv
|
|
89
|
+
pulse source seer mortality --site 47 --compare-by race -f csv
|
|
90
|
+
pulse source seer incidence --site 55 --stage 104 -f csv
|
|
91
|
+
pulse source seer by-age --site 1 -f csv
|
|
92
|
+
pulse source seer compare-sites 55 47 66 -f csv # breast vs. lung vs. melanoma
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Cancer incidence and U.S. mortality rates and 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.
|
|
96
|
+
|
|
97
|
+
### `pulse source cdc-open`: CDC Open Data (data.cdc.gov)
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
pulse source cdc-open list # 60+ datasets: mortality, vaccination, wastewater, NNDSS, HAI, and more
|
|
101
|
+
pulse source cdc-open list --search wastewater
|
|
102
|
+
pulse source cdc-open query leading_death --where "year='2015'" -f csv
|
|
103
|
+
pulse source cdc-open query bi63-dtpu --where "state='California'" --limit 500 -f json
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Raw [SODA](https://dev.socrata.com/) queries (`--where`, `--select`, `--group`, `--order`) against any registered Socrata dataset, by registry key or Socrata ID. Set `CDC_DATA_APP_TOKEN` for a higher rate limit.
|
|
107
|
+
|
|
108
|
+
### `pulse source dqs`: NCHS Data Query System (Health, United States)
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
pulse source dqs list # 28 datasets across 17 topics
|
|
112
|
+
pulse source dqs list --topic "Chronic Disease" # filter by topic bucket
|
|
113
|
+
pulse source dqs list --search cholesterol
|
|
114
|
+
pulse source dqs trend drug-overdose-deaths -f csv # all-persons national trend, oldest→newest
|
|
115
|
+
pulse source dqs trend cholesterol-adults --list-measures # see a dataset's estimate types
|
|
116
|
+
pulse source dqs trend cholesterol-adults -e "mg/dL, age adjusted" -f csv
|
|
117
|
+
pulse source dqs query nhis-adult --where "classification='Total'" --limit 500 -f json
|
|
118
|
+
```
|
|
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.
|
|
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
|
+
|
|
144
|
+
### `pulse source wisqars`: Injury and Violence Data
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
pulse source wisqars list
|
|
148
|
+
pulse source wisqars mortality --intent Suicide --mechanism Firearm -f csv # 1999-2016
|
|
149
|
+
pulse source wisqars national --intent FA_Deaths --type year -f csv # 2019-present
|
|
150
|
+
pulse source wisqars state --intent Drug_OD --year 2023 -f table
|
|
151
|
+
pulse source wisqars county --state Texas --intent FA_Deaths --year 2023
|
|
152
|
+
pulse source wisqars tract --state Texas --intent All_Homicide --year 2022 # census-tract granularity
|
|
153
|
+
pulse source wisqars query t6u2-f84c --where "intent='Drug_OD' AND type='year'"
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
Fatal firearm, suicide, homicide, and drug overdose data from [WISQARS](https://wisqars.cdc.gov/) at national, state, county, and census tract granularity, backed by the same Socrata client as `cdc-open`.
|
|
157
|
+
|
|
158
|
+
### `pulse source grasp`: ATSDR GRASP Disease Surveillance
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
pulse source grasp list
|
|
162
|
+
pulse source grasp hantavirus cases --outcome Dead -f table # pre-1993-present
|
|
163
|
+
pulse source grasp hantavirus by-year -f table
|
|
164
|
+
pulse source grasp hantavirus by-state -f table
|
|
165
|
+
pulse source grasp fluview ili-data --region nat --region ca --region tx --epiweeks 202001-202026
|
|
166
|
+
pulse source grasp fluview ili-by-region --epiweeks 201940-202020 -f table
|
|
167
|
+
pulse source grasp fluview clinical-data --region nat --epiweeks 202001-202026
|
|
168
|
+
pulse source grasp flusurv data --location CA --location OH --epiweeks 202001-202020 -f csv
|
|
169
|
+
pulse source grasp flusurv by-season --location CA -f table
|
|
170
|
+
pulse source grasp flusurv by-location --season 2019-20 -f table
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
Hantavirus cases, FluView ILINet influenza-like-illness activity, WHO/NREVSS clinical lab flu positivity, and FluSurv-NET hospitalization rates, from [gis.cdc.gov/grasp](https://gis.cdc.gov/grasp/) and the CMU Delphi Epidata API. Repeatable options like `--region` and `--location` take one value per flag (`--region nat --region ca`), unlike `health`'s argparse CLI, which accepts a space separated list after a single flag.
|
|
174
|
+
|
|
175
|
+
### `pulse source nssp`: Emergency Department Visit Surveillance
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
pulse source nssp query covid --geo-type state --geo-value ca -f csv
|
|
179
|
+
pulse source nssp query influenza --geo-type nation --geo-value us
|
|
180
|
+
pulse source nssp national --start 202401 -f csv # all 4 pathogens, national
|
|
181
|
+
pulse source nssp hhs rsv --region 4 -f table
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
Weekly percentage of ED visits attributed to COVID, flu, and RSV from the [National Syndromic Surveillance Program](https://www.cdc.gov/nssp/), via the CMU Delphi Epidata API. Time values use epiweek format (`YYYYWW`, so `202518` is week 18 of 2025).
|
|
185
|
+
|
|
186
|
+
### `pulse source nis`: National Immunization Survey
|
|
187
|
+
|
|
188
|
+
```bash
|
|
189
|
+
pulse source nis list child # available years, 2011-2022
|
|
190
|
+
pulse source nis stream child 2022 --limit 10 -f json # raw respondent microdata
|
|
191
|
+
pulse source nis rates child 2022 --vaccines P_UTD431 -f table # state-level UTD rates
|
|
192
|
+
pulse source nis rates teen 2022 --vaccines P_UTDHPV13 -f csv
|
|
193
|
+
pulse source nis national child 2022 # national UTD summary
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
Childhood (19-35mo) and teen (13-17yr) vaccination coverage from CDC's annual random-digit-dial survey. The source files are large fixed-width `.dat` files (50-200MB), and `pulse` streams them straight through without writing anything to disk.
|
|
197
|
+
|
|
198
|
+
Two things to know. 2015 is missing from both surveys: `list child` reports 2011-2022 and `list teen` reports 2011-2024, each skipping 2015.
|
|
199
|
+
|
|
200
|
+
`rates` and `national` return one column per vaccine, 30 or more in total, which is more than `-f table` can fit on a terminal. The renderer squeezes every column to zero width and prints a grid of empty cells, which looks like the query returned nothing. The data is there: narrow it with `--vaccines`, as above, or use `-f csv` or `-f json` to get every column.
|
|
201
|
+
|
|
202
|
+
## Docs
|
|
203
|
+
|
|
204
|
+
- [cdc-wonder.md](docs/cdc-wonder.md), the full `wonder` command reference and bundled dataset table
|
|
205
|
+
- [building-xml-queries.md](docs/building-xml-queries.md), how to write WONDER XML for a dataset with no template
|
|
206
|
+
- [llm-providers.md](docs/llm-providers.md), Anthropic, Azure OpenAI, and proxy configuration
|
|
207
|
+
- [test.md](docs/test.md), running the tests and previewing the generated site
|
|
208
|
+
- [release.md](docs/release.md), how a release is cut and what to do when one half-fails
|
|
209
|
+
|
|
210
|
+
## Related Projects
|
|
211
|
+
|
|
212
|
+
`pulse` is the exploration layer of various projects:
|
|
213
|
+
|
|
214
|
+
```bash
|
|
215
|
+
pulse-code → health → health-charts
|
|
216
|
+
(explore) (archive) (visualize)
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
[fartbagxp/health](https://github.com/fartbagxp/health) archives the same sources as this project on a schedule. It's also home to the CDC WONDER XML API client and LLM query builder this tool builds on.
|
|
220
|
+
|
|
221
|
+
**pulse** is where a query starts; **health** is where it graduates once someone wants to collect it as a scheduled job. 23 of the 59 saved WONDER queries in `src/pulse/queries/` are also in `health`, each wrapped in a `fetch_*.py` script. The rest are exploration only for now — cancer and AIDS broken out by state, fetal deaths by race, PM2.5 by state, deaths by place of death, plus a pile of demographic slices for COVID, opioids, and maternal mortality. `pulse`'s source clients are standalone reimplementations of `health`'s modules, kept to just `requests` instead of pulling in the `pandas`/`playwright`/`lxml` stack that `health`'s pipelines need.
|
|
222
|
+
|
|
223
|
+
[fartbagxp/health-charts](https://github.com/fartbagxp/health-charts) reads those archived CSVs from GitHub and renders them as an interactive chart site.
|
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
# Pulse
|
|
2
|
+
|
|
3
|
+
[](https://pypi.org/project/pulse-code/)
|
|
4
|
+
[](https://pypi.org/project/pulse-code/)
|
|
5
|
+
[](https://github.com/fartbagxp/pulse-code/actions/workflows/publish.yml)
|
|
6
|
+
[](https://fartbagxp.github.io/pulse-code/)
|
|
7
|
+
[](LICENSE)
|
|
8
|
+
|
|
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.
|
|
10
|
+
|
|
11
|
+

|
|
12
|
+
|
|
13
|
+
## Setup
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
# From PyPI (requires Python 3.11+)
|
|
17
|
+
pip install pulse-code
|
|
18
|
+
pulse --help
|
|
19
|
+
|
|
20
|
+
# From uv in this local directory
|
|
21
|
+
uv run pulse --help
|
|
22
|
+
```
|
|
23
|
+
|
|
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:
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
export ANTHROPIC_API_KEY=sk-ant-...
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Azure OpenAI and proxied connections work too; see [docs/llm-providers.md](docs/llm-providers.md).
|
|
31
|
+
|
|
32
|
+
## Usage
|
|
33
|
+
|
|
34
|
+
Five top level commands. `topics` browses by subject across all sources, `source` browses and queries one source, `search` is free text find, `doctor` checks credentials and source reachability, and `generate` writes a health-style `fetch_*.py` starter script from a saved query.
|
|
35
|
+
|
|
36
|
+
Start with a subject if you don't know which source holds what you want:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
pulse topics # every subject across all nine sources
|
|
40
|
+
pulse topics mortality # drill into one
|
|
41
|
+
pulse search "opioid overdose deaths by state"
|
|
42
|
+
pulse search "tick-borne disease cases" --queries # queries only
|
|
43
|
+
pulse search "recent COVID deaths" --datasets # datasets only
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Or go straight at a source. Each one nests the same way:
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
pulse source # what sources exist
|
|
50
|
+
pulse source seer # what that source offers
|
|
51
|
+
pulse source seer mortality # query it
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
### `pulse source wonder`: CDC WONDER
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
pulse source wonder datasets # 26+ datasets
|
|
58
|
+
pulse source wonder info D176 # provisional mortality
|
|
59
|
+
pulse source wonder run drug-deaths-by-year-2018-2024-req.xml -f csv
|
|
60
|
+
pulse source wonder query "fentanyl deaths by state 2020-2024" -f csv
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Mortality, natality, VAERS, and environmental datasets going back to 1968, with 59 bundled XML queries and LLM-backed commands that write new ones. CDC requires 15 seconds between queries. Full command reference and the dataset table: [docs/cdc-wonder.md](docs/cdc-wonder.md).
|
|
64
|
+
|
|
65
|
+
### `pulse source seer`: NCI SEER Cancer Statistics
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
pulse source seer sites --search breast # look up a cancer site code
|
|
69
|
+
pulse source seer mortality --site 55 --sex female -f csv
|
|
70
|
+
pulse source seer mortality --site 47 --compare-by race -f csv
|
|
71
|
+
pulse source seer incidence --site 55 --stage 104 -f csv
|
|
72
|
+
pulse source seer by-age --site 1 -f csv
|
|
73
|
+
pulse source seer compare-sites 55 47 66 -f csv # breast vs. lung vs. melanoma
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Cancer incidence and U.S. mortality rates and 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.
|
|
77
|
+
|
|
78
|
+
### `pulse source cdc-open`: CDC Open Data (data.cdc.gov)
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
pulse source cdc-open list # 60+ datasets: mortality, vaccination, wastewater, NNDSS, HAI, and more
|
|
82
|
+
pulse source cdc-open list --search wastewater
|
|
83
|
+
pulse source cdc-open query leading_death --where "year='2015'" -f csv
|
|
84
|
+
pulse source cdc-open query bi63-dtpu --where "state='California'" --limit 500 -f json
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Raw [SODA](https://dev.socrata.com/) queries (`--where`, `--select`, `--group`, `--order`) against any registered Socrata dataset, by registry key or Socrata ID. Set `CDC_DATA_APP_TOKEN` for a higher rate limit.
|
|
88
|
+
|
|
89
|
+
### `pulse source dqs`: NCHS Data Query System (Health, United States)
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
pulse source dqs list # 28 datasets across 17 topics
|
|
93
|
+
pulse source dqs list --topic "Chronic Disease" # filter by topic bucket
|
|
94
|
+
pulse source dqs list --search cholesterol
|
|
95
|
+
pulse source dqs trend drug-overdose-deaths -f csv # all-persons national trend, oldest→newest
|
|
96
|
+
pulse source dqs trend cholesterol-adults --list-measures # see a dataset's estimate types
|
|
97
|
+
pulse source dqs trend cholesterol-adults -e "mg/dL, age adjusted" -f csv
|
|
98
|
+
pulse source dqs query nhis-adult --where "classification='Total'" --limit 500 -f json
|
|
99
|
+
```
|
|
100
|
+
|
|
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.
|
|
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
|
+
|
|
125
|
+
### `pulse source wisqars`: Injury and Violence Data
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
pulse source wisqars list
|
|
129
|
+
pulse source wisqars mortality --intent Suicide --mechanism Firearm -f csv # 1999-2016
|
|
130
|
+
pulse source wisqars national --intent FA_Deaths --type year -f csv # 2019-present
|
|
131
|
+
pulse source wisqars state --intent Drug_OD --year 2023 -f table
|
|
132
|
+
pulse source wisqars county --state Texas --intent FA_Deaths --year 2023
|
|
133
|
+
pulse source wisqars tract --state Texas --intent All_Homicide --year 2022 # census-tract granularity
|
|
134
|
+
pulse source wisqars query t6u2-f84c --where "intent='Drug_OD' AND type='year'"
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
Fatal firearm, suicide, homicide, and drug overdose data from [WISQARS](https://wisqars.cdc.gov/) at national, state, county, and census tract granularity, backed by the same Socrata client as `cdc-open`.
|
|
138
|
+
|
|
139
|
+
### `pulse source grasp`: ATSDR GRASP Disease Surveillance
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
pulse source grasp list
|
|
143
|
+
pulse source grasp hantavirus cases --outcome Dead -f table # pre-1993-present
|
|
144
|
+
pulse source grasp hantavirus by-year -f table
|
|
145
|
+
pulse source grasp hantavirus by-state -f table
|
|
146
|
+
pulse source grasp fluview ili-data --region nat --region ca --region tx --epiweeks 202001-202026
|
|
147
|
+
pulse source grasp fluview ili-by-region --epiweeks 201940-202020 -f table
|
|
148
|
+
pulse source grasp fluview clinical-data --region nat --epiweeks 202001-202026
|
|
149
|
+
pulse source grasp flusurv data --location CA --location OH --epiweeks 202001-202020 -f csv
|
|
150
|
+
pulse source grasp flusurv by-season --location CA -f table
|
|
151
|
+
pulse source grasp flusurv by-location --season 2019-20 -f table
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
Hantavirus cases, FluView ILINet influenza-like-illness activity, WHO/NREVSS clinical lab flu positivity, and FluSurv-NET hospitalization rates, from [gis.cdc.gov/grasp](https://gis.cdc.gov/grasp/) and the CMU Delphi Epidata API. Repeatable options like `--region` and `--location` take one value per flag (`--region nat --region ca`), unlike `health`'s argparse CLI, which accepts a space separated list after a single flag.
|
|
155
|
+
|
|
156
|
+
### `pulse source nssp`: Emergency Department Visit Surveillance
|
|
157
|
+
|
|
158
|
+
```bash
|
|
159
|
+
pulse source nssp query covid --geo-type state --geo-value ca -f csv
|
|
160
|
+
pulse source nssp query influenza --geo-type nation --geo-value us
|
|
161
|
+
pulse source nssp national --start 202401 -f csv # all 4 pathogens, national
|
|
162
|
+
pulse source nssp hhs rsv --region 4 -f table
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
Weekly percentage of ED visits attributed to COVID, flu, and RSV from the [National Syndromic Surveillance Program](https://www.cdc.gov/nssp/), via the CMU Delphi Epidata API. Time values use epiweek format (`YYYYWW`, so `202518` is week 18 of 2025).
|
|
166
|
+
|
|
167
|
+
### `pulse source nis`: National Immunization Survey
|
|
168
|
+
|
|
169
|
+
```bash
|
|
170
|
+
pulse source nis list child # available years, 2011-2022
|
|
171
|
+
pulse source nis stream child 2022 --limit 10 -f json # raw respondent microdata
|
|
172
|
+
pulse source nis rates child 2022 --vaccines P_UTD431 -f table # state-level UTD rates
|
|
173
|
+
pulse source nis rates teen 2022 --vaccines P_UTDHPV13 -f csv
|
|
174
|
+
pulse source nis national child 2022 # national UTD summary
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
Childhood (19-35mo) and teen (13-17yr) vaccination coverage from CDC's annual random-digit-dial survey. The source files are large fixed-width `.dat` files (50-200MB), and `pulse` streams them straight through without writing anything to disk.
|
|
178
|
+
|
|
179
|
+
Two things to know. 2015 is missing from both surveys: `list child` reports 2011-2022 and `list teen` reports 2011-2024, each skipping 2015.
|
|
180
|
+
|
|
181
|
+
`rates` and `national` return one column per vaccine, 30 or more in total, which is more than `-f table` can fit on a terminal. The renderer squeezes every column to zero width and prints a grid of empty cells, which looks like the query returned nothing. The data is there: narrow it with `--vaccines`, as above, or use `-f csv` or `-f json` to get every column.
|
|
182
|
+
|
|
183
|
+
## Docs
|
|
184
|
+
|
|
185
|
+
- [cdc-wonder.md](docs/cdc-wonder.md), the full `wonder` command reference and bundled dataset table
|
|
186
|
+
- [building-xml-queries.md](docs/building-xml-queries.md), how to write WONDER XML for a dataset with no template
|
|
187
|
+
- [llm-providers.md](docs/llm-providers.md), Anthropic, Azure OpenAI, and proxy configuration
|
|
188
|
+
- [test.md](docs/test.md), running the tests and previewing the generated site
|
|
189
|
+
- [release.md](docs/release.md), how a release is cut and what to do when one half-fails
|
|
190
|
+
|
|
191
|
+
## Related Projects
|
|
192
|
+
|
|
193
|
+
`pulse` is the exploration layer of various projects:
|
|
194
|
+
|
|
195
|
+
```bash
|
|
196
|
+
pulse-code → health → health-charts
|
|
197
|
+
(explore) (archive) (visualize)
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
[fartbagxp/health](https://github.com/fartbagxp/health) archives the same sources as this project on a schedule. It's also home to the CDC WONDER XML API client and LLM query builder this tool builds on.
|
|
201
|
+
|
|
202
|
+
**pulse** is where a query starts; **health** is where it graduates once someone wants to collect it as a scheduled job. 23 of the 59 saved WONDER queries in `src/pulse/queries/` are also in `health`, each wrapped in a `fetch_*.py` script. The rest are exploration only for now — cancer and AIDS broken out by state, fetal deaths by race, PM2.5 by state, deaths by place of death, plus a pile of demographic slices for COVID, opioids, and maternal mortality. `pulse`'s source clients are standalone reimplementations of `health`'s modules, kept to just `requests` instead of pulling in the `pandas`/`playwright`/`lxml` stack that `health`'s pipelines need.
|
|
203
|
+
|
|
204
|
+
[fartbagxp/health-charts](https://github.com/fartbagxp/health-charts) reads those archived CSVs from GitHub and renders them as an interactive chart site.
|
|
@@ -1,28 +1,29 @@
|
|
|
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
|
-
requires-python = ">=3.
|
|
11
|
+
requires-python = ">=3.11"
|
|
12
12
|
dependencies = [
|
|
13
|
-
"anthropic==
|
|
14
|
-
"openai==
|
|
15
|
-
"
|
|
16
|
-
"
|
|
13
|
+
"anthropic==1.4.0",
|
|
14
|
+
"openai==3.11.0",
|
|
15
|
+
"openpyxl==3.1.5",
|
|
16
|
+
"pydantic==2.13.5",
|
|
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]
|
|
24
25
|
dev = [
|
|
25
|
-
"pre-commit==4.6.
|
|
26
|
+
"pre-commit==4.6.2",
|
|
26
27
|
"pytest==9.1.1",
|
|
27
28
|
]
|
|
28
29
|
|