pulse-code 1.1.0__tar.gz → 1.1.2__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/PKG-INFO +200 -0
- pulse_code-1.1.2/README.md +182 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/pyproject.toml +8 -8
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/cli.py +180 -1
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/data/cdc_open_catalog.json +51 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/data/queries_index.json +210 -3
- pulse_code-1.1.2/src/pulse/dqs_catalog.py +116 -0
- pulse_code-1.1.2/src/pulse/dqs_sdk.py +102 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/grasp_catalog.py +2 -2
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/grasp_client.py +1 -1
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/grasp_sdk.py +1 -1
- pulse_code-1.1.2/src/pulse/queries/aids-cases-by-age-1981-1999-req.xml +178 -0
- pulse_code-1.1.2/src/pulse/queries/aids-cases-by-location-1981-1999-req.xml +178 -0
- pulse_code-1.1.2/src/pulse/queries/aids-cases-by-race-1981-1999-req.xml +178 -0
- pulse_code-1.1.2/src/pulse/queries/aids-cases-by-sex-1981-1999-req.xml +178 -0
- pulse_code-1.1.2/src/pulse/queries/births-by-age-of-mother-2007-2024-req.xml +334 -0
- pulse_code-1.1.2/src/pulse/queries/births-by-race-2007-2024-req.xml +334 -0
- pulse_code-1.1.2/src/pulse/queries/cancer-incidence-by-state-1999-2022-req.xml +174 -0
- pulse_code-1.1.2/src/pulse/queries/cancer-mortality-by-state-2018-2023-req.xml +166 -0
- pulse_code-1.1.2/src/pulse/queries/covid-deaths-by-age-2020-2023-req.xml +533 -0
- pulse_code-1.1.2/src/pulse/queries/covid-deaths-by-age-sex-2020-2023-req.xml +533 -0
- pulse_code-1.1.2/src/pulse/queries/covid-deaths-by-sex-2020-2023-req.xml +533 -0
- pulse_code-1.1.2/src/pulse/queries/deaths-by-place-of-death-2018-2024-req.xml +538 -0
- pulse_code-1.1.2/src/pulse/queries/fetal-deaths-by-age-of-mother-2005-2024-req.xml +322 -0
- pulse_code-1.1.2/src/pulse/queries/fetal-deaths-by-race-2005-2024-req.xml +322 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/heat-wave-days-by-county-req.xml +1 -1
- pulse_code-1.1.2/src/pulse/queries/maternal-mortality-by-race-2018-2024-req.xml +413 -0
- pulse_code-1.1.2/src/pulse/queries/opioid-deaths-by-age-2018-2024-req.xml +544 -0
- pulse_code-1.1.2/src/pulse/queries/opioid-deaths-by-sex-2018-2024-req.xml +544 -0
- pulse_code-1.1.2/src/pulse/queries/pm25-by-state-2003-2011-req.xml +194 -0
- pulse_code-1.1.2/src/pulse/queries/std-cases-by-state-1984-2014-req.xml +178 -0
- pulse_code-1.1.2/src/pulse/queries/tick-borne-diseases-by-age-2016-2023-req.xml +125 -0
- pulse_code-1.1.2/src/pulse/queries/tick-borne-diseases-by-race-2016-2023-req.xml +125 -0
- pulse_code-1.1.2/src/pulse/queries/tick-borne-diseases-by-sex-2016-2023-req.xml +125 -0
- pulse_code-1.1.2/src/pulse/queries/tick-borne-diseases-by-state-2016-2023-req.xml +125 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/sources_registry.py +16 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/topics_registry.py +94 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/wonder_client.py +1 -1
- pulse_code-1.1.2/src/pulse_code.egg-info/PKG-INFO +200 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse_code.egg-info/SOURCES.txt +25 -0
- pulse_code-1.1.2/src/pulse_code.egg-info/requires.txt +8 -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.2}/LICENSE +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/setup.cfg +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/__init__.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/__main__.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/catalog.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/cdc_open_catalog.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/data/catalog.json +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/data/seer_var_formats.json +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/data/variable_labels.json +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/llm_builder.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/matcher.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/nis_catalog.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/nis_parser.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/nis_sdk.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/nssp_client.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/nssp_sdk.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/aids-cases-by-year-1981-1999-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/births-by-year-1995-2002-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/births-by-year-2003-2006-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/births-by-year-2007-2024-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/cancer-incidence-by-site-by-year-1999-2022-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/cancer-mortality-by-site-by-year-2018-2023-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/covid-deaths-by-race-2020-2023-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/drug-deaths-by-month-1999-2020-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/drug-deaths-by-month-2018-2024-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/drug-deaths-by-year-1999-2020-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/drug-deaths-by-year-2018-2024-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/fentanyl-deaths-by-month-1999-2020-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/fentanyl-deaths-by-month-2018-2024-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/fetal-deaths-by-cause-by-year-2014-2024-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/fetal-deaths-by-year-2005-2024-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/heart-vs-cancer-by-sex-2018-2023-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/infant-mortality-2018-2023-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/infant-mortality-by-cause-by-year-2007-2023-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/maternal-mortality-by-year-1999-2020-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/maternal-mortality-by-year-2018-2024-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/mortality-by-race-sex-2018-2023-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/mortality-by-year-cause-1979-1998-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/mortality-by-year-cause-1999-2020-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/mortality-by-year-cause-2021-2024-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/opioid-overdose-deaths-2018-2024-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/pm25-by-year-2003-2011-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/provisional-births-by-month-2023-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/racial-mortality-gap-2018-2023-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/std-cases-by-disease-by-year-1984-2014-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/suicide-by-sex-1999-2020-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/suicide-by-sex-2021-2024-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/tb-cases-by-year-1993-2023-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/tick-borne-diseases-by-year-2016-2023-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/underlying-cause-mortality-by-year-1999-2020-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/unintentional-injuries-by-age-2018-2023-req.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/seer_catalog.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/seer_client.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/seer_sdk.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/soda_client.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D10-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D104-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D117-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D128-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D140-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D141-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D149-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D157-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D158-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D159-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D16-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D176-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D178-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D18-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D192-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D204-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D23-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D27-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D31-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D60-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D61-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D66-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D69-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D73-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D74-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D76-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D77-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D8-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D80-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D81-base.xml +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/wisqars_catalog.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/wisqars_sdk.py +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse_code.egg-info/dependency_links.txt +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse_code.egg-info/entry_points.txt +0 -0
- {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse_code.egg-info/top_level.txt +0 -0
|
@@ -0,0 +1,200 @@
|
|
|
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
|
+
# 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
|
+
`pulse` is a command line tool for querying public health data. It covers eight live sources: CDC WONDER, NCI SEER cancer statistics, CDC Open Data, the NCHS Data Query System (Health, United States), WISQARS injury data, ATSDR GRASP disease surveillance, NSSP ED visits, and NIS vaccination surveys. Browse them by topic, run bundled queries, and get CSV, JSON, or a table back.
|
|
28
|
+
|
|
29
|
+

|
|
30
|
+
|
|
31
|
+
## Setup
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
# From PyPI (requires Python 3.11+)
|
|
35
|
+
pip install pulse-code
|
|
36
|
+
pulse --help
|
|
37
|
+
|
|
38
|
+
# From uv in this local directory
|
|
39
|
+
uv run pulse --help
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Querying any of the eight sources needs no API key or login. The `build`, `query`, `refine`, `compare`, and `chat` commands call an LLM to write CDC WONDER XML for you, so those need a key:
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
export ANTHROPIC_API_KEY=sk-ant-...
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Azure OpenAI and proxied connections work too; see [docs/llm-providers.md](docs/llm-providers.md).
|
|
49
|
+
|
|
50
|
+
## Usage
|
|
51
|
+
|
|
52
|
+
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.
|
|
53
|
+
|
|
54
|
+
Start with a subject if you don't know which source holds what you want:
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
pulse topics # every subject across all eight sources
|
|
58
|
+
pulse topics mortality # drill into one
|
|
59
|
+
pulse search "opioid overdose deaths by state"
|
|
60
|
+
pulse search "tick-borne disease cases" --queries # queries only
|
|
61
|
+
pulse search "recent COVID deaths" --datasets # datasets only
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Or go straight at a source. Each one nests the same way:
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
pulse source # what sources exist
|
|
68
|
+
pulse source seer # what that source offers
|
|
69
|
+
pulse source seer mortality # query it
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
### `pulse source wonder`: CDC WONDER
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
pulse source wonder datasets # 26+ datasets
|
|
76
|
+
pulse source wonder info D176 # provisional mortality
|
|
77
|
+
pulse source wonder run drug-deaths-by-year-2018-2024-req.xml -f csv
|
|
78
|
+
pulse source wonder query "fentanyl deaths by state 2020-2024" -f csv
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
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).
|
|
82
|
+
|
|
83
|
+
### `pulse source seer`: NCI SEER Cancer Statistics
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
pulse source seer sites --search breast # look up a cancer site code
|
|
87
|
+
pulse source seer mortality --site 55 --sex female -f csv
|
|
88
|
+
pulse source seer mortality --site 47 --compare-by race -f csv
|
|
89
|
+
pulse source seer incidence --site 55 --stage 104 -f csv
|
|
90
|
+
pulse source seer by-age --site 1 -f csv
|
|
91
|
+
pulse source seer compare-sites 55 47 66 -f csv # breast vs. lung vs. melanoma
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
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.
|
|
95
|
+
|
|
96
|
+
### `pulse source cdc-open`: CDC Open Data (data.cdc.gov)
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
pulse source cdc-open list # 60+ datasets: mortality, vaccination, wastewater, NNDSS, HAI, and more
|
|
100
|
+
pulse source cdc-open list --search wastewater
|
|
101
|
+
pulse source cdc-open query leading_death --where "year='2015'" -f csv
|
|
102
|
+
pulse source cdc-open query bi63-dtpu --where "state='California'" --limit 500 -f json
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
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.
|
|
106
|
+
|
|
107
|
+
### `pulse source dqs`: NCHS Data Query System (Health, United States)
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
pulse source dqs list # 28 datasets across 17 topics
|
|
111
|
+
pulse source dqs list --topic "Chronic Disease" # filter by topic bucket
|
|
112
|
+
pulse source dqs list --search cholesterol
|
|
113
|
+
pulse source dqs trend drug-overdose-deaths -f csv # all-persons national trend, oldest→newest
|
|
114
|
+
pulse source dqs trend cholesterol-adults --list-measures # see a dataset's estimate types
|
|
115
|
+
pulse source dqs trend cholesterol-adults -e "mg/dL, age adjusted" -f csv
|
|
116
|
+
pulse source dqs query nhis-adult --where "classification='Total'" --limit 500 -f json
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
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
|
+
### `pulse source wisqars`: Injury and Violence Data
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
pulse source wisqars list
|
|
125
|
+
pulse source wisqars mortality --intent Suicide --mechanism Firearm -f csv # 1999-2016
|
|
126
|
+
pulse source wisqars national --intent FA_Deaths --type year -f csv # 2019-present
|
|
127
|
+
pulse source wisqars state --intent Drug_OD --year 2023 -f table
|
|
128
|
+
pulse source wisqars county --state Texas --intent FA_Deaths --year 2023
|
|
129
|
+
pulse source wisqars tract --state Texas --intent All_Homicide --year 2022 # census-tract granularity
|
|
130
|
+
pulse source wisqars query t6u2-f84c --where "intent='Drug_OD' AND type='year'"
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
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`.
|
|
134
|
+
|
|
135
|
+
### `pulse source grasp`: ATSDR GRASP Disease Surveillance
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
pulse source grasp list
|
|
139
|
+
pulse source grasp hantavirus cases --outcome Dead -f table # pre-1993-present
|
|
140
|
+
pulse source grasp hantavirus by-year -f table
|
|
141
|
+
pulse source grasp hantavirus by-state -f table
|
|
142
|
+
pulse source grasp fluview ili-data --region nat --region ca --region tx --epiweeks 202001-202026
|
|
143
|
+
pulse source grasp fluview ili-by-region --epiweeks 201940-202020 -f table
|
|
144
|
+
pulse source grasp fluview clinical-data --region nat --epiweeks 202001-202026
|
|
145
|
+
pulse source grasp flusurv data --location CA --location OH --epiweeks 202001-202020 -f csv
|
|
146
|
+
pulse source grasp flusurv by-season --location CA -f table
|
|
147
|
+
pulse source grasp flusurv by-location --season 2019-20 -f table
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
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.
|
|
151
|
+
|
|
152
|
+
### `pulse source nssp`: Emergency Department Visit Surveillance
|
|
153
|
+
|
|
154
|
+
```bash
|
|
155
|
+
pulse source nssp query covid --geo-type state --geo-value ca -f csv
|
|
156
|
+
pulse source nssp query influenza --geo-type nation --geo-value us
|
|
157
|
+
pulse source nssp national --start 202401 -f csv # all 4 pathogens, national
|
|
158
|
+
pulse source nssp hhs rsv --region 4 -f table
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
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).
|
|
162
|
+
|
|
163
|
+
### `pulse source nis`: National Immunization Survey
|
|
164
|
+
|
|
165
|
+
```bash
|
|
166
|
+
pulse source nis list child # available years, 2011-2022
|
|
167
|
+
pulse source nis stream child 2022 --limit 10 -f json # raw respondent microdata
|
|
168
|
+
pulse source nis rates child 2022 --vaccines P_UTD431 -f table # state-level UTD rates
|
|
169
|
+
pulse source nis rates teen 2022 --vaccines P_UTDHPV13 -f csv
|
|
170
|
+
pulse source nis national child 2022 # national UTD summary
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
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.
|
|
174
|
+
|
|
175
|
+
Two things to know. 2015 is missing from both surveys: `list child` reports 2011-2022 and `list teen` reports 2011-2024, each skipping 2015.
|
|
176
|
+
|
|
177
|
+
`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.
|
|
178
|
+
|
|
179
|
+
## Docs
|
|
180
|
+
|
|
181
|
+
- [cdc-wonder.md](docs/cdc-wonder.md), the full `wonder` command reference and bundled dataset table
|
|
182
|
+
- [building-xml-queries.md](docs/building-xml-queries.md), how to write WONDER XML for a dataset with no template
|
|
183
|
+
- [llm-providers.md](docs/llm-providers.md), Anthropic, Azure OpenAI, and proxy configuration
|
|
184
|
+
- [test.md](docs/test.md), running the tests and previewing the generated site
|
|
185
|
+
- [release.md](docs/release.md), how a release is cut and what to do when one half-fails
|
|
186
|
+
|
|
187
|
+
## Related Projects
|
|
188
|
+
|
|
189
|
+
`pulse` is the exploration layer of various projects:
|
|
190
|
+
|
|
191
|
+
```bash
|
|
192
|
+
pulse-code → health → health-charts
|
|
193
|
+
(explore) (archive) (visualize)
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
[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.
|
|
197
|
+
|
|
198
|
+
**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.
|
|
199
|
+
|
|
200
|
+
[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,182 @@
|
|
|
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 eight live sources: CDC WONDER, NCI SEER cancer statistics, CDC Open Data, the NCHS Data Query System (Health, United States), WISQARS injury data, ATSDR GRASP disease surveillance, NSSP ED visits, and NIS vaccination surveys. Browse them by topic, run bundled queries, and get CSV, JSON, or a table back.
|
|
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 eight sources needs no API key or login. The `build`, `query`, `refine`, `compare`, and `chat` commands call an LLM to write CDC WONDER XML for you, so those need a key:
|
|
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 eight 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 wisqars`: Injury and Violence Data
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
pulse source wisqars list
|
|
107
|
+
pulse source wisqars mortality --intent Suicide --mechanism Firearm -f csv # 1999-2016
|
|
108
|
+
pulse source wisqars national --intent FA_Deaths --type year -f csv # 2019-present
|
|
109
|
+
pulse source wisqars state --intent Drug_OD --year 2023 -f table
|
|
110
|
+
pulse source wisqars county --state Texas --intent FA_Deaths --year 2023
|
|
111
|
+
pulse source wisqars tract --state Texas --intent All_Homicide --year 2022 # census-tract granularity
|
|
112
|
+
pulse source wisqars query t6u2-f84c --where "intent='Drug_OD' AND type='year'"
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
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`.
|
|
116
|
+
|
|
117
|
+
### `pulse source grasp`: ATSDR GRASP Disease Surveillance
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
pulse source grasp list
|
|
121
|
+
pulse source grasp hantavirus cases --outcome Dead -f table # pre-1993-present
|
|
122
|
+
pulse source grasp hantavirus by-year -f table
|
|
123
|
+
pulse source grasp hantavirus by-state -f table
|
|
124
|
+
pulse source grasp fluview ili-data --region nat --region ca --region tx --epiweeks 202001-202026
|
|
125
|
+
pulse source grasp fluview ili-by-region --epiweeks 201940-202020 -f table
|
|
126
|
+
pulse source grasp fluview clinical-data --region nat --epiweeks 202001-202026
|
|
127
|
+
pulse source grasp flusurv data --location CA --location OH --epiweeks 202001-202020 -f csv
|
|
128
|
+
pulse source grasp flusurv by-season --location CA -f table
|
|
129
|
+
pulse source grasp flusurv by-location --season 2019-20 -f table
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
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.
|
|
133
|
+
|
|
134
|
+
### `pulse source nssp`: Emergency Department Visit Surveillance
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
pulse source nssp query covid --geo-type state --geo-value ca -f csv
|
|
138
|
+
pulse source nssp query influenza --geo-type nation --geo-value us
|
|
139
|
+
pulse source nssp national --start 202401 -f csv # all 4 pathogens, national
|
|
140
|
+
pulse source nssp hhs rsv --region 4 -f table
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
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).
|
|
144
|
+
|
|
145
|
+
### `pulse source nis`: National Immunization Survey
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
pulse source nis list child # available years, 2011-2022
|
|
149
|
+
pulse source nis stream child 2022 --limit 10 -f json # raw respondent microdata
|
|
150
|
+
pulse source nis rates child 2022 --vaccines P_UTD431 -f table # state-level UTD rates
|
|
151
|
+
pulse source nis rates teen 2022 --vaccines P_UTDHPV13 -f csv
|
|
152
|
+
pulse source nis national child 2022 # national UTD summary
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
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.
|
|
156
|
+
|
|
157
|
+
Two things to know. 2015 is missing from both surveys: `list child` reports 2011-2022 and `list teen` reports 2011-2024, each skipping 2015.
|
|
158
|
+
|
|
159
|
+
`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.
|
|
160
|
+
|
|
161
|
+
## Docs
|
|
162
|
+
|
|
163
|
+
- [cdc-wonder.md](docs/cdc-wonder.md), the full `wonder` command reference and bundled dataset table
|
|
164
|
+
- [building-xml-queries.md](docs/building-xml-queries.md), how to write WONDER XML for a dataset with no template
|
|
165
|
+
- [llm-providers.md](docs/llm-providers.md), Anthropic, Azure OpenAI, and proxy configuration
|
|
166
|
+
- [test.md](docs/test.md), running the tests and previewing the generated site
|
|
167
|
+
- [release.md](docs/release.md), how a release is cut and what to do when one half-fails
|
|
168
|
+
|
|
169
|
+
## Related Projects
|
|
170
|
+
|
|
171
|
+
`pulse` is the exploration layer of various projects:
|
|
172
|
+
|
|
173
|
+
```bash
|
|
174
|
+
pulse-code → health → health-charts
|
|
175
|
+
(explore) (archive) (visualize)
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
[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.
|
|
179
|
+
|
|
180
|
+
**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.
|
|
181
|
+
|
|
182
|
+
[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,28 @@
|
|
|
1
1
|
[build-system]
|
|
2
|
-
requires = ["setuptools==
|
|
2
|
+
requires = ["setuptools==83.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.2"
|
|
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==
|
|
13
|
+
"anthropic==1.1.0",
|
|
14
|
+
"openai==3.5.0",
|
|
15
15
|
"pydantic==2.13.4",
|
|
16
|
-
"python-dotenv==1.2.
|
|
16
|
+
"python-dotenv==1.2.3",
|
|
17
17
|
"requests==2.34.2",
|
|
18
18
|
"rich==15.0.0",
|
|
19
19
|
"socksio==1.0.0",
|
|
20
|
-
"typer==0.27.
|
|
20
|
+
"typer==0.27.1",
|
|
21
21
|
]
|
|
22
22
|
|
|
23
23
|
[dependency-groups]
|
|
24
24
|
dev = [
|
|
25
|
-
"pre-commit==4.6.
|
|
25
|
+
"pre-commit==4.6.2",
|
|
26
26
|
"pytest==9.1.1",
|
|
27
27
|
]
|
|
28
28
|
|
|
@@ -6,6 +6,7 @@ import csv
|
|
|
6
6
|
import io
|
|
7
7
|
import json
|
|
8
8
|
import time
|
|
9
|
+
from importlib.metadata import PackageNotFoundError, version as _pkg_version
|
|
9
10
|
from pathlib import Path
|
|
10
11
|
from typing import Annotated, Optional
|
|
11
12
|
|
|
@@ -22,6 +23,13 @@ from pulse.catalog import Catalog
|
|
|
22
23
|
from pulse.cdc_open_catalog import dataset as cdc_open_dataset
|
|
23
24
|
from pulse.cdc_open_catalog import datasets as cdc_open_datasets
|
|
24
25
|
from pulse.cdc_open_catalog import search as cdc_open_search
|
|
26
|
+
from pulse.dqs_catalog import dataset as dqs_dataset
|
|
27
|
+
from pulse.dqs_catalog import datasets as dqs_datasets
|
|
28
|
+
from pulse.dqs_catalog import search as dqs_search
|
|
29
|
+
from pulse.dqs_catalog import topics as dqs_topic_list
|
|
30
|
+
from pulse.dqs_sdk import estimate_types as dqs_estimate_types
|
|
31
|
+
from pulse.dqs_sdk import query as dqs_query
|
|
32
|
+
from pulse.dqs_sdk import trend as dqs_trend
|
|
25
33
|
from pulse.grasp_catalog import DATASETS as GRASP_DATASETS
|
|
26
34
|
from pulse.grasp_catalog import FLUSURV_LOCATIONS
|
|
27
35
|
from pulse.grasp_sdk import (
|
|
@@ -129,6 +137,33 @@ app = typer.Typer(
|
|
|
129
137
|
add_completion=False,
|
|
130
138
|
no_args_is_help=True,
|
|
131
139
|
)
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
def _version_callback(value: bool) -> None:
|
|
143
|
+
if value:
|
|
144
|
+
try:
|
|
145
|
+
ver = _pkg_version("pulse-code")
|
|
146
|
+
except PackageNotFoundError: # running from a source tree without install metadata
|
|
147
|
+
ver = "unknown"
|
|
148
|
+
typer.echo(f"pulse {ver}")
|
|
149
|
+
raise typer.Exit()
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
@app.callback()
|
|
153
|
+
def main_callback(
|
|
154
|
+
version: Annotated[
|
|
155
|
+
Optional[bool],
|
|
156
|
+
typer.Option(
|
|
157
|
+
"--version",
|
|
158
|
+
callback=_version_callback,
|
|
159
|
+
is_eager=True,
|
|
160
|
+
help="Show the pulse version and exit.",
|
|
161
|
+
),
|
|
162
|
+
] = None,
|
|
163
|
+
) -> None:
|
|
164
|
+
"""CDC public health data query CLI."""
|
|
165
|
+
|
|
166
|
+
|
|
132
167
|
# `source` is a group that does double duty: bare `pulse source` prints the
|
|
133
168
|
# 7-source overview, `pulse source <name>` prints that source's dataset list,
|
|
134
169
|
# and `pulse source <name> <verb>` runs a query. Each source sub-app therefore
|
|
@@ -158,6 +193,12 @@ cdc_open_app = typer.Typer(
|
|
|
158
193
|
no_args_is_help=False,
|
|
159
194
|
invoke_without_command=True,
|
|
160
195
|
)
|
|
196
|
+
dqs_app = typer.Typer(
|
|
197
|
+
help="NCHS Data Query System — Health, United States topics (NHANES/NHIS/NHAMCS/NVSS).",
|
|
198
|
+
add_completion=False,
|
|
199
|
+
no_args_is_help=False,
|
|
200
|
+
invoke_without_command=True,
|
|
201
|
+
)
|
|
161
202
|
wisqars_app = typer.Typer(
|
|
162
203
|
help="WISQARS injury mortality and violence data.",
|
|
163
204
|
add_completion=False,
|
|
@@ -201,6 +242,7 @@ app.add_typer(source_app, name="source")
|
|
|
201
242
|
source_app.add_typer(wonder_app, name="wonder")
|
|
202
243
|
source_app.add_typer(seer_app, name="seer")
|
|
203
244
|
source_app.add_typer(cdc_open_app, name="cdc-open")
|
|
245
|
+
source_app.add_typer(dqs_app, name="dqs")
|
|
204
246
|
source_app.add_typer(wisqars_app, name="wisqars")
|
|
205
247
|
source_app.add_typer(grasp_app, name="grasp")
|
|
206
248
|
grasp_app.add_typer(grasp_hantavirus_app, name="hantavirus")
|
|
@@ -1185,6 +1227,13 @@ def _render_source_overview(json_out: bool) -> None:
|
|
|
1185
1227
|
"count": len(cdc_open_datasets()),
|
|
1186
1228
|
"years": "varies",
|
|
1187
1229
|
},
|
|
1230
|
+
{
|
|
1231
|
+
"name": "DQS",
|
|
1232
|
+
"command": "pulse source dqs list / query / trend",
|
|
1233
|
+
"coverage": "Health, United States — chronic disease, nutrition, disability, health-care system, spending",
|
|
1234
|
+
"count": len(dqs_datasets()),
|
|
1235
|
+
"years": "1960–present",
|
|
1236
|
+
},
|
|
1188
1237
|
{
|
|
1189
1238
|
"name": "WISQARS",
|
|
1190
1239
|
"command": "pulse source wisqars mortality / national / state / county / tract / query",
|
|
@@ -1276,6 +1325,16 @@ def cdc_open_callback(
|
|
|
1276
1325
|
_render_source_datasets("cdc-open", json_out)
|
|
1277
1326
|
|
|
1278
1327
|
|
|
1328
|
+
@dqs_app.callback(invoke_without_command=True)
|
|
1329
|
+
def dqs_callback(
|
|
1330
|
+
ctx: typer.Context,
|
|
1331
|
+
json_out: Annotated[bool, typer.Option("--json")] = False,
|
|
1332
|
+
):
|
|
1333
|
+
"""Bare `pulse source dqs` lists DQS datasets; subcommands query them."""
|
|
1334
|
+
if ctx.invoked_subcommand is None:
|
|
1335
|
+
_render_source_datasets("dqs", json_out)
|
|
1336
|
+
|
|
1337
|
+
|
|
1279
1338
|
@wisqars_app.callback(invoke_without_command=True)
|
|
1280
1339
|
def wisqars_callback(
|
|
1281
1340
|
ctx: typer.Context,
|
|
@@ -1322,7 +1381,8 @@ _DOCTOR_ENDPOINTS = [
|
|
|
1322
1381
|
("WONDER", "https://wonder.cdc.gov/"),
|
|
1323
1382
|
("SEER", "https://seer.cancer.gov/statistics-network/explorer/"),
|
|
1324
1383
|
("CDC Open Data / WISQARS", "https://data.cdc.gov/resource/bi63-dtpu.json?$limit=1"),
|
|
1325
|
-
("
|
|
1384
|
+
("DQS", "https://data.cdc.gov/resource/rdjz-vn2n.json?$limit=1"),
|
|
1385
|
+
("GRASP", GRASP_DATASETS["hantavirus"].url),
|
|
1326
1386
|
("GRASP / NSSP (Delphi)", "https://api.delphi.cmu.edu/epidata/covidcast_meta/"),
|
|
1327
1387
|
# A specific year's file, not the bare directory listing — the directory
|
|
1328
1388
|
# itself returns 200 even for missing files. 2022 lives on the newer
|
|
@@ -1795,6 +1855,125 @@ def cmd_cdc_open_query(
|
|
|
1795
1855
|
_print_rows(rows, format, output)
|
|
1796
1856
|
|
|
1797
1857
|
|
|
1858
|
+
# ── dqs ───────────────────────────────────────────────────────────────────────
|
|
1859
|
+
|
|
1860
|
+
|
|
1861
|
+
@dqs_app.command("list")
|
|
1862
|
+
def cmd_dqs_list(
|
|
1863
|
+
search: Annotated[Optional[str], typer.Option("--search", "-s", help="Substring match on key/name/topic/survey")] = None,
|
|
1864
|
+
topic: Annotated[Optional[str], typer.Option("--topic", "-t", help="Filter to one topic bucket")] = None,
|
|
1865
|
+
json_out: Annotated[bool, typer.Option("--json")] = False,
|
|
1866
|
+
):
|
|
1867
|
+
"""List/search the NCHS DQS dataset registry (28 Health, United States tables)."""
|
|
1868
|
+
ds = dqs_search(search) if search else dqs_datasets()
|
|
1869
|
+
if topic:
|
|
1870
|
+
tl = topic.strip().lower()
|
|
1871
|
+
ds = [d for d in ds if tl in d.topic.lower()]
|
|
1872
|
+
|
|
1873
|
+
if json_out:
|
|
1874
|
+
print(
|
|
1875
|
+
json.dumps(
|
|
1876
|
+
[
|
|
1877
|
+
{
|
|
1878
|
+
"key": d.key,
|
|
1879
|
+
"id": d.id,
|
|
1880
|
+
"name": d.name,
|
|
1881
|
+
"topic": d.topic,
|
|
1882
|
+
"survey": d.survey,
|
|
1883
|
+
"years": d.years,
|
|
1884
|
+
"dimensions": d.dimensions,
|
|
1885
|
+
}
|
|
1886
|
+
for d in ds
|
|
1887
|
+
],
|
|
1888
|
+
indent=2,
|
|
1889
|
+
)
|
|
1890
|
+
)
|
|
1891
|
+
return
|
|
1892
|
+
|
|
1893
|
+
t = Table(box=box.ROUNDED, show_header=True, header_style="bold cyan", expand=True)
|
|
1894
|
+
t.add_column("Key", style="yellow", width=26, no_wrap=True)
|
|
1895
|
+
t.add_column("Topic", width=22, no_wrap=True)
|
|
1896
|
+
t.add_column("Survey", width=10, no_wrap=True)
|
|
1897
|
+
t.add_column("Years", width=12, no_wrap=True)
|
|
1898
|
+
t.add_column("Name", ratio=1)
|
|
1899
|
+
for d in ds:
|
|
1900
|
+
t.add_row(d.key, d.topic, d.survey, d.years, d.name)
|
|
1901
|
+
|
|
1902
|
+
console.print()
|
|
1903
|
+
console.print(t)
|
|
1904
|
+
console.print(
|
|
1905
|
+
f"\n[dim]{len(ds)} datasets | topics: {', '.join(dqs_topic_list())} | "
|
|
1906
|
+
f"[bold]pulse source dqs query <key>[/bold] or [bold]trend <key>[/bold][/dim]\n"
|
|
1907
|
+
)
|
|
1908
|
+
|
|
1909
|
+
|
|
1910
|
+
@dqs_app.command("query")
|
|
1911
|
+
def cmd_dqs_query(
|
|
1912
|
+
dataset_id: Annotated[str, typer.Argument(help="Registry key (e.g. drug-overdose-deaths) or Socrata ID")],
|
|
1913
|
+
where: Annotated[Optional[str], typer.Option("--where", help="SODA $where clause")] = None,
|
|
1914
|
+
select: Annotated[Optional[str], typer.Option("--select", help="SODA $select clause")] = None,
|
|
1915
|
+
group: Annotated[Optional[str], typer.Option("--group", help="SODA $group clause")] = None,
|
|
1916
|
+
order: Annotated[Optional[str], typer.Option("--order", help="SODA $order clause")] = None,
|
|
1917
|
+
limit: Annotated[int, typer.Option("--limit", help="Max rows")] = 200,
|
|
1918
|
+
format: Annotated[str, typer.Option("-f", "--format")] = "table",
|
|
1919
|
+
output: Annotated[Optional[Path], typer.Option("-o", "--output")] = None,
|
|
1920
|
+
):
|
|
1921
|
+
"""Run a raw SODA query against a DQS dataset. `classification='Total'` is the all-persons row."""
|
|
1922
|
+
ds = dqs_dataset(dataset_id)
|
|
1923
|
+
socrata_id = ds.id if ds else dataset_id
|
|
1924
|
+
err.print(f"[bold]Querying:[/bold] {socrata_id}" + (f" ({ds.name})" if ds else ""))
|
|
1925
|
+
|
|
1926
|
+
try:
|
|
1927
|
+
rows = dqs_query(dataset_id, where=where, select=select, group=group, order=order, limit=limit)
|
|
1928
|
+
except Exception as e:
|
|
1929
|
+
err.print(f"[red]Error from CDC DQS:[/red] {e}")
|
|
1930
|
+
raise typer.Exit(1)
|
|
1931
|
+
|
|
1932
|
+
_print_rows(rows, format, output)
|
|
1933
|
+
|
|
1934
|
+
|
|
1935
|
+
@dqs_app.command("trend")
|
|
1936
|
+
def cmd_dqs_trend(
|
|
1937
|
+
dataset_id: Annotated[str, typer.Argument(help="Registry key or Socrata ID")],
|
|
1938
|
+
estimate_type: Annotated[
|
|
1939
|
+
Optional[str], typer.Option("--estimate-type", "-e", help="Narrow to one measure (see --list-measures)")
|
|
1940
|
+
] = None,
|
|
1941
|
+
list_measures: Annotated[
|
|
1942
|
+
bool, typer.Option("--list-measures", help="Print the dataset's estimate_type values and exit")
|
|
1943
|
+
] = False,
|
|
1944
|
+
limit: Annotated[int, typer.Option("--limit")] = 1000,
|
|
1945
|
+
format: Annotated[str, typer.Option("-f", "--format")] = "table",
|
|
1946
|
+
output: Annotated[Optional[Path], typer.Option("-o", "--output")] = None,
|
|
1947
|
+
):
|
|
1948
|
+
"""All-persons ('Total') national trend for a DQS dataset, oldest→newest."""
|
|
1949
|
+
ds = dqs_dataset(dataset_id)
|
|
1950
|
+
socrata_id = ds.id if ds else dataset_id
|
|
1951
|
+
|
|
1952
|
+
if list_measures:
|
|
1953
|
+
try:
|
|
1954
|
+
measures = dqs_estimate_types(dataset_id)
|
|
1955
|
+
except Exception as e:
|
|
1956
|
+
err.print(f"[red]Error from CDC DQS:[/red] {e}")
|
|
1957
|
+
raise typer.Exit(1)
|
|
1958
|
+
err.print(f"[bold]{socrata_id}[/bold]" + (f" ({ds.name})" if ds else "") + " — estimate types:")
|
|
1959
|
+
for m in measures:
|
|
1960
|
+
console.print(f" • {m}")
|
|
1961
|
+
return
|
|
1962
|
+
|
|
1963
|
+
err.print(f"[bold]Trend:[/bold] {socrata_id}" + (f" ({ds.name})" if ds else ""))
|
|
1964
|
+
try:
|
|
1965
|
+
rows = dqs_trend(dataset_id, estimate_type=estimate_type, limit=limit)
|
|
1966
|
+
except Exception as e:
|
|
1967
|
+
err.print(f"[red]Error from CDC DQS:[/red] {e}")
|
|
1968
|
+
raise typer.Exit(1)
|
|
1969
|
+
|
|
1970
|
+
if not rows:
|
|
1971
|
+
err.print("[yellow]No 'Total' rows returned. Try `pulse source dqs query` with a --where filter.[/yellow]")
|
|
1972
|
+
raise typer.Exit(1)
|
|
1973
|
+
|
|
1974
|
+
_print_rows(rows, format, output)
|
|
1975
|
+
|
|
1976
|
+
|
|
1798
1977
|
# ── wisqars ───────────────────────────────────────────────────────────────────
|
|
1799
1978
|
|
|
1800
1979
|
_WISQARS_FORMAT = Annotated[str, typer.Option("-f", "--format", help="table|csv|json")]
|