pulse-code 1.0.2__tar.gz → 1.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (106) hide show
  1. {pulse_code-1.0.2/src/pulse_code.egg-info → pulse_code-1.1.0}/PKG-INFO +77 -71
  2. {pulse_code-1.0.2 → pulse_code-1.1.0}/README.md +76 -70
  3. {pulse_code-1.0.2 → pulse_code-1.1.0}/pyproject.toml +1 -1
  4. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/cdc_open_catalog.py +1 -1
  5. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/cli.py +350 -98
  6. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/nis_catalog.py +65 -18
  7. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/nis_parser.py +42 -1
  8. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/nis_sdk.py +8 -7
  9. pulse_code-1.1.0/src/pulse/sources_registry.py +143 -0
  10. pulse_code-1.1.0/src/pulse/topics_registry.py +208 -0
  11. {pulse_code-1.0.2 → pulse_code-1.1.0/src/pulse_code.egg-info}/PKG-INFO +77 -71
  12. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse_code.egg-info/SOURCES.txt +2 -0
  13. {pulse_code-1.0.2 → pulse_code-1.1.0}/LICENSE +0 -0
  14. {pulse_code-1.0.2 → pulse_code-1.1.0}/setup.cfg +0 -0
  15. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/__init__.py +0 -0
  16. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/__main__.py +0 -0
  17. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/catalog.py +0 -0
  18. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/data/catalog.json +0 -0
  19. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/data/cdc_open_catalog.json +0 -0
  20. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/data/queries_index.json +0 -0
  21. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/data/seer_var_formats.json +0 -0
  22. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/data/variable_labels.json +0 -0
  23. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/grasp_catalog.py +0 -0
  24. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/grasp_client.py +0 -0
  25. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/grasp_sdk.py +0 -0
  26. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/llm_builder.py +0 -0
  27. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/matcher.py +0 -0
  28. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/nssp_client.py +0 -0
  29. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/nssp_sdk.py +0 -0
  30. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/aids-cases-by-year-1981-1999-req.xml +0 -0
  31. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/births-by-year-1995-2002-req.xml +0 -0
  32. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/births-by-year-2003-2006-req.xml +0 -0
  33. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/births-by-year-2007-2024-req.xml +0 -0
  34. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/cancer-incidence-by-site-by-year-1999-2022-req.xml +0 -0
  35. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/cancer-mortality-by-site-by-year-2018-2023-req.xml +0 -0
  36. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/covid-deaths-by-race-2020-2023-req.xml +0 -0
  37. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/drug-deaths-by-month-1999-2020-req.xml +0 -0
  38. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/drug-deaths-by-month-2018-2024-req.xml +0 -0
  39. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/drug-deaths-by-year-1999-2020-req.xml +0 -0
  40. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/drug-deaths-by-year-2018-2024-req.xml +0 -0
  41. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/fentanyl-deaths-by-month-1999-2020-req.xml +0 -0
  42. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/fentanyl-deaths-by-month-2018-2024-req.xml +0 -0
  43. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/fetal-deaths-by-cause-by-year-2014-2024-req.xml +0 -0
  44. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/fetal-deaths-by-year-2005-2024-req.xml +0 -0
  45. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/heart-vs-cancer-by-sex-2018-2023-req.xml +0 -0
  46. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/heat-wave-days-by-county-req.xml +0 -0
  47. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/infant-mortality-2018-2023-req.xml +0 -0
  48. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/infant-mortality-by-cause-by-year-2007-2023-req.xml +0 -0
  49. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/maternal-mortality-by-year-1999-2020-req.xml +0 -0
  50. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/maternal-mortality-by-year-2018-2024-req.xml +0 -0
  51. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/mortality-by-race-sex-2018-2023-req.xml +0 -0
  52. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/mortality-by-year-cause-1979-1998-req.xml +0 -0
  53. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/mortality-by-year-cause-1999-2020-req.xml +0 -0
  54. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/mortality-by-year-cause-2021-2024-req.xml +0 -0
  55. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/opioid-overdose-deaths-2018-2024-req.xml +0 -0
  56. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/pm25-by-year-2003-2011-req.xml +0 -0
  57. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/provisional-births-by-month-2023-req.xml +0 -0
  58. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/racial-mortality-gap-2018-2023-req.xml +0 -0
  59. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/std-cases-by-disease-by-year-1984-2014-req.xml +0 -0
  60. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/suicide-by-sex-1999-2020-req.xml +0 -0
  61. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/suicide-by-sex-2021-2024-req.xml +0 -0
  62. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/tb-cases-by-year-1993-2023-req.xml +0 -0
  63. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/tick-borne-diseases-by-year-2016-2023-req.xml +0 -0
  64. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/underlying-cause-mortality-by-year-1999-2020-req.xml +0 -0
  65. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/queries/unintentional-injuries-by-age-2018-2023-req.xml +0 -0
  66. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/seer_catalog.py +0 -0
  67. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/seer_client.py +0 -0
  68. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/seer_sdk.py +0 -0
  69. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/soda_client.py +0 -0
  70. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/templates/D10-base.xml +0 -0
  71. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/templates/D104-base.xml +0 -0
  72. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/templates/D117-base.xml +0 -0
  73. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/templates/D128-base.xml +0 -0
  74. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/templates/D140-base.xml +0 -0
  75. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/templates/D141-base.xml +0 -0
  76. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/templates/D149-base.xml +0 -0
  77. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/templates/D157-base.xml +0 -0
  78. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/templates/D158-base.xml +0 -0
  79. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/templates/D159-base.xml +0 -0
  80. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/templates/D16-base.xml +0 -0
  81. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/templates/D176-base.xml +0 -0
  82. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/templates/D178-base.xml +0 -0
  83. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/templates/D18-base.xml +0 -0
  84. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/templates/D192-base.xml +0 -0
  85. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/templates/D204-base.xml +0 -0
  86. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/templates/D23-base.xml +0 -0
  87. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/templates/D27-base.xml +0 -0
  88. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/templates/D31-base.xml +0 -0
  89. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/templates/D60-base.xml +0 -0
  90. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/templates/D61-base.xml +0 -0
  91. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/templates/D66-base.xml +0 -0
  92. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/templates/D69-base.xml +0 -0
  93. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/templates/D73-base.xml +0 -0
  94. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/templates/D74-base.xml +0 -0
  95. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/templates/D76-base.xml +0 -0
  96. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/templates/D77-base.xml +0 -0
  97. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/templates/D8-base.xml +0 -0
  98. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/templates/D80-base.xml +0 -0
  99. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/templates/D81-base.xml +0 -0
  100. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/wisqars_catalog.py +0 -0
  101. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/wisqars_sdk.py +0 -0
  102. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse/wonder_client.py +0 -0
  103. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse_code.egg-info/dependency_links.txt +0 -0
  104. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse_code.egg-info/entry_points.txt +0 -0
  105. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse_code.egg-info/requires.txt +0 -0
  106. {pulse_code-1.0.2 → pulse_code-1.1.0}/src/pulse_code.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pulse-code
