epidatpy 0.5.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.
- epidatpy-0.5.0/LICENSE +21 -0
- epidatpy-0.5.0/MANIFEST.in +10 -0
- epidatpy-0.5.0/PKG-INFO +184 -0
- epidatpy-0.5.0/README.md +126 -0
- epidatpy-0.5.0/docs/conf.py +93 -0
- epidatpy-0.5.0/docs/epidatpy.rst +22 -0
- epidatpy-0.5.0/docs/index.rst +59 -0
- epidatpy-0.5.0/epidatpy/__init__.py +17 -0
- epidatpy-0.5.0/epidatpy/_auth.py +15 -0
- epidatpy-0.5.0/epidatpy/_call.py +380 -0
- epidatpy-0.5.0/epidatpy/_constants.py +7 -0
- epidatpy-0.5.0/epidatpy/_covidcast.py +397 -0
- epidatpy-0.5.0/epidatpy/_endpoints.py +1731 -0
- epidatpy-0.5.0/epidatpy/_model.py +189 -0
- epidatpy-0.5.0/epidatpy/_parse.py +133 -0
- epidatpy-0.5.0/epidatpy/request.py +54 -0
- epidatpy-0.5.0/epidatpy.egg-info/PKG-INFO +184 -0
- epidatpy-0.5.0/epidatpy.egg-info/SOURCES.txt +28 -0
- epidatpy-0.5.0/epidatpy.egg-info/dependency_links.txt +1 -0
- epidatpy-0.5.0/epidatpy.egg-info/requires.txt +18 -0
- epidatpy-0.5.0/epidatpy.egg-info/top_level.txt +1 -0
- epidatpy-0.5.0/pyproject.toml +82 -0
- epidatpy-0.5.0/setup.cfg +4 -0
- epidatpy-0.5.0/tests/__init__.py +0 -0
- epidatpy-0.5.0/tests/test_auth.py +12 -0
- epidatpy-0.5.0/tests/test_cast_endpoints.py +103 -0
- epidatpy-0.5.0/tests/test_constants.py +5 -0
- epidatpy-0.5.0/tests/test_epidata_calls.py +424 -0
- epidatpy-0.5.0/tests/test_model.py +32 -0
- epidatpy-0.5.0/tests/test_parse.py +43 -0
epidatpy-0.5.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
The MIT License (MIT)
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2018 The Delphi Group at Carnegie Mellon University
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
epidatpy-0.5.0/PKG-INFO
ADDED
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: epidatpy
|
|
3
|
+
Version: 0.5.0
|
|
4
|
+
Summary: A programmatic interface to Delphi's Epidata API.
|
|
5
|
+
Author: Delphi Research Group
|
|
6
|
+
Maintainer-email: Dmitry Shemetov <dshemeto@andrew.cmu.edu>
|
|
7
|
+
License: The MIT License (MIT)
|
|
8
|
+
|
|
9
|
+
Copyright (c) 2018 The Delphi Group at Carnegie Mellon University
|
|
10
|
+
|
|
11
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
12
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
13
|
+
in the Software without restriction, including without limitation the rights
|
|
14
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
15
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
16
|
+
furnished to do so, subject to the following conditions:
|
|
17
|
+
|
|
18
|
+
The above copyright notice and this permission notice shall be included in all
|
|
19
|
+
copies or substantial portions of the Software.
|
|
20
|
+
|
|
21
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
22
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
23
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
24
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
25
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
26
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
27
|
+
SOFTWARE.
|
|
28
|
+
|
|
29
|
+
Project-URL: homepage, https://github.com/cmu-delphi/epidatpy
|
|
30
|
+
Project-URL: repository, https://github.com/cmu-delphi/epidatpy
|
|
31
|
+
Classifier: Programming Language :: Python :: 3
|
|
32
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
33
|
+
Classifier: Operating System :: OS Independent
|
|
34
|
+
Classifier: Intended Audience :: Science/Research
|
|
35
|
+
Classifier: Natural Language :: English
|
|
36
|
+
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
|
|
37
|
+
Requires-Python: >=3.9
|
|
38
|
+
Description-Content-Type: text/markdown
|
|
39
|
+
License-File: LICENSE
|
|
40
|
+
Requires-Dist: appdirs>=1.4.4
|
|
41
|
+
Requires-Dist: diskcache>=5.6.3
|
|
42
|
+
Requires-Dist: epiweeks>=2.1
|
|
43
|
+
Requires-Dist: pandas>=2
|
|
44
|
+
Requires-Dist: requests>=2.25
|
|
45
|
+
Requires-Dist: tenacity>=9.0.0
|
|
46
|
+
Provides-Extra: dev
|
|
47
|
+
Requires-Dist: ipykernel; extra == "dev"
|
|
48
|
+
Requires-Dist: matplotlib; extra == "dev"
|
|
49
|
+
Requires-Dist: mypy; extra == "dev"
|
|
50
|
+
Requires-Dist: myst-nb; extra == "dev"
|
|
51
|
+
Requires-Dist: pytest; extra == "dev"
|
|
52
|
+
Requires-Dist: ruff; extra == "dev"
|
|
53
|
+
Requires-Dist: sphinx_rtd_theme; extra == "dev"
|
|
54
|
+
Requires-Dist: sphinx-autodoc-typehints; extra == "dev"
|
|
55
|
+
Requires-Dist: sphinx; extra == "dev"
|
|
56
|
+
Requires-Dist: types-requests; extra == "dev"
|
|
57
|
+
Dynamic: license-file
|
|
58
|
+
|
|
59
|
+
# `epidatpy`
|
|
60
|
+
|
|
61
|
+
[![License: MIT][mit-image]][mit-url] [![Github Actions][github-actions-image]][github-actions-url] [![PyPi][pypi-image]][pypi-url] [![Read the Docs][docs-image]][docs-url]
|
|
62
|
+
|
|
63
|
+
The Python client for the [Delphi Epidata API](https://cmu-delphi.github.io/delphi-epidata/).
|
|
64
|
+
|
|
65
|
+
## Install
|
|
66
|
+
|
|
67
|
+
Install with the following commands:
|
|
68
|
+
|
|
69
|
+
```sh
|
|
70
|
+
# Latest dev version
|
|
71
|
+
pip install "git+https://github.com/cmu-delphi/epidatpy.git#egg=epidatpy"
|
|
72
|
+
|
|
73
|
+
# PyPI version (not yet available)
|
|
74
|
+
pip install epidatpy
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
## Usage
|
|
78
|
+
|
|
79
|
+
```py
|
|
80
|
+
from epidatpy import CovidcastEpidata, EpiDataContext, EpiRange
|
|
81
|
+
|
|
82
|
+
# All calls using the `epidata` object will now be cached for 7 days
|
|
83
|
+
epidata = EpiDataContext(use_cache=True, cache_max_age_days=7)
|
|
84
|
+
|
|
85
|
+
# Obtain a DataFrame of the most up-to-date version of the smoothed covid-like illness (CLI)
|
|
86
|
+
# signal from the COVID-19 Trends and Impact survey for the US
|
|
87
|
+
epidata.pub_covidcast(
|
|
88
|
+
data_source="jhu-csse",
|
|
89
|
+
signals="confirmed_cumulative_num",
|
|
90
|
+
geo_type="nation",
|
|
91
|
+
time_type="day",
|
|
92
|
+
geo_values="us",
|
|
93
|
+
time_values=EpiRange(20210405, 20210410),
|
|
94
|
+
).df()
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
### CAST API (snapshot / archive)
|
|
98
|
+
|
|
99
|
+
The CAST API exposes versioned signals (NSSP, pophive, NWSS, ...). Use
|
|
100
|
+
`epidata_snapshot` for a single as-of view, `epidata_archive` for the full
|
|
101
|
+
report-time history, or `epidata` to dispatch between them.
|
|
102
|
+
|
|
103
|
+
```py
|
|
104
|
+
from epidatpy import EpiDataContext, EpiRange
|
|
105
|
+
|
|
106
|
+
epidata = EpiDataContext()
|
|
107
|
+
|
|
108
|
+
# Source-level metadata (signals, geo_types, available date ranges).
|
|
109
|
+
epidata.epidata_meta(source="nssp")
|
|
110
|
+
|
|
111
|
+
# Latest snapshot of a signal (omit `snapshot_date` to fetch the newest version).
|
|
112
|
+
epidata.epidata_snapshot(
|
|
113
|
+
source="nssp",
|
|
114
|
+
signals="pct_ed_visits_influenza",
|
|
115
|
+
geo_type="state",
|
|
116
|
+
geo_values="ca,ny",
|
|
117
|
+
reference_time=EpiRange("2025-01-01", "2025-06-01"),
|
|
118
|
+
).df()
|
|
119
|
+
|
|
120
|
+
# Full report-time history, filtered to report_times on or before 2025-10-16.
|
|
121
|
+
epidata.epidata_archive(
|
|
122
|
+
source="nssp",
|
|
123
|
+
signals="pct_ed_visits_influenza",
|
|
124
|
+
geo_type="state",
|
|
125
|
+
report_time="<2025-10-16",
|
|
126
|
+
).df()
|
|
127
|
+
|
|
128
|
+
# Router: pass `report_time` (or `snapshot_date="*"`) for archive, `snapshot_date` for snapshot.
|
|
129
|
+
epidata.epidata(
|
|
130
|
+
source="nssp",
|
|
131
|
+
signals="pct_ed_visits_influenza",
|
|
132
|
+
geo_type="state",
|
|
133
|
+
report_time=EpiRange("2025-01-01", "2025-10-16"),
|
|
134
|
+
).df()
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
`geo_values`, `reference_time`, and an `EpiRange` `report_time` lower
|
|
138
|
+
bound are filtered locally after the request.
|
|
139
|
+
|
|
140
|
+
## Development
|
|
141
|
+
|
|
142
|
+
The following commands are available for developers:
|
|
143
|
+
|
|
144
|
+
```sh
|
|
145
|
+
make install # setup venv, install dependencies and local package
|
|
146
|
+
make test # run unit tests
|
|
147
|
+
make format # format code
|
|
148
|
+
make lint # check linting
|
|
149
|
+
make doc # build docs
|
|
150
|
+
make doc-preview # preview docs in browser
|
|
151
|
+
make release # build distribution packages
|
|
152
|
+
make upload # upload the current version to pypi
|
|
153
|
+
make clean # clean build and docs artifacts
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
### Release Process
|
|
157
|
+
|
|
158
|
+
`dev` is the only long-lived branch; each release line lives on a `rel-X.Y` branch.
|
|
159
|
+
Everything is driven by the [create_release](https://github.com/cmu-delphi/epidatpy/actions/workflows/create_release.yml)
|
|
160
|
+
workflow, run with a `bump` of `major`, `minor`, or `patch`:
|
|
161
|
+
|
|
162
|
+
- **`major` / `minor`:** bumps the version on `dev`, cuts a new `rel-X.Y` branch at
|
|
163
|
+
that commit, and tags `vX.Y.0`.
|
|
164
|
+
- **`patch` (hotfix):** bumps the patch version on an existing `rel-X.Y` branch and
|
|
165
|
+
tags `vX.Y.Z`. Land the fix on that branch first (commit directly or cherry-pick
|
|
166
|
+
from `dev`); set `release_branch` to pick the branch (defaults to the line
|
|
167
|
+
matching `dev`'s version).
|
|
168
|
+
|
|
169
|
+
Either way the workflow creates a [GitHub release](https://github.com/cmu-delphi/epidatpy/releases)
|
|
170
|
+
with auto-generated notes. Pushing the `vX.Y.Z` tag then triggers `pypi_publish`
|
|
171
|
+
(build + upload to [PyPI](https://pypi.python.org/pypi/epidatpy/)) and `documentation`
|
|
172
|
+
(docs rebuild). Because publishing is a separate workflow keyed off the tag rather
|
|
173
|
+
than a step inside `create_release`, a failed PyPI upload can be re-run against the
|
|
174
|
+
existing tag via the `pypi_publish` workflow's `Run workflow` button — without redoing
|
|
175
|
+
the release cut.
|
|
176
|
+
|
|
177
|
+
[mit-image]: https://img.shields.io/badge/License-MIT-yellow.svg
|
|
178
|
+
[mit-url]: https://opensource.org/licenses/MIT
|
|
179
|
+
[github-actions-image]: https://github.com/cmu-delphi/epidatpy/workflows/ci/badge.svg
|
|
180
|
+
[github-actions-url]: https://github.com/cmu-delphi/epidatpy/actions
|
|
181
|
+
[pypi-image]: https://img.shields.io/pypi/v/epidatpy
|
|
182
|
+
[pypi-url]: https://pypi.python.org/pypi/epidatpy/
|
|
183
|
+
[docs-image]: https://readthedocs.org/projects/epidatpy/badge/?version=latest
|
|
184
|
+
[docs-url]: https://epidatpy.readthedocs.io/en/latest/?badge=latest
|
epidatpy-0.5.0/README.md
ADDED
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
# `epidatpy`
|
|
2
|
+
|
|
3
|
+
[![License: MIT][mit-image]][mit-url] [![Github Actions][github-actions-image]][github-actions-url] [![PyPi][pypi-image]][pypi-url] [![Read the Docs][docs-image]][docs-url]
|
|
4
|
+
|
|
5
|
+
The Python client for the [Delphi Epidata API](https://cmu-delphi.github.io/delphi-epidata/).
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
Install with the following commands:
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
# Latest dev version
|
|
13
|
+
pip install "git+https://github.com/cmu-delphi/epidatpy.git#egg=epidatpy"
|
|
14
|
+
|
|
15
|
+
# PyPI version (not yet available)
|
|
16
|
+
pip install epidatpy
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Usage
|
|
20
|
+
|
|
21
|
+
```py
|
|
22
|
+
from epidatpy import CovidcastEpidata, EpiDataContext, EpiRange
|
|
23
|
+
|
|
24
|
+
# All calls using the `epidata` object will now be cached for 7 days
|
|
25
|
+
epidata = EpiDataContext(use_cache=True, cache_max_age_days=7)
|
|
26
|
+
|
|
27
|
+
# Obtain a DataFrame of the most up-to-date version of the smoothed covid-like illness (CLI)
|
|
28
|
+
# signal from the COVID-19 Trends and Impact survey for the US
|
|
29
|
+
epidata.pub_covidcast(
|
|
30
|
+
data_source="jhu-csse",
|
|
31
|
+
signals="confirmed_cumulative_num",
|
|
32
|
+
geo_type="nation",
|
|
33
|
+
time_type="day",
|
|
34
|
+
geo_values="us",
|
|
35
|
+
time_values=EpiRange(20210405, 20210410),
|
|
36
|
+
).df()
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
### CAST API (snapshot / archive)
|
|
40
|
+
|
|
41
|
+
The CAST API exposes versioned signals (NSSP, pophive, NWSS, ...). Use
|
|
42
|
+
`epidata_snapshot` for a single as-of view, `epidata_archive` for the full
|
|
43
|
+
report-time history, or `epidata` to dispatch between them.
|
|
44
|
+
|
|
45
|
+
```py
|
|
46
|
+
from epidatpy import EpiDataContext, EpiRange
|
|
47
|
+
|
|
48
|
+
epidata = EpiDataContext()
|
|
49
|
+
|
|
50
|
+
# Source-level metadata (signals, geo_types, available date ranges).
|
|
51
|
+
epidata.epidata_meta(source="nssp")
|
|
52
|
+
|
|
53
|
+
# Latest snapshot of a signal (omit `snapshot_date` to fetch the newest version).
|
|
54
|
+
epidata.epidata_snapshot(
|
|
55
|
+
source="nssp",
|
|
56
|
+
signals="pct_ed_visits_influenza",
|
|
57
|
+
geo_type="state",
|
|
58
|
+
geo_values="ca,ny",
|
|
59
|
+
reference_time=EpiRange("2025-01-01", "2025-06-01"),
|
|
60
|
+
).df()
|
|
61
|
+
|
|
62
|
+
# Full report-time history, filtered to report_times on or before 2025-10-16.
|
|
63
|
+
epidata.epidata_archive(
|
|
64
|
+
source="nssp",
|
|
65
|
+
signals="pct_ed_visits_influenza",
|
|
66
|
+
geo_type="state",
|
|
67
|
+
report_time="<2025-10-16",
|
|
68
|
+
).df()
|
|
69
|
+
|
|
70
|
+
# Router: pass `report_time` (or `snapshot_date="*"`) for archive, `snapshot_date` for snapshot.
|
|
71
|
+
epidata.epidata(
|
|
72
|
+
source="nssp",
|
|
73
|
+
signals="pct_ed_visits_influenza",
|
|
74
|
+
geo_type="state",
|
|
75
|
+
report_time=EpiRange("2025-01-01", "2025-10-16"),
|
|
76
|
+
).df()
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
`geo_values`, `reference_time`, and an `EpiRange` `report_time` lower
|
|
80
|
+
bound are filtered locally after the request.
|
|
81
|
+
|
|
82
|
+
## Development
|
|
83
|
+
|
|
84
|
+
The following commands are available for developers:
|
|
85
|
+
|
|
86
|
+
```sh
|
|
87
|
+
make install # setup venv, install dependencies and local package
|
|
88
|
+
make test # run unit tests
|
|
89
|
+
make format # format code
|
|
90
|
+
make lint # check linting
|
|
91
|
+
make doc # build docs
|
|
92
|
+
make doc-preview # preview docs in browser
|
|
93
|
+
make release # build distribution packages
|
|
94
|
+
make upload # upload the current version to pypi
|
|
95
|
+
make clean # clean build and docs artifacts
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### Release Process
|
|
99
|
+
|
|
100
|
+
`dev` is the only long-lived branch; each release line lives on a `rel-X.Y` branch.
|
|
101
|
+
Everything is driven by the [create_release](https://github.com/cmu-delphi/epidatpy/actions/workflows/create_release.yml)
|
|
102
|
+
workflow, run with a `bump` of `major`, `minor`, or `patch`:
|
|
103
|
+
|
|
104
|
+
- **`major` / `minor`:** bumps the version on `dev`, cuts a new `rel-X.Y` branch at
|
|
105
|
+
that commit, and tags `vX.Y.0`.
|
|
106
|
+
- **`patch` (hotfix):** bumps the patch version on an existing `rel-X.Y` branch and
|
|
107
|
+
tags `vX.Y.Z`. Land the fix on that branch first (commit directly or cherry-pick
|
|
108
|
+
from `dev`); set `release_branch` to pick the branch (defaults to the line
|
|
109
|
+
matching `dev`'s version).
|
|
110
|
+
|
|
111
|
+
Either way the workflow creates a [GitHub release](https://github.com/cmu-delphi/epidatpy/releases)
|
|
112
|
+
with auto-generated notes. Pushing the `vX.Y.Z` tag then triggers `pypi_publish`
|
|
113
|
+
(build + upload to [PyPI](https://pypi.python.org/pypi/epidatpy/)) and `documentation`
|
|
114
|
+
(docs rebuild). Because publishing is a separate workflow keyed off the tag rather
|
|
115
|
+
than a step inside `create_release`, a failed PyPI upload can be re-run against the
|
|
116
|
+
existing tag via the `pypi_publish` workflow's `Run workflow` button — without redoing
|
|
117
|
+
the release cut.
|
|
118
|
+
|
|
119
|
+
[mit-image]: https://img.shields.io/badge/License-MIT-yellow.svg
|
|
120
|
+
[mit-url]: https://opensource.org/licenses/MIT
|
|
121
|
+
[github-actions-image]: https://github.com/cmu-delphi/epidatpy/workflows/ci/badge.svg
|
|
122
|
+
[github-actions-url]: https://github.com/cmu-delphi/epidatpy/actions
|
|
123
|
+
[pypi-image]: https://img.shields.io/pypi/v/epidatpy
|
|
124
|
+
[pypi-url]: https://pypi.python.org/pypi/epidatpy/
|
|
125
|
+
[docs-image]: https://readthedocs.org/projects/epidatpy/badge/?version=latest
|
|
126
|
+
[docs-url]: https://epidatpy.readthedocs.io/en/latest/?badge=latest
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
# Configuration file for the Sphinx documentation builder.
|
|
2
|
+
#
|
|
3
|
+
# This file only contains a selection of the most common options. For a full
|
|
4
|
+
# list see the documentation:
|
|
5
|
+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
|
6
|
+
|
|
7
|
+
# -- Path setup --------------------------------------------------------------
|
|
8
|
+
|
|
9
|
+
# If extensions (or modules to document with autodoc) are in another directory,
|
|
10
|
+
# add these directories to sys.path here. If the directory is relative to the
|
|
11
|
+
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
|
12
|
+
#
|
|
13
|
+
import os
|
|
14
|
+
import sys
|
|
15
|
+
from importlib.metadata import version as _version
|
|
16
|
+
|
|
17
|
+
sys.path.insert(0, os.path.abspath(".."))
|
|
18
|
+
sys.path.insert(0, os.path.abspath("../epidatpy"))
|
|
19
|
+
|
|
20
|
+
# -- Project information -----------------------------------------------------
|
|
21
|
+
|
|
22
|
+
project = "epidatpy"
|
|
23
|
+
copyright = "2024, Delphi Research Group"
|
|
24
|
+
author = "Delphi Research Group"
|
|
25
|
+
|
|
26
|
+
# The full version, including alpha/beta/rc tags
|
|
27
|
+
release = _version("epidatpy")
|
|
28
|
+
version = release
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
# -- General configuration ---------------------------------------------------
|
|
32
|
+
|
|
33
|
+
# Add any Sphinx extension module names here, as strings. They can be
|
|
34
|
+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
|
35
|
+
# ones.
|
|
36
|
+
# myst_nb (Markdown + notebook support) implies myst_parser, so narrative pages
|
|
37
|
+
# can be authored in either Markdown (.md) or reStructuredText (.rst).
|
|
38
|
+
extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx_autodoc_typehints", "myst_nb"]
|
|
39
|
+
|
|
40
|
+
# Add any paths that contain templates here, relative to this directory.
|
|
41
|
+
templates_path = ["_templates"]
|
|
42
|
+
|
|
43
|
+
# List of patterns, relative to source directory, that match files and
|
|
44
|
+
# directories to ignore when looking for source files.
|
|
45
|
+
# This pattern also affects html_static_path and html_extra_path.
|
|
46
|
+
exclude_patterns = [
|
|
47
|
+
"_build",
|
|
48
|
+
# myst_nb writes executed notebook copies here; not standalone source docs.
|
|
49
|
+
"jupyter_execute",
|
|
50
|
+
"Thumbs.db",
|
|
51
|
+
".DS_Store",
|
|
52
|
+
"smoke_covid_test",
|
|
53
|
+
"smoke_test_async",
|
|
54
|
+
"smoke_test",
|
|
55
|
+
"tasks",
|
|
56
|
+
"test_pydantic",
|
|
57
|
+
]
|
|
58
|
+
|
|
59
|
+
add_module_names = False
|
|
60
|
+
autoclass_content = "class"
|
|
61
|
+
autodoc_typehints = "description"
|
|
62
|
+
|
|
63
|
+
# -- Options for HTML output -------------------------------------------------
|
|
64
|
+
|
|
65
|
+
# The theme to use for HTML and HTML Help pages. See the documentation for
|
|
66
|
+
# a list of builtin themes.
|
|
67
|
+
#
|
|
68
|
+
html_theme = "alabaster"
|
|
69
|
+
|
|
70
|
+
# Add any paths that contain custom static files (such as style sheets) here,
|
|
71
|
+
# relative to this directory. They are copied after the builtin static files,
|
|
72
|
+
# so a file named "default.css" will overwrite the builtin "default.css".
|
|
73
|
+
html_static_path = ["_static"]
|
|
74
|
+
|
|
75
|
+
html_theme_options = {
|
|
76
|
+
"extra_nav_links": {
|
|
77
|
+
"Delphi Research Group": "https://delphi.cmu.edu/",
|
|
78
|
+
"Delphi Epidata API": "https://cmu-delphi.github.io/delphi-epidata",
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
# Read The Docs
|
|
83
|
+
# on_rtd is whether we are on readthedocs.org, this line of code grabbed from
|
|
84
|
+
# docs.readthedocs.org
|
|
85
|
+
on_rtd = os.environ.get("READTHEDOCS", None) == "True"
|
|
86
|
+
|
|
87
|
+
# https://pypi.org/project/sphinx-autodoc-typehints/
|
|
88
|
+
always_document_param_types = True
|
|
89
|
+
|
|
90
|
+
# https://myst-nb.readthedocs.io/
|
|
91
|
+
# "auto" runs only notebooks that lack stored outputs (committed notebooks ship
|
|
92
|
+
# with outputs, so they render as-is without hitting the live API).
|
|
93
|
+
nb_execution_mode = "auto"
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
epidatpy Reference
|
|
2
|
+
==================
|
|
3
|
+
|
|
4
|
+
.. toctree::
|
|
5
|
+
:maxdepth: 4
|
|
6
|
+
|
|
7
|
+
epidatpy.request module
|
|
8
|
+
-----------------------
|
|
9
|
+
|
|
10
|
+
.. automodule:: epidatpy.request
|
|
11
|
+
:members:
|
|
12
|
+
:undoc-members:
|
|
13
|
+
:show-inheritance:
|
|
14
|
+
|
|
15
|
+
epidatpy._endpoints module
|
|
16
|
+
--------------------------
|
|
17
|
+
|
|
18
|
+
.. automodule:: epidatpy._endpoints
|
|
19
|
+
:members:
|
|
20
|
+
:undoc-members:
|
|
21
|
+
:show-inheritance:
|
|
22
|
+
:exclude-members: get_wildcard_equivalent_dates
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
===============
|
|
2
|
+
epidatpy
|
|
3
|
+
===============
|
|
4
|
+
|
|
5
|
+
This package provides Python access to the `Delphi Epidata API
|
|
6
|
+
<https://cmu-delphi.github.io/delphi-epidata/>`_ published by the `Delphi
|
|
7
|
+
research group <https://delphi.cmu.edu>`_ at `Carnegie Mellon University
|
|
8
|
+
<https://www.cmu.edu>`_. The package source code and bug tracker can be found
|
|
9
|
+
`on GitHub <https://github.com/cmu-delphi/epidatpy>`_.
|
|
10
|
+
|
|
11
|
+
.. note :: **You should consider subscribing** to the `API mailing list
|
|
12
|
+
<https://lists.andrew.cmu.edu/mailman/listinfo/delphi-covidcast-api>`_ to be
|
|
13
|
+
notified of package updates, new data sources, corrections, and other
|
|
14
|
+
updates.
|
|
15
|
+
|
|
16
|
+
See also the `CMU Delphi Terms of Use
|
|
17
|
+
<https://delphi.cmu.edu/epidemic-signals/terms-of-use/>`_, noting that the data
|
|
18
|
+
is a research product and not warranted for a particular purpose.
|
|
19
|
+
|
|
20
|
+
Installation
|
|
21
|
+
===============
|
|
22
|
+
|
|
23
|
+
This package will soon be available on PyPI as `epidatpy
|
|
24
|
+
<https://pypi.org/project/epidatpy/>`_. Meanwhile, it can be installed from
|
|
25
|
+
GitHub:
|
|
26
|
+
|
|
27
|
+
.. code-block:: sh
|
|
28
|
+
|
|
29
|
+
pip install -e "git+https://github.com/cmu-delphi/epidatpy.git#egg=epidatpy"
|
|
30
|
+
|
|
31
|
+
API Keys
|
|
32
|
+
===============
|
|
33
|
+
|
|
34
|
+
The Delphi Epidata API requires a (free) API key for full functionality. To
|
|
35
|
+
generate your key, register for a pseudo-anonymous account `here
|
|
36
|
+
<https://api.delphi.cmu.edu/epidata/admin/registration_form>`_ and see more
|
|
37
|
+
discussion on the `general API website
|
|
38
|
+
<https://cmu-delphi.github.io/delphi-epidata/api/api_keys.html>`_. The ``epidatpy``
|
|
39
|
+
client will automatically look for this key in the environment variable
|
|
40
|
+
``DELPHI_EPIDATA_KEY``. We recommend storing your key in a ``.env`` file, using
|
|
41
|
+
`python-dotenv <https://github.com/theskumar/python-dotenv>`_ to load it into
|
|
42
|
+
your environment, and adding ``.env`` to your ``.gitignore`` file.
|
|
43
|
+
|
|
44
|
+
Note that for the time being, the private endpoints (i.e. those prefixed with
|
|
45
|
+
``pvt``) will require additional permissions (contact us for more information).
|
|
46
|
+
|
|
47
|
+
Documentation Contents
|
|
48
|
+
======================
|
|
49
|
+
|
|
50
|
+
.. toctree::
|
|
51
|
+
:maxdepth: 1
|
|
52
|
+
|
|
53
|
+
getting_started
|
|
54
|
+
|
|
55
|
+
signal_discovery
|
|
56
|
+
|
|
57
|
+
versioned_data
|
|
58
|
+
|
|
59
|
+
epidatpy
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
"""Fetch data from Delphi's API."""
|
|
2
|
+
|
|
3
|
+
# Make the linter happy about the unused variables
|
|
4
|
+
__all__ = [
|
|
5
|
+
"__version__",
|
|
6
|
+
"available_endpoints",
|
|
7
|
+
"EpiDataContext",
|
|
8
|
+
"CovidcastEpidata",
|
|
9
|
+
"EpiRange",
|
|
10
|
+
"InvalidArgumentException",
|
|
11
|
+
]
|
|
12
|
+
__author__ = "Delphi Research Group"
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
from ._constants import __version__
|
|
16
|
+
from ._model import EpiRange, InvalidArgumentException
|
|
17
|
+
from .request import CovidcastEpidata, EpiDataContext, available_endpoints
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import os
|
|
2
|
+
import warnings
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
def _get_api_key() -> str:
|
|
6
|
+
key = os.environ.get("DELPHI_EPIDATA_KEY", "")
|
|
7
|
+
|
|
8
|
+
if not key:
|
|
9
|
+
warnings.warn(
|
|
10
|
+
"DELPHI_EPIDATA_KEY environment variable not set. "
|
|
11
|
+
"Please set it to your Epidata API key to avoid rate limits. "
|
|
12
|
+
"You can get a free key at: https://api.delphi.cmu.edu/epidata/admin/registration_form"
|
|
13
|
+
)
|
|
14
|
+
|
|
15
|
+
return key
|