Skip to content

Commit 5294fe3

Browse files
dshemetovdshemetov
committed
doc: iterate on all documentation pages, README
1 parent 7820ad8 commit 5294fe3

10 files changed

+325
-317
lines changed

‎README.md

Lines changed: 20 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
[![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]
44

5-
A Python client for the [Delphi Epidata API](https://cmu-delphi.github.io/delphi-epidata/). Still in development.
5+
The Python client for the [Delphi Epidata API](https://cmu-delphi.github.io/delphi-epidata/).
66

77
## Install
88

@@ -18,7 +18,23 @@ pip install epidatpy
1818

1919
## Usage
2020

21-
TODO
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+
```
2238

2339
## Development
2440

@@ -35,8 +51,8 @@ make release # upload the current version to pypi
3551
make clean # clean build and docs artifacts
3652
```
3753

38-
Building the documentation additionally requires the Pandoc package. These commands can be used
39-
to install the package on common platforms (see the
54+
Building the documentation additionally requires the Pandoc package. These
55+
commands can be used to install the package on common platforms (see the
4056
[official documentation](https://pandoc.org/installing.html) for more options):
4157

4258
```sh

‎docs/conf.py

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -31,12 +31,7 @@
3131
# Add any Sphinx extension module names here, as strings. They can be
3232
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
3333
# ones.
34-
extensions = [
35-
"sphinx.ext.autodoc",
36-
"sphinx_autodoc_typehints",
37-
# 'matplotlib.sphinxext.plot_directive'
38-
"nbsphinx"
39-
]
34+
extensions = ["sphinx.ext.autodoc", "sphinx_autodoc_typehints", "nbsphinx"]
4035

4136
# Add any paths that contain templates here, relative to this directory.
4237
templates_path = ["_templates"]

‎docs/getting_started.ipynb

Lines changed: 97 additions & 109 deletions
Original file line numberDiff line numberDiff line change
@@ -4,44 +4,13 @@
44
"cell_type": "markdown",
55
"metadata": {},
66
"source": [
7-
"# Getting started with epidatpy\n",
7+
"# Getting started\n",
88
"\n",
99
"The epidatpy package provides access to all the endpoints of the [Delphi Epidata\n",
1010
"API](https://cmu-delphi.github.io/delphi-epidata/), and can be used to make\n",
1111
"requests for specific signals on specific dates and in select geographic\n",
1212
"regions.\n",
1313
"\n",
14-
"## Setup\n",
15-
"\n",
16-
"### Installation\n",
17-
"\n",
18-
"You can install the stable version of this package from PyPi:\n",
19-
"\n",
20-
"```\n",
21-
"pip install epidatpy\n",
22-
"```\n",
23-
"\n",
24-
"Or if you want the development version, install from GitHub:\n",
25-
"\n",
26-
"```\n",
27-
"pip install -e \"git+https://github.com/cmu-delphi/epidatpy.git#egg=epidatpy\"\n",
28-
"```\n",
29-
"\n",
30-
"\n",
31-
"### API keys\n",
32-
"\n",
33-
"The Delphi API requires a (free) API key for full functionality. While most\n",
34-
"endpoints are available without one, there are\n",
35-
"[limits on API usage for anonymous users](https://cmu-delphi.github.io/delphi-epidata/api/api_keys.html),\n",
36-
"including a rate limit.\n",
37-
"\n",
38-
"To generate your key,\n",
39-
"[register for a pseudo-anonymous account](https://api.delphi.cmu.edu/epidata/admin/registration_form).\n",
40-
"\n",
41-
"*Note* that private endpoints (i.e. those prefixed with `pvt_`) require a\n",
42-
"separate key that needs to be passed as an argument. These endpoints require\n",
43-
"specific data use agreements to access.\n",
44-
"\n",
4514
"## Basic usage\n",
4615
"\n",
4716
"Fetching data from the Delphi Epidata API is simple. Suppose we are\n",
@@ -52,43 +21,55 @@
5221
"a data source name, a signal name, a geographic level, a time resolution, and\n",
5322
"the location and times of interest.\n",
5423
"\n",
55-
"The `pub_covidcast` function lets us access the `covidcast` endpoint:"
24+
"The `pub_covidcast` function lets us access the `covidcast` endpoint. Here we\n",
25+
"demonstrate how to fetch the most up-to-date version of the confirmed cumulative COVID cases\n",
26+
"from the JHU CSSE data source at the national level."
5627
]
5728
},
5829
{
5930
"cell_type": "code",
6031
"execution_count": null,
61-
"metadata": {},
32+
"metadata": {
33+
"nbsphinx": "hidden"
34+
},
6235
"outputs": [],
6336
"source": [
64-
"from epidatpy import EpiDataContext, EpiRange\n",
37+
"# Hidden cell (set in the metadata for this cell)\n",
6538
"import pandas as pd\n",
6639
"\n",
6740
"# Set common options and context\n",
68-
"pd.set_option('display.max_columns', None)\n",
69-
"pd.set_option('display.max_rows', None)\n",
70-
"pd.set_option('display.width', 1000)\n",
71-
"\n",
72-
"epidata = EpiDataContext(use_cache=False)\n",
73-
"\n",
74-
"# Obtain the most up-to-date version of the smoothed covid-like illness (CLI)\n",
75-
"# signal from the COVID-19 Trends and Impact survey for the US\n",
76-
"apicall = epidata.pub_covidcast(\n",
77-
" data_source = \"fb-survey\",\n",
78-
" signals = \"smoothed_cli\",\n",
79-
" geo_type = \"nation\",\n",
80-
" time_type = \"day\",\n",
81-
" geo_values = \"us\",\n",
82-
" time_values = EpiRange(20210405, 20210410))\n",
83-
"\n",
84-
"print(apicall)"
41+
"pd.set_option(\"display.max_columns\", None)\n",
42+
"pd.set_option(\"display.max_rows\", 10)\n",
43+
"pd.set_option(\"display.width\", 1000)"
8544
]
8645
},
8746
{
88-
"cell_type": "markdown",
47+
"cell_type": "code",
48+
"execution_count": null,
8949
"metadata": {},
50+
"outputs": [],
9051
"source": [
91-
"`pub_covidcast` returns an `EpiDataCall`, which is a not-yet-executed query that can be inspected. The query can be executed and converted to a DataFrame by using the `.df()` method:\n"
52+
"from epidatpy import CovidcastEpidata, EpiDataContext, EpiRange\n",
53+
"\n",
54+
"# Create the client object. Note that due to the arguments below all results\n",
55+
"# will be cached to your disk for 7 days, which helps avoid making repeated\n",
56+
"# downloads.\n",
57+
"epidata = EpiDataContext(use_cache=True, cache_max_age_days=7)\n",
58+
"\n",
59+
"# `pub_covidcast` returns an `EpiDataCall`, which is a not-yet-executed query\n",
60+
"# that can be inspected.\n",
61+
"apicall = epidata.pub_covidcast(\n",
62+
" data_source=\"jhu-csse\",\n",
63+
" signals=\"confirmed_cumulative_num\",\n",
64+
" geo_type=\"nation\",\n",
65+
" time_type=\"day\",\n",
66+
" geo_values=\"us\",\n",
67+
" time_values=EpiRange(20210405, 20210410),\n",
68+
")\n",
69+
"print(apicall)\n",
70+
"# The query can be executed and converted to a DataFrame by using the `.df()`\n",
71+
"# method:\n",
72+
"apicall.df()"
9273
]
9374
},
9475
{
@@ -97,8 +78,19 @@
9778
"metadata": {},
9879
"outputs": [],
9980
"source": [
100-
"data = apicall.df()\n",
101-
"print(data.head())"
81+
"# Create the pub_covidcast-specific client object. This you to find what sources\n",
82+
"# and signals are available without leaving your REPL.\n",
83+
"covidcast = CovidcastEpidata(use_cache=True, cache_max_age_days=7)\n",
84+
"# Get a list of all the sources available in the pub_covidcast endpoint.\n",
85+
"print(covidcast.source_names())\n",
86+
"print(covidcast.signal_names(\"jhu-csse\"))\n",
87+
"# Obtain the same data as above with a different interface.\n",
88+
"covidcast[\"jhu-csse\", \"confirmed_cumulative_num\"].call(\n",
89+
" \"nation\",\n",
90+
" \"us\",\n",
91+
" EpiRange(20210405, 20210410),\n",
92+
").df()\n",
93+
"# See the \"Finding data of interest\" notebook for more features of this interface."
10294
]
10395
},
10496
{
@@ -125,16 +117,14 @@
125117
"metadata": {},
126118
"outputs": [],
127119
"source": [
128-
"apicall = epidata.pub_covidcast(\n",
129-
" data_source = \"fb-survey\",\n",
130-
" signals = \"smoothed_cli\",\n",
131-
" geo_type = \"state\",\n",
132-
" time_type = \"day\",\n",
133-
" geo_values = \"*\",\n",
134-
" time_values = EpiRange(20210405, 20210410))\n",
135-
"\n",
136-
"print(apicall)\n",
137-
"print(apicall.df().head())"
120+
"epidata.pub_covidcast(\n",
121+
" data_source=\"fb-survey\",\n",
122+
" signals=\"smoothed_cli\",\n",
123+
" geo_type=\"state\",\n",
124+
" time_type=\"day\",\n",
125+
" geo_values=\"*\",\n",
126+
" time_values=EpiRange(20210405, 20210410),\n",
127+
").df()"
138128
]
139129
},
140130
{
@@ -152,16 +142,14 @@
152142
"metadata": {},
153143
"outputs": [],
154144
"source": [
155-
"apicall = epidata.pub_covidcast(\n",
156-
" data_source = \"fb-survey\",\n",
157-
" signals = \"smoothed_cli\",\n",
158-
" geo_type = \"state\",\n",
159-
" time_type = \"day\",\n",
160-
" geo_values = \"pa,ca,fl\",\n",
161-
" time_values = EpiRange(20210405, 20210410))\n",
162-
"\n",
163-
"print(apicall)\n",
164-
"print(apicall.df().head())"
145+
"epidata.pub_covidcast(\n",
146+
" data_source=\"fb-survey\",\n",
147+
" signals=\"smoothed_cli\",\n",
148+
" geo_type=\"state\",\n",
149+
" time_type=\"day\",\n",
150+
" geo_values=\"pa,ca,fl\",\n",
151+
" time_values=\"*\",\n",
152+
").df()"
165153
]
166154
},
167155
{
@@ -182,17 +170,15 @@
182170
"metadata": {},
183171
"outputs": [],
184172
"source": [
185-
"apicall = epidata.pub_covidcast(\n",
186-
" data_source = \"fb-survey\",\n",
187-
" signals = \"smoothed_cli\",\n",
188-
" geo_type = \"state\",\n",
189-
" time_type = \"day\",\n",
190-
" geo_values = \"pa\",\n",
191-
" time_values = EpiRange(20210405, 20210410),\n",
192-
" as_of = \"2021-06-01\")\n",
193-
"\n",
194-
"print(apicall)\n",
195-
"print(apicall.df().head())"
173+
"epidata.pub_covidcast(\n",
174+
" data_source=\"fb-survey\",\n",
175+
" signals=\"smoothed_cli\",\n",
176+
" geo_type=\"state\",\n",
177+
" time_type=\"day\",\n",
178+
" geo_values=\"pa\",\n",
179+
" time_values=EpiRange(20210405, 20210410),\n",
180+
" as_of=\"2021-06-01\",\n",
181+
").df()"
196182
]
197183
},
198184
{
@@ -213,32 +199,30 @@
213199
"source": [
214200
"import matplotlib.pyplot as plt\n",
215201
"\n",
216-
"plt.rcParams['figure.dpi'] = 300\n",
202+
"plt.rcParams[\"figure.dpi\"] = 300\n",
217203
"\n",
218204
"apicall = epidata.pub_covidcast(\n",
219-
" data_source = \"fb-survey\",\n",
220-
" signals = \"smoothed_cli\", \n",
221-
" geo_type = \"state\",\n",
222-
" geo_values = \"pa,ca,fl\",\n",
223-
" time_type = \"day\",\n",
224-
" time_values = EpiRange(20210405, 20210410))\n",
225-
"\n",
226-
"data = apicall.df()\n",
205+
" data_source=\"fb-survey\",\n",
206+
" signals=\"smoothed_cli\",\n",
207+
" geo_type=\"state\",\n",
208+
" geo_values=\"pa,ca,fl\",\n",
209+
" time_type=\"day\",\n",
210+
" time_values=EpiRange(20210405, 20210410),\n",
211+
")\n",
227212
"\n",
228213
"fig, ax = plt.subplots(figsize=(6, 5))\n",
229214
"ax.spines[\"right\"].set_visible(False)\n",
230215
"ax.spines[\"left\"].set_visible(False)\n",
231216
"ax.spines[\"top\"].set_visible(False)\n",
232217
"\n",
233-
"data.pivot_table(values = \"value\", index = \"time_value\", columns = \"geo_value\").plot(\n",
234-
" xlabel=\"Date\",\n",
235-
" ylabel=\"CLI\",\n",
236-
" ax = ax,\n",
237-
" linewidth = 1.5\n",
218+
"(\n",
219+
" apicall.df()\n",
220+
" .pivot_table(values=\"value\", index=\"time_value\", columns=\"geo_value\")\n",
221+
" .plot(xlabel=\"Date\", ylabel=\"CLI\", ax=ax, linewidth=1.5)\n",
238222
")\n",
239223
"\n",
240224
"plt.title(\"Smoothed CLI from Facebook Survey\", fontsize=16)\n",
241-
"plt.subplots_adjust(bottom=.2)\n",
225+
"plt.subplots_adjust(bottom=0.2)\n",
242226
"plt.show()"
243227
]
244228
},
@@ -279,20 +263,24 @@
279263
"\n",
280264
"## Epiweeks and dates\n",
281265
"\n",
282-
"Epiweeks use the U.S. definition. That is, the first epiweek each year is the\n",
283-
"week, starting on a Sunday, containing January 4. See [this page](https://www.cmmcp.org/mosquito-surveillance-data/pages/epi-week-calendars-2008-2021)\n",
284-
"for more information.\n",
285-
"\n",
286266
"Formatting for epiweeks is YYYYWW and for dates is YYYYMMDD.\n",
287267
"\n",
288-
"Use individual values, comma-separated lists or, a hyphenated range of values to specify single or several dates.\n",
289-
"An `EpiRange` object can be also used to construct a range of epiweeks or dates. Examples include:\n",
268+
"Epiweeks use the U.S. CDC definition, which defines the first epiweek each year\n",
269+
"to be the first week containing January 4th and the start of the week is on\n",
270+
"Sunday. See [this\n",
271+
"page](https://www.cmmcp.org/mosquito-surveillance-data/pages/epi-week-calendars-2008-2021)\n",
272+
"for a less terse explanation. \n",
273+
"\n",
274+
"When specifying the time_values argument, you can use individual values,\n",
275+
"comma-separated lists or, a hyphenated range of values to specify single or\n",
276+
"several dates (or epiweeks). An `EpiRange` object can be also used to construct\n",
277+
"a range of epiweeks or dates. Examples include:\n",
290278
"\n",
291279
"- `param = 201530` (A single epiweek)\n",
292280
"- `param = '201401,201501,201601'` (Several epiweeks)\n",
293281
"- `param = '200501-200552'` (A range of epiweeks)\n",
294282
"- `param = '201440,201501-201510'` (Several epiweeks, including a range)\n",
295-
"- `param = EpiRange(20070101, 20071231)` (A range of dates)"
283+
"- `param = EpiRange(20070101, 20071231)` (A range of dates)\n"
296284
]
297285
}
298286
],

0 commit comments

Comments
 (0)