3
- Version: 1.0.2
3
+ Version: 1.1.0
4
4
  Summary: CDC WONDER query CLI — explore, build, and refine public health data queries
5
5
  License-Expression: CC0-1.0
6
6
  Requires-Python: >=3.14
@@ -90,24 +90,30 @@ export LLM_HTTP_PROXY=socks5h://user:pass@host:port
90
90
 
91
91
  ## Commands
92
92
 
93
- ### `pulse datasets` — what's available
93
+ The CLI has five top-level commands: **`topics`** (browse by subject across all
94
+ sources), **`source`** (browse/query one source), **`search`** (free-text find),
95
+ plus **`doctor`** and **`generate`**. Every data source lives under `source`:
96
+ `pulse source` for an overview, `pulse source <name>` for its datasets, and
97
+ `pulse source <name> <verb> …` to query it (e.g. `pulse source seer mortality`).
98
+
99
+ ### `pulse source wonder datasets` — what's available
94
100
 
95
101
  ```bash
96
- pulse datasets # all datasets
97
- pulse datasets --topic Mortality # filter by topic
98
- pulse datasets --json # JSON output
102
+ pulse source wonder datasets # all datasets
103
+ pulse source wonder datasets --topic Mortality # filter by topic
104
+ pulse source wonder datasets --json # JSON output
99
105
  ```
100
106
 
101
107
  Shows all 26+ CDC WONDER datasets with: topic, year range, what the data covers, number of bundled example queries, and whether age-adjusted rates are available.
102
108
 
103
109
  **Topics:** Mortality · Infant Mortality · Natality · Environment · Vaccine Safety · Infectious Disease
104
110
 
105
- ### `pulse info <ID>` — deep dive on a dataset
111
+ ### `pulse source wonder info <ID>` — deep dive on a dataset
106
112
 
107
113
  ```bash
108
- pulse info D176 # Provisional Mortality (2018–present)
109
- pulse info D66 # Natality / birth data
110
- pulse info D8 # VAERS vaccine adverse events
114
+ pulse source wonder info D176 # Provisional Mortality (2018–present)
115
+ pulse source wonder info D66 # Natality / birth data
116
+ pulse source wonder info D8 # VAERS vaccine adverse events
111
117
  ```
112
118
 
113
119
  Shows: subject description, available measures, key grouping dimensions, and all bundled example queries for that dataset.
@@ -122,134 +128,134 @@ pulse search "tick-borne disease cases" --queries # queries only
122
128
  pulse search "recent COVID deaths" --datasets # datasets only
123
129
  ```
124
130
 
125
- ### `pulse list-queries` — all bundled example queries
131
+ ### `pulse source wonder list-queries` — all bundled example queries
126
132
 
127
133
  ```bash
