diff --git a/docs/conf.py b/docs/conf.py index 268f542..a22a338 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -31,7 +31,7 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ["sphinx.ext.autodoc", "sphinx_autodoc_typehints", "nbsphinx"] +extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx_autodoc_typehints", "nbsphinx"] # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] diff --git a/docs/epidatpy.rst b/docs/epidatpy.rst index d3b7a1f..0e13e3c 100644 --- a/docs/epidatpy.rst +++ b/docs/epidatpy.rst @@ -1,5 +1,5 @@ epidatpy Reference -================ +================== .. toctree:: :maxdepth: 4 @@ -13,7 +13,7 @@ epidatpy.request module :show-inheritance: epidatpy._endpoints module ------------------------ +-------------------------- .. automodule:: epidatpy._endpoints :members: diff --git a/docs/getting_started.ipynb b/docs/getting_started.ipynb index ec34864..0f50d14 100644 --- a/docs/getting_started.ipynb +++ b/docs/getting_started.ipynb @@ -181,6 +181,65 @@ ").df()" ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "We can also request all versions of the data issued within a specific time range using the `issues` argument. `issues` can also take a single date.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# See how the estimate for a SINGLE day (March 1, 2021) evolved\n", + "# by fetching all issues reported between March and April 2021.\n", + "epidata.pub_covidcast(\n", + " data_source=\"fb-survey\",\n", + " signals=\"smoothed_cli\",\n", + " geo_type=\"state\",\n", + " time_type=\"day\",\n", + " geo_values=\"pa\",\n", + " time_values=\"2021-03-01\",\n", + " issues=EpiRange(\"2021-03-01\", \"2021-04-30\"),\n", + ").df()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Finally, we can use the `lag` argument to request only data that was reported a certain number of days after the event.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Fetch survey data for January 2021, but ONLY include data\n", + "# that was issued exactly 2 days after it was collected.\n", + "epidata.pub_covidcast(\n", + " data_source=\"fb-survey\",\n", + " signals=\"smoothed_cli\",\n", + " geo_type=\"state\",\n", + " time_type=\"day\",\n", + " geo_values=\"pa\",\n", + " time_values=EpiRange(20210101, 20210131),\n", + " lag=2,\n", + ").df()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "See detail notebook about [versioned data](versioned_data.ipynb) for details and more ways to specify versioned data.\n" + ] + }, { "cell_type": "markdown", "metadata": {}, @@ -234,9 +293,9 @@ "\n", "Most data is only available for the US. Select endpoints report other countries at the national and/or regional levels. Endpoint descriptions explicitly state when they cover non-US locations.\n", "\n", - "For endpoints that report US data, see the\n", + "For the main endpoints that report US data, see the\n", "[geographic coding documentation](https://cmu-delphi.github.io/delphi-epidata/api/covidcast_geography.html)\n", - "for available geographic levels.\n", + "for available geographic levels. Documentation for the other endpoints is available [here](https://cmu-delphi.github.io/delphi-epidata/api/geographic_codes.html).\n", "\n", "## International data\n", "\n", diff --git a/docs/index.rst b/docs/index.rst index f7f86a6..8248724 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -45,7 +45,7 @@ Note that for the time being, the private endpoints (i.e. those prefixed with ``pvt``) will require additional permissions (contact us for more information). Documentation Contents -=============== +====================== .. toctree:: :maxdepth: 1 diff --git a/docs/signal_discovery.ipynb b/docs/signal_discovery.ipynb index 830b216..2191dd0 100644 --- a/docs/signal_discovery.ipynb +++ b/docs/signal_discovery.ipynb @@ -147,6 +147,531 @@ "- `has_sample_size` - Whether the signal has `sample_size` statistic.\n", "- `geo_types` - Geographical levels for which this signal is available.\n" ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Example Queries\n", + "\n", + "### Main Endpoint\n", + "\n", + "API docs: \n", + "\n", + "County geo_values are [FIPS codes](https://en.wikipedia.org/wiki/List_of_United_States_FIPS_codes_by_county) and are discussed in the API docs [here](https://cmu-delphi.github.io/delphi-epidata/api/covidcast_geography.html). The example below is for Orange County, California.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from epidatpy import EpiDataContext, EpiRange\n", + "# Reuse existing context if available, but creating new one for standalone clarity\n", + "epidata = EpiDataContext()\n", + "\n", + "epidata.pub_covidcast(\n", + " data_source=\"fb-survey\",\n", + " signals=\"smoothed_accept_covid_vaccine\",\n", + " geo_type=\"county\",\n", + " time_type=\"day\",\n", + " time_values=EpiRange(20201221, 20201225),\n", + " geo_values=\"06059\"\n", + ").df()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Other Covid Endpoints\n", + "\n", + "#### COVID-19 Hospitalization: Facility Lookup\n", + "\n", + "API docs: \n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "epidata.pub_covid_hosp_facility_lookup(city=\"southlake\").df()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### COVID-19 Hospitalization by Facility\n", + "\n", + "API docs: \n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "epidata.pub_covid_hosp_facility(\n", + " hospital_pks=\"100075\",\n", + " collection_weeks=EpiRange(20200101, 20200501)\n", + ").df()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### COVID-19 Hospitalization by State\n", + "\n", + "API docs: \n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "epidata.pub_covid_hosp_state_timeseries(states=\"MA\", dates=\"20200510\").df()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Flu Endpoints\n", + "\n", + "#### FluSurv hospitalization data\n", + "\n", + "API docs: \n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "epidata.pub_flusurv(locations=\"ca\", epiweeks=202001).df()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### Fluview data\n", + "\n", + "API docs: \n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "epidata.pub_fluview(regions=\"nat\", epiweeks=EpiRange(201201, 202001)).df()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### Delphi's ILINet forecasts\n", + "\n", + "API docs: \n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "delphi_forecast = epidata.pub_delphi(system=\"ec\", epiweek=201501)\n", + "delphi_forecast()['epidata']" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### FluView Clinical\n", + "\n", + "API docs: \n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "epidata.pub_fluview_clinical(regions=\"nat\", epiweeks=EpiRange(201601, 201701)).df()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### FluView Metadata\n", + "\n", + "API docs: \n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "epidata.pub_fluview_meta().df()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### Google Flu Trends\n", + "\n", + "API docs: \n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "epidata.pub_gft(locations=\"hhs1\", epiweeks=EpiRange(201201, 202001)).df()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### ECDC ILI\n", + "\n", + "API docs: \n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "epidata.pub_ecdc_ili(regions=\"Armenia\", epiweeks=201840).df()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### KCDC ILI\n", + "\n", + "API docs: \n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "epidata.pub_kcdc_ili(regions=\"ROK\", epiweeks=200436).df()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### NIDSS Flu\n", + "\n", + "API docs: \n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "epidata.pub_nidss_flu(regions=\"taipei\", epiweeks=EpiRange(200901, 201301)).df()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### ILI Nearby Nowcast\n", + "\n", + "API docs: \n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "epidata.pub_nowcast(locations=\"ca\", epiweeks=EpiRange(202201, 202319)).df()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Dengue Endpoints\n", + "\n", + "#### Delphi's Dengue Nowcast\n", + "\n", + "API docs: \n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "epidata.pub_dengue_nowcast(locations=\"pr\", epiweeks=EpiRange(201401, 202301)).df()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### NIDSS Dengue\n", + "\n", + "API docs: \n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "epidata.pub_nidss_dengue(locations=\"taipei\", epiweeks=EpiRange(200301, 201301)).df()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### PAHO Dengue\n", + "\n", + "API docs: \n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "epidata.pub_paho_dengue(regions=\"ca\", epiweeks=EpiRange(200201, 202319)).df()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Other Endpoints\n", + "\n", + "#### Wikipedia Access\n", + "\n", + "API docs: \n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "epidata.pub_wiki(\n", + " language=\"en\",\n", + " articles=\"influenza\",\n", + " time_type=\"week\",\n", + " time_values=EpiRange(202001, 202319)\n", + ").df()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Private methods\n", + "\n", + "These require private access keys to use.\n", + "\n", + "#### Google Health Trends\n", + "\n", + "API docs: \n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Requires valid API key\n", + "# epidata.pvt_ght(\n", + "# auth=\"\",\n", + "# epiweeks=EpiRange(199301, 202304),\n", + "# locations=\"ma\",\n", + "# query=\"how to get over the flu\"\n", + "# ).df()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### CDC\n", + "\n", + "API docs: \n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# epidata.pvt_cdc(auth=\"...\", locations=\"ma\", epiweeks=EpiRange(202003, 202304)).df()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### Dengue Digital Surveillance Sensors\n", + "\n", + "API docs: \n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# epidata.pvt_dengue_sensors(\n", + "# auth=\"...\",\n", + "# names=\"ght\",\n", + "# locations=\"ag\",\n", + "# epiweeks=EpiRange(201404, 202004)\n", + "# ).df()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### NoroSTAT metadata\n", + "\n", + "API docs: \n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# epidata.pvt_meta_norostat(auth=\"...\").df()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### NoroSTAT data\n", + "\n", + "API docs: \n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# epidata.pvt_norostat(auth=\"...\", locations=\"1\", epiweeks=201233).df()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### Quidel Influenza testing\n", + "\n", + "API docs: \n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# epidata.pvt_quidel(auth=\"...\", locations=\"hhs1\", epiweeks=EpiRange(200301, 202105)).df()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### Sensors\n", + "\n", + "API docs: \n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# epidata.pvt_sensors(\n", + "# auth=\"...\",\n", + "# names=\"sar3\",\n", + "# locations=\"nat\",\n", + "# epiweeks=EpiRange(200301, 202105)\n", + "# ).df()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### Twitter\n", + "\n", + "API docs: \n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# epidata.pvt_twitter(\n", + "# auth=\"...\",\n", + "# locations=\"nat\",\n", + "# time_type=\"week\",\n", + "# time_values=EpiRange(200301, 202105)\n", + "# ).df()" + ] } ], "metadata": { diff --git a/docs/versioned_data.ipynb b/docs/versioned_data.ipynb index 02b3504..a99b182 100644 --- a/docs/versioned_data.ipynb +++ b/docs/versioned_data.ipynb @@ -22,7 +22,7 @@ "a combination of:\n", "\n", "- time taken by our data partner to collect the data\n", - "- time taken by the Dekohu Epidata API to ingest the data provided.\n", + "- time taken by the Delphi Epidata API to ingest the data provided.\n", "\n", "Later, the estimate for May 1st could be updated, perhaps because additional\n", "visit data from May 1st arrived at our source and was reported to us. This\n", @@ -189,6 +189,30 @@ ").df()" ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The `issues` parameter also accepts a list of dates (or epiweeks).\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "epidata.pub_covidcast(\n", + " data_source=\"doctor-visits\",\n", + " signals=\"smoothed_adj_cli\",\n", + " time_type=\"day\",\n", + " time_values=EpiRange(\"2020-05-01\", \"2020-05-01\"),\n", + " geo_type=\"state\",\n", + " geo_values=\"pa\",\n", + " issues=[\"2020-05-07\", \"2020-05-09\", \"2020-05-15\"],\n", + ").df()" + ] + }, { "cell_type": "markdown", "metadata": {}, @@ -254,8 +278,14 @@ } ], "metadata": { + "kernelspec": { + "display_name": ".venv", + "language": "python", + "name": "python3" + }, "language_info": { - "name": "python" + "name": "python", + "version": "3.11.14" } }, "nbformat": 4, diff --git a/epidatpy/_endpoints.py b/epidatpy/_endpoints.py index 4084434..db98c5b 100644 --- a/epidatpy/_endpoints.py +++ b/epidatpy/_endpoints.py @@ -54,7 +54,22 @@ def pvt_cdc( locations: StringParam, epiweeks: EpiRangeParam = "*", ) -> CALL_TYPE: - """Fetch CDC page hits.""" + """Fetch CDC total and by topic webpage visits. + + API docs: + + Parameters + ---------- + auth : str + Private API key. + locations : StringParam + Geographic locations to return. Supports a single string or a sequence of strings. + See `Geographic Codes `__. + epiweeks : EpiRangeParam + Epiweeks to fetch. Supports :class:`~epidatpy.EpiRange` and defaults to all ("*") weeks. + Format as ``epirange(startweek, endweek)``, where startweek and endweek are of the form + YYYYWW (string or numeric). + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "day") return self._create_call( @@ -84,7 +99,30 @@ def pub_covid_hosp_facility_lookup( zip: Optional[str] = None, # pylint: disable=redefined-builtin fips_code: Optional[str] = None, ) -> CALL_TYPE: - """Lookup COVID hospitalization facility identifiers.""" + """Helper for finding COVID hospitalization facilities. + + API docs: + + Obtains unique identifiers and other metadata for COVID hospitalization + facilities of interest. This is a companion endpoint to the + :meth:`pub_covid_hosp_facility` endpoint. + + Only one location argument needs to be specified. Combinations of the + arguments are not currently supported. + + Parameters + ---------- + state : str, optional + Two-letter state abbreviation. + ccn : str, optional + CMS Certification Number. + city : str, optional + City name. + zip : str, optional + 5-digit zip code. + fips_code : str, optional + A 5-digit FIPS county code, zero-padded. + """ if all(v is None for v in (state, ccn, city, zip, fips_code)): raise InvalidArgumentException("one of `state`, `ccn`, `city`, `zip`, or `fips_code` is required") @@ -117,7 +155,30 @@ def pub_covid_hosp_facility( collection_weeks: EpiRangeParam = "*", publication_dates: Optional[EpiRangeParam] = None, ) -> CALL_TYPE: - """Fetch COVID hospitalization data for specific facilities.""" + """Fetch COVID hospitalizations by facility. + + API docs: + + Obtains the COVID-19 reported patient impact and hospital capacity data by + facility. This dataset is provided by the US Department of Health & Human + Services. The companion function :meth:`pub_covid_hosp_facility_lookup` can be + used to look up facility identifiers in a variety of ways. + + Starting October 1, 2022, some facilities are only required to report + annually. + + Parameters + ---------- + hospital_pks : StringParam + Unique identifiers for hospitals of interest. Supports a single string or a sequence of strings. + collection_weeks : EpiRangeParam + Weekly data collection periods to fetch. Supports :class:`~epidatpy.EpiRange` and defaults to all + ("*") weeks. + Note: This parameter expects dates in YYYY-MM-DD or YYYYMMDD format. + If provided as ``Week``, they will be converted to the starting day of the week. + publication_dates : EpiRangeParam, optional + Publication dates to fetch. Supports :class:`~epidatpy.EpiRange`. Format as YYYY-MM-DD (string or numeric). + """ collection_weeks = get_wildcard_equivalent_dates(collection_weeks, "day") # Confusingly, the endpoint expects `collection_weeks` to be in day format, @@ -266,7 +327,33 @@ def pub_covid_hosp_state_timeseries( issues: Optional[EpiRangeParam] = None, as_of: Union[None, int, str] = None, ) -> CALL_TYPE: - """Fetch COVID hospitalization data.""" + """Fetch COVID hospitalizations by state. + + API docs: + + Obtains the COVID-19 reported patient impact and hospital capacity data by + state. This dataset is provided by the US Department of Health & Human + Services. + + Starting October 1, 2022, some facilities are only required to report + annually. + + Parameters + ---------- + states : StringParam + Geographic locations to return, formatted as two-letter state abbreviations. + Supports a single string or a sequence of strings. + dates : EpiRangeParam + Dates to fetch. Supports :class:`~epidatpy.EpiRange` and defaults to all ("*") dates. + Format as ``epirange(start, end)``, where start and end are of the form YYYYMMDD + (string or numeric). + issues : EpiRangeParam, optional + Range or list of issue dates to fetch. Supports :class:`~epidatpy.EpiRange`. Format as YYYYMMDD. + Mutually exclusive with `as_of`. + as_of : Union[int, str], optional + Fetch data as it was known as of this date. Format as YYYYMMDD. + Mutually exclusive with `issues`. + """ if issues is not None and as_of is not None: raise InvalidArgumentException("`issues` and `as_of` are mutually exclusive") @@ -353,13 +440,18 @@ def pub_covid_hosp_state_timeseries( def pub_covidcast_meta(self) -> CALL_TYPE: """Fetch COVIDcast surveillance stream metadata. + API docs: + Obtains a data frame of metadata describing all publicly available data streams from the COVIDcast API. See the `data source and signals documentation `_ for descriptions of the available sources. - :returns: A `EpiDataCall` object containing the following information: + Returns + ------- + CALL_TYPE + A ``EpiDataCall`` object containing the following information: ``data_source`` Data source name. @@ -387,7 +479,7 @@ def pub_covidcast_meta(self) -> CALL_TYPE: ``num_locations`` Number of distinct geographic locations available for this signal. For - example, if `geo_type` is county, the number of counties for which this + example, if ``geo_type`` is county, the number of counties for which this signal has ever been reported. ``min_value`` @@ -451,7 +543,45 @@ def pub_covidcast( issues: Optional[EpiRangeParam] = None, lag: Optional[int] = None, ) -> CALL_TYPE: - """Fetch Delphi's COVID-19 Surveillance Streams""" + """Fetch Delphi's COVID-19 Surveillance Streams. + + API docs: + + The primary endpoint for fetching COVID-19 data, providing access to a wide + variety of signals from a wide variety of sources. Delphi's `COVIDcast public + dashboard `_ is powered by this endpoint. + + Parameters + ---------- + data_source : str + The name of the data source to query. + See `Covidcast Signals `__. + signals : StringParam + The signals to query from a specific source. + See `Covidcast Signals `__. + geo_type : GeoType + The geographic resolution of the data. + See `Covidcast Geography `__. + time_type : TimeType + The temporal resolution of the data (either "day" or "week"). + geo_values : Union[str, Sequence[str]] + The geographic locations to return. Supports a single string, a sequence of strings, + or defaults to all locations ("*"). + See `Covidcast Geography `__. + time_values : EpiRangeParam + Temporal points to fetch. Supports :class:`~epidatpy.EpiRange` and defaults to all ("*") dates/weeks. + Format as ``epirange(start, end)``, where start and end are of the form YYYY-MM-DD + or YYYYWW depending on the ``time_type``. + as_of : Union[str, int], optional + Fetch data as it was known as of this date. + Mutually exclusive with ``issues`` and ``lag``. + issues : EpiRangeParam, optional + Range or list of issue dates to fetch. + Mutually exclusive with ``as_of`` and ``lag``. + lag : int, optional + Number of days between the observation and its publication. + Mutually exclusive with ``as_of`` and ``issues``. + """ if sum([issues is not None, lag is not None, as_of is not None]) > 1: raise InvalidArgumentException("`issues`, `lag`, and `as_of` are mutually exclusive.") @@ -475,7 +605,20 @@ def pub_covidcast( ) def pub_delphi(self, system: str, epiweek: Union[int, str]) -> CALL_TYPE: - """Fetch Delphi's forecast.""" + """Fetch Delphi's ILINet outpatient doctor visits forecasts. + + API docs: + + Parameters + ---------- + system : str + The name of the forecast system. + See `Forecasting Systems + `_. + epiweek : Union[int, str] + Epiweek to fetch. Does not support multiple dates. + Make separate calls to fetch data for multiple epiweeks. + """ return self._create_call( "delphi/", {"system": system, "epiweek": epiweek}, @@ -488,7 +631,21 @@ def pub_delphi(self, system: str, epiweek: Union[int, str]) -> CALL_TYPE: ) def pub_dengue_nowcast(self, locations: StringParam, epiweeks: EpiRangeParam = "*") -> CALL_TYPE: - """Fetch Delphi's dengue nowcast.""" + """Fetch Delphi's PAHO dengue nowcasts (North and South America). + + API docs: + + Parameters + ---------- + locations : StringParam + Geographic locations to return. Supports a single string or a sequence of strings. + See `Countries and Territories in the Americas + `__. + epiweeks : EpiRangeParam + Epiweeks to fetch. Supports :class:`~epidatpy.EpiRange` and defaults to all ("*") weeks. + Format as ``epirange(startweek, endweek)``, where startweek and endweek are of the form + YYYYWW (string or numeric). + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") return self._create_call( @@ -509,7 +666,27 @@ def pvt_dengue_sensors( locations: StringParam, epiweeks: EpiRangeParam = "*", ) -> CALL_TYPE: - """Fetch Delphi's digital surveillance sensors.""" + """Fetch PAHO dengue digital surveillance sensors (North and South America). + + API docs: + + Parameters + ---------- + auth : str + Private API key. + names : StringParam + Sensor names to fetch. + See `Dengue Sensors Indicators + `__. + locations : StringParam + List of countries in the Americas to fetch. + See `Countries and Territories in the Americas + `_. + epiweeks : EpiRangeParam + Epiweeks to fetch. Supports :class:`~epidatpy.EpiRange` and defaults to all ("*") weeks. + Format as ``epirange(startweek, endweek)``, where startweek and endweek are of the form + YYYYWW (string or numeric). + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") return self._create_call( @@ -535,7 +712,30 @@ def pub_ecdc_ili( issues: Optional[EpiRangeParam] = None, lag: Optional[int] = None, ) -> CALL_TYPE: - """Fetch ECDC ILI data.""" + """Fetch ECDC ILI incidence (Europe). + + API docs: + + Obtain information on influenza-like-illness from the European Centre for + Disease Prevention and Control. + + Parameters + ---------- + regions : StringParam + List of European countries to fetch. + See `European Countries + `_. + epiweeks : EpiRangeParam + Epiweeks to fetch. Supports :class:`~epidatpy.EpiRange` and defaults to all ("*") weeks. + Format as ``epirange(startweek, endweek)``, where startweek and endweek are of the form + YYYYWW (string or numeric). + issues : EpiRangeParam, optional + Range or list of issue dates to fetch. Supports :class:`~epidatpy.EpiRange`. + Mutually exclusive with ``lag``. + lag : int, optional + Number of days between the observation and its publication. + Mutually exclusive with ``issues``. + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") if issues is not None and lag is not None: @@ -561,7 +761,32 @@ def pub_flusurv( issues: Optional[EpiRangeParam] = None, lag: Optional[int] = None, ) -> CALL_TYPE: - """Fetch FluSurv data.""" + """Fetch CDC FluSurv flu hospitalizations. + + API docs: + + Obtain information on influenza hospitalization rates from the Center of Disease + Control. + + See also . + + Parameters + ---------- + locations : StringParam + List of locations to fetch. + See `FluSurv Locations + `_. + epiweeks : EpiRangeParam + Epiweeks to fetch. Supports :class:`~epidatpy.EpiRange` and defaults to all ("*") weeks. + Format as ``epirange(startweek, endweek)``, where startweek and endweek are of the form + YYYYWW (string or numeric). + issues : EpiRangeParam, optional + Range or list of issue dates to fetch. Supports `epirange()`. + Mutually exclusive with ``lag``. + lag : int, optional + Number of days between the observation and its publication. + Mutually exclusive with ``issues``. + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") if issues is not None and lag is not None: @@ -620,7 +845,27 @@ def pub_fluview_clinical( issues: Optional[EpiRangeParam] = None, lag: Optional[int] = None, ) -> CALL_TYPE: - """Fetch FluView clinical data.""" + """Fetch CDC FluView flu tests from clinical labs. + + API docs: + + Parameters + ---------- + regions : StringParam + List of regions to fetch. + See `US Regions and States + `__. + epiweeks : EpiRangeParam, default "*" + Epiweeks to fetch. Supports :class:`~epidatpy.EpiRange` and defaults to all ("*") weeks. + Format as ``epirange(startweek, endweek)``, where startweek and endweek are of the form + YYYYWW (string or numeric). + issues : EpiRangeParam, optional + Range or list of issue dates to fetch. Supports :class:`~epidatpy.EpiRange`. + Mutually exclusive with ``lag``. + lag : int, optional + Number of days between the observation and its publication. + Mutually exclusive with ``issues``. + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") if issues is not None and lag is not None: @@ -645,6 +890,10 @@ def pub_fluview_clinical( ) def pub_fluview_meta(self) -> CALL_TYPE: + """Fetch Metadata for the FluView endpoint. + + API docs: + """ return self._create_call( "fluview_meta", {}, @@ -663,6 +912,36 @@ def pub_fluview( lag: Optional[int] = None, auth: Optional[str] = None, ) -> CALL_TYPE: + """Fetch CDC FluView ILINet outpatient doctor visits. + + API docs: + + Obtains information on outpatient inluenza-like-illness (ILI) from U.S. + Outpatient Influenza-like Illness Surveillance Network (ILINet). + + See also . + + Parameters + ---------- + regions : StringParam + List of regions to fetch. + See `US Regions and States + `__ + and `FluView Cities + `__. + epiweeks : EpiRangeParam + Epiweeks to fetch. Supports :class:`~epidatpy.EpiRange` and defaults to all ("*") weeks. + Format as ``epirange(startweek, endweek)``, where startweek and endweek are of the form + YYYYWW (string or numeric). + issues : EpiRangeParam, optional + Range or list of issue dates to fetch. Supports :class:`~epidatpy.EpiRange`. + Mutually exclusive with ``lag``. + lag : int, optional + Number of days between the observation and its publication. + Mutually exclusive with ``issues``. + auth : str, optional + Private API key. + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") if issues is not None and lag is not None: @@ -697,7 +976,26 @@ def pub_fluview( ) def pub_gft(self, locations: StringParam, epiweeks: EpiRangeParam = "*") -> CALL_TYPE: - """Fetch Google Flu Trends data.""" + """Fetch Google Flu Trends flu search volume. + + API docs: + + Obtains estimates of inluenza activity based on volume of certain search + queries from Google. + + Google has discontinued Flu Trends and this is now a static endpoint. + + Parameters + ---------- + locations : StringParam + List of locations to fetch. + See `Geographic Codes + `__. + epiweeks : EpiRangeParam + Epiweeks to fetch. Supports :class:`~epidatpy.EpiRange` and defaults to all ("*") weeks. + Format as ``epirange(startweek, endweek)``, where startweek and endweek are of the form + YYYYWW (string or numeric). + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") return self._create_call( @@ -717,7 +1015,28 @@ def pvt_ght( epiweeks: EpiRangeParam = "*", query: str = "", ) -> CALL_TYPE: - """Fetch Google Health Trends data.""" + """Fetch Google Health Trends data. + + API docs: + + Requires a private API key. + + Parameters + ---------- + auth : str + Private API key. + locations : StringParam + List of locations to fetch. + See `Geographic Codes + `__. + epiweeks : EpiRangeParam, default "*" + Epiweeks to fetch. Supports :class:`~epidatpy.EpiRange` and defaults to all ("*") weeks. + Format as ``epirange(startweek, endweek)``, where startweek and endweek are of the form + YYYYWW (string or numeric). + query : str, default "" + GHT search query. + See `Valid Queries `__. + """ if auth is None or locations is None or query == "": raise InvalidArgumentException("`auth`, `locations`, `epiweeks`, and `query` are all required") @@ -743,7 +1062,33 @@ def pub_kcdc_ili( issues: Optional[EpiRangeParam] = None, lag: Optional[int] = None, ) -> CALL_TYPE: - """Fetch KCDC ILI data.""" + """Fetch KCDC ILI incidence (Korea). + + API docs: + + Obtain information on influenza-like-illness from the Korea Centers for + Disease Control and Prevention (KCDC). + + The list of location argument can be found in + . + + Parameters + ---------- + regions : StringParam + List of regions to fetch. + See `Republic of Korea + `__. + epiweeks : EpiRangeParam + Epiweeks to fetch. Supports :class:`~epidatpy.EpiRange` and defaults to all ("*") weeks. + Format as ``epirange(startweek, endweek)``, where startweek and endweek are of the form + YYYYWW (string or numeric). + issues : EpiRangeParam, optional + Range or list of issue dates to fetch. Supports `epirange()`. + Mutually exclusive with ``lag``. + lag : int, optional + Number of days between the observation and its publication. + Mutually exclusive with ``issues``. + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") if issues is not None and lag is not None: @@ -763,7 +1108,17 @@ def pub_kcdc_ili( ) def pvt_meta_norostat(self, auth: str) -> CALL_TYPE: - """Fetch NoroSTAT metadata.""" + """Fetch NoroSTAT metadata. + + API docs: + + Requires a private API key. + + Parameters + ---------- + auth : str + Private API key. + """ return self._create_call( "meta_norostat/", {"auth": auth}, @@ -771,7 +1126,10 @@ def pvt_meta_norostat(self, auth: str) -> CALL_TYPE: ) def pub_meta(self) -> CALL_TYPE: - """Fetch API metadata.""" + """Fetch API metadata. + + API docs: + """ return self._create_call( "meta/", {}, @@ -779,7 +1137,21 @@ def pub_meta(self) -> CALL_TYPE: ) def pub_nidss_dengue(self, locations: StringParam, epiweeks: EpiRangeParam = "*") -> CALL_TYPE: - """Fetch NIDSS dengue data.""" + """Fetch NIDSS dengue data (Taiwan). + + API docs: + + Parameters + ---------- + locations : StringParam + List of Taiwan locations to fetch. + See `Taiwan Locations + `_. + epiweeks : EpiRangeParam + Epiweeks to fetch. Supports :class:`~epidatpy.EpiRange` and defaults to all ("*") weeks. + Format as ``epirange(startweek, endweek)``, where startweek and endweek are of the form + YYYYWW (string or numeric). + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") return self._create_call( @@ -799,7 +1171,27 @@ def pub_nidss_flu( issues: Optional[EpiRangeParam] = None, lag: Optional[int] = None, ) -> CALL_TYPE: - """Fetch NIDSS flu data.""" + """Fetch NIDSS flu data (Taiwan). + + API docs: + + Parameters + ---------- + regions : StringParam + List of Taiwan locations to fetch. + See `Taiwan Locations + `_. + epiweeks : EpiRangeParam + Epiweeks to fetch. Supports :class:`~epidatpy.EpiRange` and defaults to all ("*") weeks. + Format as ``epirange(startweek, endweek)``, where startweek and endweek are of the form + YYYYWW (string or numeric). + issues : EpiRangeParam, optional + Range or list of issue dates to fetch. Supports `epirange()`. + Mutually exclusive with ``lag``. + lag : int, optional + Number of days between the observation and its publication. + Mutually exclusive with ``issues``. + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") if issues is not None and lag is not None: @@ -820,7 +1212,25 @@ def pub_nidss_flu( ) def pvt_norostat(self, auth: str, location: str, epiweeks: EpiRangeParam = "*") -> CALL_TYPE: - """Fetch NoroSTAT data (point data, no min/max).""" + """Fetch NoroSTAT data (point data, no min/max). + + API docs: + + Requires a private API key. + + Parameters + ---------- + auth : str + Private API key. + location : str + Locations to fetch. Only a specific list of + full state names are permitted. See the ``locations`` column in the + output of :meth:`pvt_meta_norostat` for the allowed values. + epiweeks : EpiRangeParam + Epiweeks to fetch. Supports :class:`~epidatpy.EpiRange` and defaults to all ("*") weeks. + Format as ``epirange(startweek, endweek)``, where startweek and endweek are of the form + YYYYWW (string or numeric). + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") return self._create_call( @@ -834,7 +1244,21 @@ def pvt_norostat(self, auth: str, location: str, epiweeks: EpiRangeParam = "*") ) def pub_nowcast(self, locations: StringParam, epiweeks: EpiRangeParam = "*") -> CALL_TYPE: - """Fetch Delphi's wILI nowcast.""" + """Fetch Delphi's wILI nowcast. + + API docs: + + Parameters + ---------- + locations : StringParam + List of locations to fetch. + See `Geographic Codes + `__. + epiweeks : EpiRangeParam + Epiweeks to fetch. Supports :class:`~epidatpy.EpiRange` and defaults to all ("*") weeks. + Format as ``epirange(startweek, endweek)``, where startweek and endweek are of the form + YYYYWW (string or numeric). + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") return self._create_call( @@ -855,7 +1279,28 @@ def pub_paho_dengue( issues: Optional[EpiRangeParam] = None, lag: Optional[int] = None, ) -> CALL_TYPE: - """Fetch PAHO Dengue data.""" + """Fetch PAHO Dengue data. + + API docs: + + Parameters + ---------- + regions : StringParam + List of American countries and territories to fetch. + See `Countries and Territories in the Americas + `__. + + epiweeks : EpiRangeParam + Epiweeks to fetch. Supports :class:`~epidatpy.EpiRange` and defaults to all ("*") weeks. + Format as ``epirange(startweek, endweek)``, where startweek and endweek are of the form + YYYYWW (string or numeric). + issues : EpiRangeParam, optional + Range or list of issue dates to fetch. Supports `epirange()`. + Mutually exclusive with ``lag``. + lag : int, optional + Number of days between the observation and its publication. + Mutually exclusive with ``issues``. + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") if issues is not None and lag is not None: @@ -880,7 +1325,25 @@ def pub_paho_dengue( ) def pvt_quidel(self, auth: str, locations: StringParam, epiweeks: EpiRangeParam = "*") -> CALL_TYPE: - """Fetch Quidel data.""" + """Fetch Quidel data. + + API docs: + + Requires a private API key. + + Parameters + ---------- + auth : str + Private API key. + locations : StringParam + List of locations to fetch. + See `Geographic Codes + `__. + epiweeks : EpiRangeParam + Epiweeks to fetch. Supports :class:`~epidatpy.EpiRange` and defaults to all ("*") weeks. + Format as ``epirange(startweek, endweek)``, where startweek and endweek are of the form + YYYYWW (string or numeric). + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") return self._create_call( @@ -900,7 +1363,27 @@ def pvt_sensors( locations: StringParam, epiweeks: EpiRangeParam = "*", ) -> CALL_TYPE: - """Fetch Delphi's digital surveillance sensors.""" + """Fetch Delphi's digital surveillance sensors. + + API docs: + + Requires a private API key. + + Parameters + ---------- + auth : str + Private API key. + names : StringParam + Sensor names to fetch. + See `Data Sources `_. + locations : StringParam + List of locations to fetch. + See `Geographic Codes `__. + epiweeks : EpiRangeParam + Epiweeks to fetch. Supports :class:`~epidatpy.EpiRange` and defaults to all ("*") weeks. + Format as ``epirange(startweek, endweek)``, where startweek and endweek are of the form + YYYYWW (string or numeric). + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") return self._create_call( @@ -926,7 +1409,26 @@ def pvt_twitter( time_type: Literal["day", "week"], time_values: EpiRangeParam = "*", ) -> CALL_TYPE: - """Fetch HealthTweets data.""" + """Fetch HealthTweets data. + + API docs: + + Requires a private API key. + + Parameters + ---------- + auth : str + Private API key. + locations : StringParam + List of locations to fetch. + See `Geographic Codes `__. + time_type : Literal["day", "week"] + The temporal resolution to use ("day" or "week"). + time_values : EpiRangeParam, default "*" + Temporal points to fetch. Supports :class:`~epidatpy.EpiRange` and defaults to all ("*") dates/weeks. + Format as ``epirange(start, end)``, where start and end are of the form YYYY-MM-DD + or YYYYWW depending on the ``time_type``. + """ if time_type == "day": dates = time_values epiweeks = None @@ -967,7 +1469,27 @@ def pub_wiki( hours: Optional[IntParam] = None, language: str = "en", ) -> CALL_TYPE: - """Fetch Wikipedia access data.""" + """Fetch Wikipedia access data. + + API docs: + + Parameters + ---------- + articles : StringParam + The Wikipedia article(s) to fetch. Supports a single string or a sequence of strings. + See `Available Articles + `_. + time_type : Literal["day", "week"] + The temporal resolution to use ("day" or "week"). + time_values : EpiRangeParam, default "*" + Temporal points to fetch. Supports :class:`~epidatpy.EpiRange` and defaults to all ("*") dates/weeks. + Format as ``epirange(start, end)``, where start and end are of the form YYYY-MM-DD + or YYYYWW depending on the ``time_type``. + hours : IntParam, optional + A list of hours to include. + language : str, default "en" + Two-letter language code. + """ if time_type == "day": dates = time_values epiweeks = None