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.
Files changed (135) hide show
  1. pulse_code-1.1.2/PKG-INFO +200 -0
  2. pulse_code-1.1.2/README.md +182 -0
  3. {pulse_code-1.1.0 → pulse_code-1.1.2}/pyproject.toml +8 -8
  4. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/cli.py +180 -1
  5. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/data/cdc_open_catalog.json +51 -0
  6. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/data/queries_index.json +210 -3
  7. pulse_code-1.1.2/src/pulse/dqs_catalog.py +116 -0
  8. pulse_code-1.1.2/src/pulse/dqs_sdk.py +102 -0
  9. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/grasp_catalog.py +2 -2
  10. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/grasp_client.py +1 -1
  11. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/grasp_sdk.py +1 -1
  12. pulse_code-1.1.2/src/pulse/queries/aids-cases-by-age-1981-1999-req.xml +178 -0
  13. pulse_code-1.1.2/src/pulse/queries/aids-cases-by-location-1981-1999-req.xml +178 -0
  14. pulse_code-1.1.2/src/pulse/queries/aids-cases-by-race-1981-1999-req.xml +178 -0
  15. pulse_code-1.1.2/src/pulse/queries/aids-cases-by-sex-1981-1999-req.xml +178 -0
  16. pulse_code-1.1.2/src/pulse/queries/births-by-age-of-mother-2007-2024-req.xml +334 -0
  17. pulse_code-1.1.2/src/pulse/queries/births-by-race-2007-2024-req.xml +334 -0
  18. pulse_code-1.1.2/src/pulse/queries/cancer-incidence-by-state-1999-2022-req.xml +174 -0
  19. pulse_code-1.1.2/src/pulse/queries/cancer-mortality-by-state-2018-2023-req.xml +166 -0
  20. pulse_code-1.1.2/src/pulse/queries/covid-deaths-by-age-2020-2023-req.xml +533 -0
  21. pulse_code-1.1.2/src/pulse/queries/covid-deaths-by-age-sex-2020-2023-req.xml +533 -0
  22. pulse_code-1.1.2/src/pulse/queries/covid-deaths-by-sex-2020-2023-req.xml +533 -0
  23. pulse_code-1.1.2/src/pulse/queries/deaths-by-place-of-death-2018-2024-req.xml +538 -0
  24. pulse_code-1.1.2/src/pulse/queries/fetal-deaths-by-age-of-mother-2005-2024-req.xml +322 -0
  25. pulse_code-1.1.2/src/pulse/queries/fetal-deaths-by-race-2005-2024-req.xml +322 -0
  26. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/heat-wave-days-by-county-req.xml +1 -1
  27. pulse_code-1.1.2/src/pulse/queries/maternal-mortality-by-race-2018-2024-req.xml +413 -0
  28. pulse_code-1.1.2/src/pulse/queries/opioid-deaths-by-age-2018-2024-req.xml +544 -0
  29. pulse_code-1.1.2/src/pulse/queries/opioid-deaths-by-sex-2018-2024-req.xml +544 -0
  30. pulse_code-1.1.2/src/pulse/queries/pm25-by-state-2003-2011-req.xml +194 -0
  31. pulse_code-1.1.2/src/pulse/queries/std-cases-by-state-1984-2014-req.xml +178 -0
  32. pulse_code-1.1.2/src/pulse/queries/tick-borne-diseases-by-age-2016-2023-req.xml +125 -0
  33. pulse_code-1.1.2/src/pulse/queries/tick-borne-diseases-by-race-2016-2023-req.xml +125 -0
  34. pulse_code-1.1.2/src/pulse/queries/tick-borne-diseases-by-sex-2016-2023-req.xml +125 -0
  35. pulse_code-1.1.2/src/pulse/queries/tick-borne-diseases-by-state-2016-2023-req.xml +125 -0
  36. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/sources_registry.py +16 -0
  37. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/topics_registry.py +94 -0
  38. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/wonder_client.py +1 -1
  39. pulse_code-1.1.2/src/pulse_code.egg-info/PKG-INFO +200 -0
  40. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse_code.egg-info/SOURCES.txt +25 -0
  41. pulse_code-1.1.2/src/pulse_code.egg-info/requires.txt +8 -0
  42. pulse_code-1.1.0/PKG-INFO +0 -355
  43. pulse_code-1.1.0/README.md +0 -337
  44. pulse_code-1.1.0/src/pulse_code.egg-info/PKG-INFO +0 -355
  45. pulse_code-1.1.0/src/pulse_code.egg-info/requires.txt +0 -8
  46. {pulse_code-1.1.0 → pulse_code-1.1.2}/LICENSE +0 -0
  47. {pulse_code-1.1.0 → pulse_code-1.1.2}/setup.cfg +0 -0
  48. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/__init__.py +0 -0
  49. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/__main__.py +0 -0
  50. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/catalog.py +0 -0
  51. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/cdc_open_catalog.py +0 -0
  52. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/data/catalog.json +0 -0
  53. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/data/seer_var_formats.json +0 -0
  54. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/data/variable_labels.json +0 -0
  55. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/llm_builder.py +0 -0
  56. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/matcher.py +0 -0
  57. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/nis_catalog.py +0 -0
  58. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/nis_parser.py +0 -0
  59. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/nis_sdk.py +0 -0
  60. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/nssp_client.py +0 -0
  61. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/nssp_sdk.py +0 -0
  62. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/aids-cases-by-year-1981-1999-req.xml +0 -0
  63. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/births-by-year-1995-2002-req.xml +0 -0
  64. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/births-by-year-2003-2006-req.xml +0 -0
  65. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/births-by-year-2007-2024-req.xml +0 -0
  66. {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
  67. {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
  68. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/covid-deaths-by-race-2020-2023-req.xml +0 -0
  69. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/drug-deaths-by-month-1999-2020-req.xml +0 -0
  70. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/drug-deaths-by-month-2018-2024-req.xml +0 -0
  71. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/drug-deaths-by-year-1999-2020-req.xml +0 -0
  72. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/drug-deaths-by-year-2018-2024-req.xml +0 -0
  73. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/fentanyl-deaths-by-month-1999-2020-req.xml +0 -0
  74. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/fentanyl-deaths-by-month-2018-2024-req.xml +0 -0
  75. {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
  76. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/fetal-deaths-by-year-2005-2024-req.xml +0 -0
  77. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/heart-vs-cancer-by-sex-2018-2023-req.xml +0 -0
  78. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/infant-mortality-2018-2023-req.xml +0 -0
  79. {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
  80. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/maternal-mortality-by-year-1999-2020-req.xml +0 -0
  81. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/maternal-mortality-by-year-2018-2024-req.xml +0 -0
  82. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/mortality-by-race-sex-2018-2023-req.xml +0 -0
  83. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/mortality-by-year-cause-1979-1998-req.xml +0 -0
  84. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/mortality-by-year-cause-1999-2020-req.xml +0 -0
  85. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/mortality-by-year-cause-2021-2024-req.xml +0 -0
  86. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/opioid-overdose-deaths-2018-2024-req.xml +0 -0
  87. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/pm25-by-year-2003-2011-req.xml +0 -0
  88. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/provisional-births-by-month-2023-req.xml +0 -0
  89. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/racial-mortality-gap-2018-2023-req.xml +0 -0
  90. {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
  91. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/suicide-by-sex-1999-2020-req.xml +0 -0
  92. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/suicide-by-sex-2021-2024-req.xml +0 -0
  93. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/tb-cases-by-year-1993-2023-req.xml +0 -0
  94. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/tick-borne-diseases-by-year-2016-2023-req.xml +0 -0
  95. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/underlying-cause-mortality-by-year-1999-2020-req.xml +0 -0
  96. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/queries/unintentional-injuries-by-age-2018-2023-req.xml +0 -0
  97. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/seer_catalog.py +0 -0
  98. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/seer_client.py +0 -0
  99. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/seer_sdk.py +0 -0
  100. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/soda_client.py +0 -0
  101. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D10-base.xml +0 -0
  102. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D104-base.xml +0 -0
  103. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D117-base.xml +0 -0
  104. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D128-base.xml +0 -0
  105. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D140-base.xml +0 -0
  106. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D141-base.xml +0 -0
  107. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D149-base.xml +0 -0
  108. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D157-base.xml +0 -0
  109. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D158-base.xml +0 -0
  110. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D159-base.xml +0 -0
  111. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D16-base.xml +0 -0
  112. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D176-base.xml +0 -0
  113. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D178-base.xml +0 -0
  114. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D18-base.xml +0 -0
  115. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D192-base.xml +0 -0
  116. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D204-base.xml +0 -0
  117. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D23-base.xml +0 -0
  118. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D27-base.xml +0 -0
  119. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D31-base.xml +0 -0
  120. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D60-base.xml +0 -0
  121. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D61-base.xml +0 -0
  122. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D66-base.xml +0 -0
  123. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D69-base.xml +0 -0
  124. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D73-base.xml +0 -0
  125. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D74-base.xml +0 -0
  126. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D76-base.xml +0 -0
  127. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D77-base.xml +0 -0
  128. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D8-base.xml +0 -0
  129. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D80-base.xml +0 -0
  130. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/templates/D81-base.xml +0 -0
  131. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/wisqars_catalog.py +0 -0
  132. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse/wisqars_sdk.py +0 -0
  133. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse_code.egg-info/dependency_links.txt +0 -0
  134. {pulse_code-1.1.0 → pulse_code-1.1.2}/src/pulse_code.egg-info/entry_points.txt +0 -0
  135. {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
+ [![PyPI](https://img.shields.io/pypi/v/pulse-code?style=for-the-badge)](https://pypi.org/project/pulse-code/)
22
+ [![Python versions](https://img.shields.io/badge/python-3.11%2B-blue?style=for-the-badge)](https://pypi.org/project/pulse-code/)
23
+ [![Publish](https://img.shields.io/github/actions/workflow/status/fartbagxp/pulse-code/publish.yml?style=for-the-badge&label=publish)](https://github.com/fartbagxp/pulse-code/actions/workflows/publish.yml)
24
+ [![Pages](https://img.shields.io/github/actions/workflow/status/fartbagxp/pulse-code/pages.yml?style=for-the-badge&label=pages)](https://fartbagxp.github.io/pulse-code/)
25
+ [![License](https://img.shields.io/badge/license-CC0--1.0-blue?style=for-the-badge)](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
+ ![pulse-code demo](docs/demo/pulse-demo.gif)
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
+ [![PyPI](https://img.shields.io/pypi/v/pulse-code?style=for-the-badge)](https://pypi.org/project/pulse-code/)
4
+ [![Python versions](https://img.shields.io/badge/python-3.11%2B-blue?style=for-the-badge)](https://pypi.org/project/pulse-code/)
5
+ [![Publish](https://img.shields.io/github/actions/workflow/status/fartbagxp/pulse-code/publish.yml?style=for-the-badge&label=publish)](https://github.com/fartbagxp/pulse-code/actions/workflows/publish.yml)
6
+ [![Pages](https://img.shields.io/github/actions/workflow/status/fartbagxp/pulse-code/pages.yml?style=for-the-badge&label=pages)](https://fartbagxp.github.io/pulse-code/)
7
+ [![License](https://img.shields.io/badge/license-CC0--1.0-blue?style=for-the-badge)](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
+ ![pulse-code demo](docs/demo/pulse-demo.gif)
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==82.0.1"]
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.0"
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.14"
11
+ requires-python = ">=3.11"
12
12
  dependencies = [
13
- "anthropic==0.120.2",
14
- "openai==2.50.0",
13
+ "anthropic==1.1.0",
14
+ "openai==3.5.0",
15
15
  "pydantic==2.13.4",
16
- "python-dotenv==1.2.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.0",
20
+ "typer==0.27.1",
21
21
  ]
22
22
 
23
23
  [dependency-groups]
24
24
  dev = [
25
- "pre-commit==4.6.1",
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
- ("GRASP", "https://gis.cdc.gov/grasp/HantavirusCaseViewAPI/GetData_JSON?appVersion=Public"),
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")]