128
- pulse list-queries
129
- pulse list-queries --dataset D176 # filter by dataset
134
+ pulse source wonder list-queries
135
+ pulse source wonder list-queries --dataset D176 # filter by dataset
130
136
  ```
131
137
 
132
138
  23 working XML queries covering: drug/opioid/fentanyl deaths, maternal mortality, births, COVID deaths by race, suicide, tick-borne diseases, racial mortality gap, infant mortality, heart disease vs. cancer, and more.
133
139
 
134
- ### `pulse seer` — NCI SEER cancer statistics
140
+ ### `pulse source seer` — NCI SEER cancer statistics
135
141
 
136
142
  ```bash
137
- pulse seer sites --search breast # look up a cancer site code
138
- pulse seer mortality --site 55 --sex female -f csv
139
- pulse seer mortality --site 47 --compare-by race -f csv
140
- pulse seer incidence --site 55 --stage 104 -f csv
141
- pulse seer by-age --site 1 -f csv
142
- pulse seer compare-sites 55 47 66 -f csv # breast vs. lung vs. melanoma
143
+ pulse source seer sites --search breast # look up a cancer site code
144
+ pulse source seer mortality --site 55 --sex female -f csv
145
+ pulse source seer mortality --site 47 --compare-by race -f csv
146
+ pulse source seer incidence --site 55 --stage 104 -f csv
147
+ pulse source seer by-age --site 1 -f csv
148
+ pulse source seer compare-sites 55 47 66 -f csv # breast vs. lung vs. melanoma
143
149
  ```
144
150
 
145
151
  Cancer incidence and U.S. mortality rates/counts by site, sex, race, and age group, back to 1975 — calls the same unauthenticated JSON endpoints [SEER*Explorer](https://seer.cancer.gov/statistics-network/explorer/) itself uses. No API key needed.
146
152
 
147
- ### `pulse cdc-open` — CDC Open Data (data.cdc.gov)
153
+ ### `pulse source cdc-open` — CDC Open Data (data.cdc.gov)
148
154
 
149
155
  ```bash
150
- pulse cdc-open list # 60+ datasets: mortality, vaccination, wastewater, NNDSS, HAI, and more
151
- pulse cdc-open list --search wastewater
152
- pulse cdc-open query leading_death --where "year='2015'" -f csv
153
- pulse cdc-open query bi63-dtpu --where "state='California'" --limit 500 -f json
156
+ pulse source cdc-open list # 60+ datasets: mortality, vaccination, wastewater, NNDSS, HAI, and more
157
+ pulse source cdc-open list --search wastewater
158
+ pulse source cdc-open query leading_death --where "year='2015'" -f csv
159
+ pulse source cdc-open query bi63-dtpu --where "state='California'" --limit 500 -f json
154
160
  ```
155
161
 
156
162
  Raw [SODA](https://dev.socrata.com/) queries (`--where`, `--select`, `--group`, `--order`) against any of the registered Socrata datasets, by registry key or by Socrata ID directly. No API key needed (set `CDC_DATA_APP_TOKEN` for a higher rate limit).
157
163
 
158
- ### `pulse wisqars` — WISQARS injury & violence data
164
+ ### `pulse source wisqars` — WISQARS injury & violence data
159
165
 
160
166
  ```bash
161
- pulse wisqars list
162
- pulse wisqars mortality --intent Suicide --mechanism Firearm -f csv # 1999-2016
163
- pulse wisqars national --intent FA_Deaths --type year -f csv # 2019-present
164
- pulse wisqars state --intent Drug_OD --year 2023 -f table
165
- pulse wisqars county --state Texas --intent FA_Deaths --year 2023
166
- pulse wisqars tract --state Texas --intent All_Homicide --year 2022 # census-tract granularity
167
- pulse wisqars query t6u2-f84c --where "intent='Drug_OD' AND type='year'"
167
+ pulse source wisqars list
168
+ pulse source wisqars mortality --intent Suicide --mechanism Firearm -f csv # 1999-2016
169
+ pulse source wisqars national --intent FA_Deaths --type year -f csv # 2019-present
170
+ pulse source wisqars state --intent Drug_OD --year 2023 -f table
171
+ pulse source wisqars county --state Texas --intent FA_Deaths --year 2023
172
+ pulse source wisqars tract --state Texas --intent All_Homicide --year 2022 # census-tract granularity
173
+ pulse source wisqars query t6u2-f84c --where "intent='Drug_OD' AND type='year'"
168
174
  ```
169
175
 
170
176
  Fatal firearm/suicide/homicide/drug-overdose data from [WISQARS](https://wisqars.cdc.gov/) at national, state, county, and census-tract granularity, backed by data.cdc.gov Socrata datasets (same client as `cdc-open`). No API key needed.
171
177
 
172
- ### `pulse grasp` — ATSDR GRASP disease surveillance
178
+ ### `pulse source grasp` — ATSDR GRASP disease surveillance
173
179
 
174
180
  ```bash
175
- pulse grasp list
176
- pulse grasp hantavirus cases --outcome Dead -f table # pre-1993-present
177
- pulse grasp hantavirus by-year -f table
178
- pulse grasp hantavirus by-state -f table
179
- pulse grasp fluview ili-data --region nat --region ca --region tx --epiweeks 202001-202026
180
- pulse grasp fluview ili-by-region --epiweeks 201940-202020 -f table
181
- pulse grasp fluview clinical-data --region nat --epiweeks 202001-202026
182
- pulse grasp flusurv data --location CA --location OH --epiweeks 202001-202020 -f csv
183
- pulse grasp flusurv by-season --location CA -f table
184
- pulse grasp flusurv by-location --season 2019-20 -f table
181
+ pulse source grasp list
182
+ pulse source grasp hantavirus cases --outcome Dead -f table # pre-1993-present
183
+ pulse source grasp hantavirus by-year -f table
184
+ pulse source grasp hantavirus by-state -f table
185
+ pulse source grasp fluview ili-data --region nat --region ca --region tx --epiweeks 202001-202026
186
+ pulse source grasp fluview ili-by-region --epiweeks 201940-202020 -f table
187
+ pulse source grasp fluview clinical-data --region nat --epiweeks 202001-202026
188
+ pulse source grasp flusurv data --location CA --location OH --epiweeks 202001-202020 -f csv
189
+ pulse source grasp flusurv by-season --location CA -f table
190
+ pulse source grasp flusurv by-location --season 2019-20 -f table
185
191
  ```
186
192
 
187
193
  Hantavirus case data, FluView ILINet influenza-like-illness activity, WHO/NREVSS clinical lab flu positivity, and FluSurv-NET hospitalization rates — sourced from [gis.cdc.gov/grasp](https://gis.cdc.gov/grasp/) and the CMU Delphi Epidata API. No API key needed. Note: repeatable options like `--region`/`--location` take one value per flag (`--region nat --region ca`), unlike `health`'s argparse CLI which accepts space-separated lists after a single flag.
188
194
 
189
- ### `pulse nssp` — emergency department visit surveillance
195
+ ### `pulse source nssp` — emergency department visit surveillance
190
196
 
191
197
  ```bash
192
- pulse nssp query covid --geo-type state --geo-value ca -f csv
193
- pulse nssp query influenza --geo-type nation --geo-value us
194
- pulse nssp national --start 202401 -f csv # all 4 pathogens, national
195
- pulse nssp hhs rsv --region 4 -f table
198
+ pulse source nssp query covid --geo-type state --geo-value ca -f csv
199
+ pulse source nssp query influenza --geo-type nation --geo-value us
200
+ pulse source nssp national --start 202401 -f csv # all 4 pathogens, national
201
+ pulse source nssp hhs rsv --region 4 -f table
196
202
  ```
197
203
 
198
204
  Weekly % of ED visits attributed to COVID/flu/RSV from the [National Syndromic Surveillance Program](https://www.cdc.gov/nssp/), via the CMU Delphi Epidata API. Time values use epiweek format (`YYYYWW`, e.g. `202518` = week 18 of 2025). No API key needed.
199
205
 
200
- ### `pulse nis` — National Immunization Survey (vaccination coverage)
206
+ ### `pulse source nis` — National Immunization Survey (vaccination coverage)
201
207
 
202
208
  ```bash
203
- pulse nis list child # available years, 2011-2022
204
- pulse nis stream child 2022 --limit 10 -f json # raw respondent microdata
205
- pulse nis rates child 2022 -f table # state-level UTD rates
206
- pulse nis rates teen 2022 --vaccines P_UTDHPV13 -f csv
207
- pulse nis national child 2022 # national UTD summary
209
+ pulse source nis list child # available years, 2011-2022
210
+ pulse source nis stream child 2022 --limit 10 -f json # raw respondent microdata
211
+ pulse source nis rates child 2022 -f table # state-level UTD rates
212
+ pulse source nis rates teen 2022 --vaccines P_UTDHPV13 -f csv
213
+ pulse source nis national child 2022 # national UTD summary
208
214
  ```
209
215
 
210
216
  Childhood (19–35mo) and teen (13–17yr) vaccination coverage from CDC's annual random-digit-dial survey. Files are large fixed-width `.dat` files (50–200MB) streamed directly — nothing is written to disk. **Known issue:** CDC has restructured its NIS file hosting since this registry's URLs were last verified (some years now live under `www.cdc.gov/nis/media/files/...` or `ftp.cdc.gov/pub/Vaccines_NIS/` instead of the legacy `ftp.cdc.gov/.../nis/NISPUF{YY}-formats.sas` path baked into `nis_catalog.py`), so live `stream`/`rates`/`national` calls currently 404 for at least the 2015+ years — the same pre-existing gap affects `health`'s own `nis` module. The CLI plumbing and DAT-streaming parser are unit-tested and correct; only the hardcoded per-year URLs need refreshing against CDC's current hosting.
211
217
 
212
- ### `pulse run <query>` — execute a query
218
+ ### `pulse source wonder run <query>` — execute a query
213
219
 
214
220
  ```bash
215
221
  # Run a bundled query by filename (no path needed)
216
- pulse run drug-deaths-by-year-2018-2024-req.xml
222
+ pulse source wonder run drug-deaths-by-year-2018-2024-req.xml
217
223
 
218
224
  # Output formats
219
- pulse run opioid-overdose-deaths-2018-2024-req.xml -f csv
220
- pulse run mortality-by-year-cause-2021-2024-req.xml -f json
221
- pulse run births-by-year-2007-2024-req.xml -f table -o births.csv
225
+ pulse source wonder run opioid-overdose-deaths-2018-2024-req.xml -f csv
226
+ pulse source wonder run mortality-by-year-cause-2021-2024-req.xml -f json
227
+ pulse source wonder run births-by-year-2007-2024-req.xml -f table -o births.csv
222
228
 
223
229
  # Run your own query file
224
- pulse run /path/to/my-query.xml
230
+ pulse source wonder run /path/to/my-query.xml
225
231
  ```
226
232
 
227
233
  Hits the live CDC WONDER API. No login required; CDC requires a ~2-minute cooldown between queries.
228
234
 
229
- ### `pulse build "<description>"` — build a query with Claude
235
+ ### `pulse source wonder build "<description>"` — build a query with Claude
230
236
 
231
237
  ```bash
232
238
  # Requires ANTHROPIC_API_KEY
233
- pulse build "drug overdose deaths by state and year 2018-2023"
234
- pulse build "maternal mortality by race, 2018-2023" -o maternal-race.xml
235
- pulse build "birth rates by age of mother 2010 to 2024" --no-suggest
239
+ pulse source wonder build "drug overdose deaths by state and year 2018-2023"
240
+ pulse source wonder build "maternal mortality by race, 2018-2023" -o maternal-race.xml
241
+ pulse source wonder build "birth rates by age of mother 2010 to 2024" --no-suggest
236
242
  ```
237
243
 
238
244
  Suggests closest existing queries first, then calls Claude to build a new XML query. The LLM selects the right dataset and generates overrides merged onto a validated base template.
239
245
 
240
- ### `pulse query "<description>"` — build and run in one step
246
+ ### `pulse source wonder query "<description>"` — build and run in one step
241
247
 
242
248
  ```bash
243
- pulse query "fentanyl deaths by state 2020-2024" -f csv
244
- pulse query "infant mortality by race 2018-2023" --save-xml infant-race.xml
249
+ pulse source wonder query "fentanyl deaths by state 2020-2024" -f csv
250
+ pulse source wonder query "infant mortality by race 2018-2023" --save-xml infant-race.xml
245
251
  ```
246
252
 
247
- ### `pulse refine <file> "<feedback>"` — iterate on a query
253
+ ### `pulse source wonder refine <file> "<feedback>"` — iterate on a query
248
254
 
249
255
  ```bash
250
- pulse refine opioid-overdose-deaths-2018-2024-req.xml "break it down by state"
251
- pulse refine drug-deaths-by-year-2018-2024-req.xml "add sex breakdown" -o drug-sex.xml
252
- pulse refine drug-deaths-by-year-2018-2024-req.xml "show monthly not yearly" --run -f csv
256
+ pulse source wonder refine opioid-overdose-deaths-2018-2024-req.xml "break it down by state"
257
+ pulse source wonder refine drug-deaths-by-year-2018-2024-req.xml "add sex breakdown" -o drug-sex.xml
258
+ pulse source wonder refine drug-deaths-by-year-2018-2024-req.xml "show monthly not yearly" --run -f csv
253
259
  ```
254
260
 
255
261
  ## Testing
@@ -72,24 +72,30 @@ export LLM_HTTP_PROXY=socks5h://user:pass@host:port
72
72
 
73
73
  ## Commands
74
74
 
75
- ### `pulse datasets` — what's available
75
+ The CLI has five top-level commands: **`topics`** (browse by subject across all
76
+ sources), **`source`** (browse/query one source), **`search`** (free-text find),
77
+ plus **`doctor`** and **`generate`**. Every data source lives under `source`:
78
+ `pulse source` for an overview, `pulse source <name>` for its datasets, and
79
+ `pulse source <name> <verb> …` to query it (e.g. `pulse source seer mortality`).
80
+
81
+ ### `pulse source wonder datasets` — what's available
76
82
 
77
83
  ```bash
78
- pulse datasets # all datasets
79
- pulse datasets --topic Mortality # filter by topic
80
- pulse datasets --json # JSON output
84
+ pulse source wonder datasets # all datasets
85
+ pulse source wonder datasets --topic Mortality # filter by topic
86
+ pulse source wonder datasets --json # JSON output
81
87
  ```
82
88
 
83
89
  Shows all 26+ CDC WONDER datasets with: topic, year range, what the data covers, number of bundled example queries, and whether age-adjusted rates are available.
84
90
 
85
91
  **Topics:** Mortality · Infant Mortality · Natality · Environment · Vaccine Safety · Infectious Disease
86
92
 
87
- ### `pulse info <ID>` — deep dive on a dataset
93
+ ### `pulse source wonder info <ID>` — deep dive on a dataset
88
94
 
89
95
  ```bash
90
- pulse info D176 # Provisional Mortality (2018–present)
91
- pulse info D66 # Natality / birth data
92
- pulse info D8 # VAERS vaccine adverse events
96
+ pulse source wonder info D176 # Provisional Mortality (2018–present)
97
+ pulse source wonder info D66 # Natality / birth data
98
+ pulse source wonder info D8 # VAERS vaccine adverse events
93
99
  ```
94
100
 
95
101
  Shows: subject description, available measures, key grouping dimensions, and all bundled example queries for that dataset.
@@ -104,134 +110,134 @@ pulse search "tick-borne disease cases" --queries # queries only
104
110
  pulse search "recent COVID deaths" --datasets # datasets only
105
111
  ```
106
112
 
107
- ### `pulse list-queries` — all bundled example queries
113
+ ### `pulse source wonder list-queries` — all bundled example queries
108
114
 
109
115
  ```bash
110
- pulse list-queries
111
- pulse list-queries --dataset D176 # filter by dataset
116
+ pulse source wonder list-queries
117
+ pulse source wonder list-queries --dataset D176 # filter by dataset
112
118
  ```
113
119
 
114
120
  23 working XML queries covering: drug/opioid/fentanyl deaths, maternal mortality, births, COVID deaths by race, suicide, tick-borne diseases, racial mortality gap, infant mortality, heart disease vs. cancer, and more.
115
121
 
116
- ### `pulse seer` — NCI SEER cancer statistics
122
+ ### `pulse source seer` — NCI SEER cancer statistics
117
123
 
118
124
  ```bash
119
- pulse seer sites --search breast # look up a cancer site code
120
- pulse seer mortality --site 55 --sex female -f csv
121
- pulse seer mortality --site 47 --compare-by race -f csv
122
- pulse seer incidence --site 55 --stage 104 -f csv
123
- pulse seer by-age --site 1 -f csv
124
- pulse seer compare-sites 55 47 66 -f csv # breast vs. lung vs. melanoma
125
+ pulse source seer sites --search breast # look up a cancer site code
126
+ pulse source seer mortality --site 55 --sex female -f csv
127
+ pulse source seer mortality --site 47 --compare-by race -f csv
128
+ pulse source seer incidence --site 55 --stage 104 -f csv
129
+ pulse source seer by-age --site 1 -f csv
130
+ pulse source seer compare-sites 55 47 66 -f csv # breast vs. lung vs. melanoma
125
131
  ```
126
132
 
127
133
  Cancer incidence and U.S. mortality rates/counts by site, sex, race, and age group, back to 1975 — calls the same unauthenticated JSON endpoints [SEER*Explorer](https://seer.cancer.gov/statistics-network/explorer/) itself uses. No API key needed.
128
134
 
129
- ### `pulse cdc-open` — CDC Open Data (data.cdc.gov)
135
+ ### `pulse source cdc-open` — CDC Open Data (data.cdc.gov)
130
136
 
131
137
  ```bash
132
- pulse cdc-open list # 60+ datasets: mortality, vaccination, wastewater, NNDSS, HAI, and more
133
- pulse cdc-open list --search wastewater
134
- pulse cdc-open query leading_death --where "year='2015'" -f csv
135
- pulse cdc-open query bi63-dtpu --where "state='California'" --limit 500 -f json
138
+ pulse source cdc-open list # 60+ datasets: mortality, vaccination, wastewater, NNDSS, HAI, and more
139
+ pulse source cdc-open list --search wastewater
140
+ pulse source cdc-open query leading_death --where "year='2015'" -f csv
141
+ pulse source cdc-open query bi63-dtpu --where "state='California'" --limit 500 -f json
136
142
  ```
137
143
 
138
144
  Raw [SODA](https://dev.socrata.com/) queries (`--where`, `--select`, `--group`, `--order`) against any of the registered Socrata datasets, by registry key or by Socrata ID directly. No API key needed (set `CDC_DATA_APP_TOKEN` for a higher rate limit).
139
145
 
140
- ### `pulse wisqars` — WISQARS injury & violence data
146
+ ### `pulse source wisqars` — WISQARS injury & violence data
141
147
 
142
148
  ```bash
143
- pulse wisqars list
144
- pulse wisqars mortality --intent Suicide --mechanism Firearm -f csv # 1999-2016
145
- pulse wisqars national --intent FA_Deaths --type year -f csv # 2019-present
146
- pulse wisqars state --intent Drug_OD --year 2023 -f table
147
- pulse wisqars county --state Texas --intent FA_Deaths --year 2023
148
- pulse wisqars tract --state Texas --intent All_Homicide --year 2022 # census-tract granularity
149
- pulse wisqars query t6u2-f84c --where "intent='Drug_OD' AND type='year'"
149
+ pulse source wisqars list
150
+ pulse source wisqars mortality --intent Suicide --mechanism Firearm -f csv # 1999-2016
151
+ pulse source wisqars national --intent FA_Deaths --type year -f csv # 2019-present
152
+ pulse source wisqars state --intent Drug_OD --year 2023 -f table
153
+ pulse source wisqars county --state Texas --intent FA_Deaths --year 2023
154
+ pulse source wisqars tract --state Texas --intent All_Homicide --year 2022 # census-tract granularity
155
+ pulse source wisqars query t6u2-f84c --where "intent='Drug_OD' AND type='year'"
150
156
  ```
151
157
 
152
158
  Fatal firearm/suicide/homicide/drug-overdose data from [WISQARS](https://wisqars.cdc.gov/) at national, state, county, and census-tract granularity, backed by data.cdc.gov Socrata datasets (same client as `cdc-open`). No API key needed.
153
159
 
154
- ### `pulse grasp` — ATSDR GRASP disease surveillance
160
+ ### `pulse source grasp` — ATSDR GRASP disease surveillance
155
161
 
156
162
  ```bash
157
- pulse grasp list
158
- pulse grasp hantavirus cases --outcome Dead -f table # pre-1993-present
159
- pulse grasp hantavirus by-year -f table
160
- pulse grasp hantavirus by-state -f table
161
- pulse grasp fluview ili-data --region nat --region ca --region tx --epiweeks 202001-202026
162
- pulse grasp fluview ili-by-region --epiweeks 201940-202020 -f table
163
- pulse grasp fluview clinical-data --region nat --epiweeks 202001-202026
164
- pulse grasp flusurv data --location CA --location OH --epiweeks 202001-202020 -f csv
165
- pulse grasp flusurv by-season --location CA -f table
166
- pulse grasp flusurv by-location --season 2019-20 -f table
163
+ pulse source grasp list
164
+ pulse source grasp hantavirus cases --outcome Dead -f table # pre-1993-present
165
+ pulse source grasp hantavirus by-year -f table
166
+ pulse source grasp hantavirus by-state -f table
167
+ pulse source grasp fluview ili-data --region nat --region ca --region tx --epiweeks 202001-202026
168
+ pulse source grasp fluview ili-by-region --epiweeks 201940-202020 -f table
169
+ pulse source grasp fluview clinical-data --region nat --epiweeks 202001-202026
170
+ pulse source grasp flusurv data --location CA --location OH --epiweeks 202001-202020 -f csv
171
+ pulse source grasp flusurv by-season --location CA -f table
172
+ pulse source grasp flusurv by-location --season 2019-20 -f table
167
173
  ```
168
174
 
169
175
  Hantavirus case data, FluView ILINet influenza-like-illness activity, WHO/NREVSS clinical lab flu positivity, and FluSurv-NET hospitalization rates — sourced from [gis.cdc.gov/grasp](https://gis.cdc.gov/grasp/) and the CMU Delphi Epidata API. No API key needed. Note: repeatable options like `--region`/`--location` take one value per flag (`--region nat --region ca`), unlike `health`'s argparse CLI which accepts space-separated lists after a single flag.
170
176
 
171
- ### `pulse nssp` — emergency department visit surveillance
177
+ ### `pulse source nssp` — emergency department visit surveillance
172
178
 
173
179
  ```bash
174
- pulse nssp query covid --geo-type state --geo-value ca -f csv
175
- pulse nssp query influenza --geo-type nation --geo-value us
176
- pulse nssp national --start 202401 -f csv # all 4 pathogens, national
177
- pulse nssp hhs rsv --region 4 -f table
180
+ pulse source nssp query covid --geo-type state --geo-value ca -f csv
181
+ pulse source nssp query influenza --geo-type nation --geo-value us
182
+ pulse source nssp national --start 202401 -f csv # all 4 pathogens, national
183
+ pulse source nssp hhs rsv --region 4 -f table
178
184
  ```
179
185
 
180
186
  Weekly % of ED visits attributed to COVID/flu/RSV from the [National Syndromic Surveillance Program](https://www.cdc.gov/nssp/), via the CMU Delphi Epidata API. Time values use epiweek format (`YYYYWW`, e.g. `202518` = week 18 of 2025). No API key needed.
181
187
 
182
- ### `pulse nis` — National Immunization Survey (vaccination coverage)
188
+ ### `pulse source nis` — National Immunization Survey (vaccination coverage)
183
189
 
184
190
  ```bash
185
- pulse nis list child # available years, 2011-2022
186
- pulse nis stream child 2022 --limit 10 -f json # raw respondent microdata
187
- pulse nis rates child 2022 -f table # state-level UTD rates
188
- pulse nis rates teen 2022 --vaccines P_UTDHPV13 -f csv
189
- pulse nis national child 2022 # national UTD summary
191
+ pulse source nis list child # available years, 2011-2022
192
+ pulse source nis stream child 2022 --limit 10 -f json # raw respondent microdata
193
+ pulse source nis rates child 2022 -f table # state-level UTD rates
194
+ pulse source nis rates teen 2022 --vaccines P_UTDHPV13 -f csv
195
+ pulse source nis national child 2022 # national UTD summary
190
196
  ```
191
197
 
192
198
  Childhood (19–35mo) and teen (13–17yr) vaccination coverage from CDC's annual random-digit-dial survey. Files are large fixed-width `.dat` files (50–200MB) streamed directly — nothing is written to disk. **Known issue:** CDC has restructured its NIS file hosting since this registry's URLs were last verified (some years now live under `www.cdc.gov/nis/media/files/...` or `ftp.cdc.gov/pub/Vaccines_NIS/` instead of the legacy `ftp.cdc.gov/.../nis/NISPUF{YY}-formats.sas` path baked into `nis_catalog.py`), so live `stream`/`rates`/`national` calls currently 404 for at least the 2015+ years — the same pre-existing gap affects `health`'s own `nis` module. The CLI plumbing and DAT-streaming parser are unit-tested and correct; only the hardcoded per-year URLs need refreshing against CDC's current hosting.
193
199
 
194
- ### `pulse run <query>` — execute a query
200
+ ### `pulse source wonder run <query>` — execute a query
195
201
 
196
202
  ```bash
197
203
  # Run a bundled query by filename (no path needed)
198
- pulse run drug-deaths-by-year-2018-2024-req.xml
204
+ pulse source wonder run drug-deaths-by-year-2018-2024-req.xml
199
205
 
200
206
  # Output formats
201
- pulse run opioid-overdose-deaths-2018-2024-req.xml -f csv
202
- pulse run mortality-by-year-cause-2021-2024-req.xml -f json
203
- pulse run births-by-year-2007-2024-req.xml -f table -o births.csv
207
+ pulse source wonder run opioid-overdose-deaths-2018-2024-req.xml -f csv
208
+ pulse source wonder run mortality-by-year-cause-2021-2024-req.xml -f json
209
+ pulse source wonder run births-by-year-2007-2024-req.xml -f table -o births.csv
204
210
 
205
211
  # Run your own query file
206
- pulse run /path/to/my-query.xml
212
+ pulse source wonder run /path/to/my-query.xml
207
213
  ```
208
214
 
209
215
  Hits the live CDC WONDER API. No login required; CDC requires a ~2-minute cooldown between queries.
210
216
 
211
- ### `pulse build "<description>"` — build a query with Claude
217
+ ### `pulse source wonder build "<description>"` — build a query with Claude
212
218
 
213
219
  ```bash
214
220
  # Requires ANTHROPIC_API_KEY
215
- pulse build "drug overdose deaths by state and year 2018-2023"
216
- pulse build "maternal mortality by race, 2018-2023" -o maternal-race.xml
217
- pulse build "birth rates by age of mother 2010 to 2024" --no-suggest
221
+ pulse source wonder build "drug overdose deaths by state and year 2018-2023"
222
+ pulse source wonder build "maternal mortality by race, 2018-2023" -o maternal-race.xml
223
+ pulse source wonder build "birth rates by age of mother 2010 to 2024" --no-suggest
218
224
  ```
219
225
 
220
226
  Suggests closest existing queries first, then calls Claude to build a new XML query. The LLM selects the right dataset and generates overrides merged onto a validated base template.
221
227
 
222
- ### `pulse query "<description>"` — build and run in one step
228
+ ### `pulse source wonder query "<description>"` — build and run in one step
223
229
 
224
230
  ```bash
225
- pulse query "fentanyl deaths by state 2020-2024" -f csv
226
- pulse query "infant mortality by race 2018-2023" --save-xml infant-race.xml
231
+ pulse source wonder query "fentanyl deaths by state 2020-2024" -f csv
232
+ pulse source wonder query "infant mortality by race 2018-2023" --save-xml infant-race.xml
227
233
  ```
228
234
 
229
- ### `pulse refine <file> "<feedback>"` — iterate on a query
235
+ ### `pulse source wonder refine <file> "<feedback>"` — iterate on a query
230
236
 
231
237
  ```bash
232
- pulse refine opioid-overdose-deaths-2018-2024-req.xml "break it down by state"
233
- pulse refine drug-deaths-by-year-2018-2024-req.xml "add sex breakdown" -o drug-sex.xml
234
- pulse refine drug-deaths-by-year-2018-2024-req.xml "show monthly not yearly" --run -f csv
238
+ pulse source wonder refine opioid-overdose-deaths-2018-2024-req.xml "break it down by state"
239
+ pulse source wonder refine drug-deaths-by-year-2018-2024-req.xml "add sex breakdown" -o drug-sex.xml
240
+ pulse source wonder refine drug-deaths-by-year-2018-2024-req.xml "show monthly not yearly" --run -f csv
235
241
  ```
236
242
 
237
243
  ## Testing
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "pulse-code"
7
- version = "1.0.2"
7
+ version = "1.1.0"
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"
@@ -3,7 +3,7 @@ snapshot at data/cdc_open_catalog.json.
3
3
 
4
4
  Each entry describes a Socrata dataset: its ID, human-readable name,
5
5
  description, date coverage, and key queryable columns. This is a reference
6
- catalog for discovery (`pulse cdc-open list`) — actual queries go straight to
6
+ catalog for discovery (`pulse source cdc-open list`) — actual queries go straight to
7
7
  the live API via SodaClient, so the data itself is never stale even if a
8
8
  dataset's metadata here drifts.
9
9
  """