From d48fa5687e62fdf86d05017116fbde7a81fa3adf Mon Sep 17 00:00:00 2001 From: JavierMtzRdz Date: Wed, 28 Jan 2026 15:49:12 -0800 Subject: [PATCH 01/30] docs: add CDC page and parameters --- epidatpy/_endpoints.py | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/epidatpy/_endpoints.py b/epidatpy/_endpoints.py index 4084434..f55a935 100644 --- a/epidatpy/_endpoints.py +++ b/epidatpy/_endpoints.py @@ -54,7 +54,19 @@ 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 + List of locations. + epiweeks : EpiRangeParam, default "*" + Range or list of epiweeks. + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "day") return self._create_call( From 32f8a12ee2d597443873e72333f07f251b314ca5 Mon Sep 17 00:00:00 2001 From: JavierMtzRdz Date: Wed, 28 Jan 2026 15:50:30 -0800 Subject: [PATCH 02/30] docs: add covid facility page and parameters --- epidatpy/_endpoints.py | 47 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 45 insertions(+), 2 deletions(-) diff --git a/epidatpy/_endpoints.py b/epidatpy/_endpoints.py index f55a935..603ac15 100644 --- a/epidatpy/_endpoints.py +++ b/epidatpy/_endpoints.py @@ -96,7 +96,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 + `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 + State abbreviation. + ccn : str, optional + CMS Certification Number. + city : str, optional + City name. + zip : str, optional + Zip code. + fips_code : str, optional + FIPS code. + """ 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") @@ -129,7 +152,27 @@ 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 `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 + List of hospital identifiers. + collection_weeks : EpiRangeParam, default "*" + Range or list of epiweeks. + publication_dates : EpiRangeParam, optional + Range or list of publication dates. + """ collection_weeks = get_wildcard_equivalent_dates(collection_weeks, "day") # Confusingly, the endpoint expects `collection_weeks` to be in day format, From 91ee1a48a097a0b51521d5843e3112d8ede0578d Mon Sep 17 00:00:00 2001 From: JavierMtzRdz Date: Wed, 28 Jan 2026 15:51:10 -0800 Subject: [PATCH 03/30] docs: add covid facility state timeseries page and parameters --- epidatpy/_endpoints.py | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/epidatpy/_endpoints.py b/epidatpy/_endpoints.py index 603ac15..47a79b1 100644 --- a/epidatpy/_endpoints.py +++ b/epidatpy/_endpoints.py @@ -321,7 +321,28 @@ 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 + List of state abbreviations. + dates : EpiRangeParam, default "*" + Range or list of dates. + issues : EpiRangeParam, optional + Range or list of issue dates. + as_of : Union[int, str], optional + Fetch data as of this date. + """ if issues is not None and as_of is not None: raise InvalidArgumentException("`issues` and `as_of` are mutually exclusive") From 87f55c29ea84e383423ce3f3579657c57c29c4d1 Mon Sep 17 00:00:00 2001 From: JavierMtzRdz Date: Wed, 28 Jan 2026 16:20:51 -0800 Subject: [PATCH 04/30] docs: add covidcast metta page and parameters --- epidatpy/_endpoints.py | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/epidatpy/_endpoints.py b/epidatpy/_endpoints.py index 47a79b1..e9e2adf 100644 --- a/epidatpy/_endpoints.py +++ b/epidatpy/_endpoints.py @@ -429,13 +429,39 @@ 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: + Parameters + ---------- + data_source : str + Data source name. + signals : StringParam + Signal name. + geo_type : GeoType + Geographic level. + time_type : TimeType + Temporal resolution. + geo_values : Union[str, Sequence[str]], default "*" + Which locations to return. + time_values : EpiRangeParam, default "*" + Which time points to return. + as_of : Union[str, int], optional + Fetch data as of this date. + issues : EpiRangeParam, optional + Range or list of issue dates. + lag : int, optional + Lag days. + + Returns + ------- + CALL_TYPE + A `EpiDataCall` object containing the following information: ``data_source`` Data source name. From c857bf01c480aa609a5d4dec19b7df231868c3f3 Mon Sep 17 00:00:00 2001 From: JavierMtzRdz Date: Wed, 28 Jan 2026 16:21:10 -0800 Subject: [PATCH 05/30] docs: add covidcast page and parameters --- docs/conf.py | 2 +- epidatpy/_endpoints.py | 30 +++++++++++++++++++++++++++++- 2 files changed, 30 insertions(+), 2 deletions(-) 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/epidatpy/_endpoints.py b/epidatpy/_endpoints.py index e9e2adf..b948dac 100644 --- a/epidatpy/_endpoints.py +++ b/epidatpy/_endpoints.py @@ -553,7 +553,35 @@ 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 + Data source name. + signals : StringParam + Signal name. + geo_type : GeoType + Geographic level. + time_type : TimeType + Temporal resolution. + geo_values : Union[str, Sequence[str]], default "*" + Which locations to return. + time_values : EpiRangeParam, default "*" + Which time points to return. + as_of : Union[str, int], optional + Fetch data as of this date. + issues : EpiRangeParam, optional + Range or list of issue dates. + lag : int, optional + Lag days. + """ 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.") From f0efde27d7a303961ab0ee7718309ed722cc358e Mon Sep 17 00:00:00 2001 From: JavierMtzRdz Date: Wed, 28 Jan 2026 16:21:43 -0800 Subject: [PATCH 06/30] docs: add Delphi forecast page and parameters --- epidatpy/_endpoints.py | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/epidatpy/_endpoints.py b/epidatpy/_endpoints.py index b948dac..664e9d3 100644 --- a/epidatpy/_endpoints.py +++ b/epidatpy/_endpoints.py @@ -605,7 +605,17 @@ 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 + System name. + epiweek : Union[int, str] + Epiweek. + """ return self._create_call( "delphi/", {"system": system, "epiweek": epiweek}, From 0be339ee9403a5cbee846ea28aab933f1e38cc5a Mon Sep 17 00:00:00 2001 From: JavierMtzRdz Date: Wed, 28 Jan 2026 16:23:09 -0800 Subject: [PATCH 07/30] docs: add dengue nowcast page and parameters --- docs/conf.py | 2 +- epidatpy/_endpoints.py | 12 +++++++++++- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index a22a338..268f542 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.ext.napoleon", "sphinx_autodoc_typehints", "nbsphinx"] +extensions = ["sphinx.ext.autodoc", "sphinx_autodoc_typehints", "nbsphinx"] # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] diff --git a/epidatpy/_endpoints.py b/epidatpy/_endpoints.py index 664e9d3..16aeed0 100644 --- a/epidatpy/_endpoints.py +++ b/epidatpy/_endpoints.py @@ -628,7 +628,17 @@ 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 + List of locations. + epiweeks : EpiRangeParam, default "*" + Range or list of epiweeks. + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") return self._create_call( From 336aef242e82bcbdec45b4b05142ea7f52c48640 Mon Sep 17 00:00:00 2001 From: JavierMtzRdz Date: Wed, 28 Jan 2026 16:23:47 -0800 Subject: [PATCH 08/30] docs: add dengue sensor page and parameters --- epidatpy/_endpoints.py | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/epidatpy/_endpoints.py b/epidatpy/_endpoints.py index 16aeed0..7f7ccdd 100644 --- a/epidatpy/_endpoints.py +++ b/epidatpy/_endpoints.py @@ -659,7 +659,21 @@ 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 + List of sensor names. + locations : StringParam + List of locations. + epiweeks : EpiRangeParam, default "*" + Range or list of epiweeks. + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") return self._create_call( From 2d77f8234a1cb36e73530dc2952a59cd06512c45 Mon Sep 17 00:00:00 2001 From: JavierMtzRdz Date: Wed, 28 Jan 2026 16:24:06 -0800 Subject: [PATCH 09/30] docs: add ECDC page and parameters --- epidatpy/_endpoints.py | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/epidatpy/_endpoints.py b/epidatpy/_endpoints.py index 7f7ccdd..d01b938 100644 --- a/epidatpy/_endpoints.py +++ b/epidatpy/_endpoints.py @@ -699,7 +699,27 @@ 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. + + The list of location argument can be found in + . + + Parameters + ---------- + regions : StringParam + List of regions. + epiweeks : EpiRangeParam, default "*" + Range or list of epiweeks. + issues : EpiRangeParam, optional + Range or list of issue dates. + lag : int, optional + Lag days. + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") if issues is not None and lag is not None: From 43a61ac5b0ef4302ed33ab76624a8648d60f72a2 Mon Sep 17 00:00:00 2001 From: JavierMtzRdz Date: Wed, 28 Jan 2026 16:24:28 -0800 Subject: [PATCH 10/30] docs: add FluSurv page and parameters --- epidatpy/_endpoints.py | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/epidatpy/_endpoints.py b/epidatpy/_endpoints.py index d01b938..c504b40 100644 --- a/epidatpy/_endpoints.py +++ b/epidatpy/_endpoints.py @@ -745,7 +745,29 @@ 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 . + + The list of location argument can be found in + . + + Parameters + ---------- + locations : StringParam + List of locations. + epiweeks : EpiRangeParam, default "*" + Range or list of epiweeks. + issues : EpiRangeParam, optional + Range or list of issue dates. + lag : int, optional + Lag days. + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") if issues is not None and lag is not None: From d7e2fa7b1bbcc3bc0e49994ad463fff8b16a7db3 Mon Sep 17 00:00:00 2001 From: JavierMtzRdz Date: Wed, 28 Jan 2026 16:25:11 -0800 Subject: [PATCH 11/30] docs: add Flueview page and parameters --- epidatpy/_endpoints.py | 48 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 47 insertions(+), 1 deletion(-) diff --git a/epidatpy/_endpoints.py b/epidatpy/_endpoints.py index c504b40..76c7036 100644 --- a/epidatpy/_endpoints.py +++ b/epidatpy/_endpoints.py @@ -826,7 +826,24 @@ 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: + + The list of location argument can be found in + . + + Parameters + ---------- + regions : StringParam + List of regions. + epiweeks : EpiRangeParam, default "*" + Range or list of epiweeks. + issues : EpiRangeParam, optional + Range or list of issue dates. + lag : int, optional + Lag days. + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") if issues is not None and lag is not None: @@ -851,6 +868,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", {}, @@ -869,6 +890,31 @@ 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 . + + The full list of location inputs can be accessed at + . + + Parameters + ---------- + regions : StringParam + List of regions. + epiweeks : EpiRangeParam, default "*" + Range or list of epiweeks. + issues : EpiRangeParam, optional + Range or list of issue dates. + lag : int, optional + Lag days. + auth : str, optional + Private API key. + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") if issues is not None and lag is not None: From f6ea62c67f1d118101e7b7858bcdb60cd51d419c Mon Sep 17 00:00:00 2001 From: JavierMtzRdz Date: Wed, 28 Jan 2026 16:25:38 -0800 Subject: [PATCH 12/30] docs: add gft page and parameters --- epidatpy/_endpoints.py | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/epidatpy/_endpoints.py b/epidatpy/_endpoints.py index 76c7036..e2cf46e 100644 --- a/epidatpy/_endpoints.py +++ b/epidatpy/_endpoints.py @@ -949,7 +949,22 @@ 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. + epiweeks : EpiRangeParam, default "*" + Range or list of epiweeks. + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") return self._create_call( From bad0378e808f52b459c5ba9555a15ed94fd1d48e Mon Sep 17 00:00:00 2001 From: JavierMtzRdz Date: Wed, 28 Jan 2026 16:25:53 -0800 Subject: [PATCH 13/30] docs: add ght page and parameters --- epidatpy/_endpoints.py | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/epidatpy/_endpoints.py b/epidatpy/_endpoints.py index e2cf46e..9efe471 100644 --- a/epidatpy/_endpoints.py +++ b/epidatpy/_endpoints.py @@ -984,7 +984,23 @@ 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. + epiweeks : EpiRangeParam, default "*" + Range or list of epiweeks. + query : str, default "" + GHT search query. + """ if auth is None or locations is None or query == "": raise InvalidArgumentException("`auth`, `locations`, `epiweeks`, and `query` are all required") From ed7e9cf431d44f530d6b48f7ed52c584183cd257 Mon Sep 17 00:00:00 2001 From: JavierMtzRdz Date: Wed, 28 Jan 2026 16:26:03 -0800 Subject: [PATCH 14/30] docs: add KCDC page and parameters --- epidatpy/_endpoints.py | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/epidatpy/_endpoints.py b/epidatpy/_endpoints.py index 9efe471..bcc82fb 100644 --- a/epidatpy/_endpoints.py +++ b/epidatpy/_endpoints.py @@ -1026,7 +1026,27 @@ 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. + epiweeks : EpiRangeParam, default "*" + Range or list of epiweeks. + issues : EpiRangeParam, optional + Range or list of issue dates. + lag : int, optional + Lag days. + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") if issues is not None and lag is not None: From 045ec83494ffde684c309e149eaf516f0541cc69 Mon Sep 17 00:00:00 2001 From: JavierMtzRdz Date: Wed, 28 Jan 2026 16:26:47 -0800 Subject: [PATCH 15/30] docs: add meta NOROSTAT page and parameters --- epidatpy/_endpoints.py | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/epidatpy/_endpoints.py b/epidatpy/_endpoints.py index bcc82fb..f41f336 100644 --- a/epidatpy/_endpoints.py +++ b/epidatpy/_endpoints.py @@ -1066,7 +1066,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}, From 4ebb7acbcd3a0c61fb62ff4cb77dd96820f7d2c4 Mon Sep 17 00:00:00 2001 From: JavierMtzRdz Date: Wed, 28 Jan 2026 16:27:06 -0800 Subject: [PATCH 16/30] docs: add meta function page and parameters --- epidatpy/_endpoints.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/epidatpy/_endpoints.py b/epidatpy/_endpoints.py index f41f336..2b438af 100644 --- a/epidatpy/_endpoints.py +++ b/epidatpy/_endpoints.py @@ -1084,7 +1084,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/", {}, From 84c4f41b39ab0362583d281f36cc1c21330c6340 Mon Sep 17 00:00:00 2001 From: JavierMtzRdz Date: Wed, 28 Jan 2026 16:27:21 -0800 Subject: [PATCH 17/30] docs: add NIDSS page and parameters --- epidatpy/_endpoints.py | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/epidatpy/_endpoints.py b/epidatpy/_endpoints.py index 2b438af..62758e7 100644 --- a/epidatpy/_endpoints.py +++ b/epidatpy/_endpoints.py @@ -1095,7 +1095,17 @@ 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 locations. + epiweeks : EpiRangeParam, default "*" + Range or list of epiweeks. + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") return self._create_call( From 8fcb74eb6b52fec739d53b7b63729464cbcbc949 Mon Sep 17 00:00:00 2001 From: JavierMtzRdz Date: Wed, 28 Jan 2026 16:27:53 -0800 Subject: [PATCH 18/30] docs: add missing NoroSTAT and NIDSS pages and parameters --- epidatpy/_endpoints.py | 32 ++++++++++++++++++++++++++++++-- 1 file changed, 30 insertions(+), 2 deletions(-) diff --git a/epidatpy/_endpoints.py b/epidatpy/_endpoints.py index 62758e7..4e729c0 100644 --- a/epidatpy/_endpoints.py +++ b/epidatpy/_endpoints.py @@ -1125,7 +1125,21 @@ 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 regions. + epiweeks : EpiRangeParam, default "*" + Range or list of epiweeks. + issues : EpiRangeParam, optional + Range or list of issue dates. + lag : int, optional + Lag days. + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") if issues is not None and lag is not None: @@ -1146,7 +1160,21 @@ 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 + Location. + epiweeks : EpiRangeParam, default "*" + Range or list of epiweeks. + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") return self._create_call( From d34198816c162ed0a8395e219923bdeb2075dd8b Mon Sep 17 00:00:00 2001 From: JavierMtzRdz Date: Wed, 28 Jan 2026 16:28:12 -0800 Subject: [PATCH 19/30] docs: add nowcast page and parameters --- epidatpy/_endpoints.py | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/epidatpy/_endpoints.py b/epidatpy/_endpoints.py index 4e729c0..6ee975c 100644 --- a/epidatpy/_endpoints.py +++ b/epidatpy/_endpoints.py @@ -1188,7 +1188,17 @@ 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. + epiweeks : EpiRangeParam, default "*" + Range or list of epiweeks. + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") return self._create_call( From f382becef871f48c91e2ff1e925d9b59b437ea13 Mon Sep 17 00:00:00 2001 From: JavierMtzRdz Date: Wed, 28 Jan 2026 16:28:32 -0800 Subject: [PATCH 20/30] docs: add PAHO page and parameters --- epidatpy/_endpoints.py | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/epidatpy/_endpoints.py b/epidatpy/_endpoints.py index 6ee975c..915f802 100644 --- a/epidatpy/_endpoints.py +++ b/epidatpy/_endpoints.py @@ -1219,7 +1219,21 @@ 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 regions. + epiweeks : EpiRangeParam, default "*" + Range or list of epiweeks. + issues : EpiRangeParam, optional + Range or list of issue dates. + lag : int, optional + Lag days. + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") if issues is not None and lag is not None: From 72e81cb740d55c4fa30002958b565c68e0bbebc1 Mon Sep 17 00:00:00 2001 From: JavierMtzRdz Date: Wed, 28 Jan 2026 16:28:48 -0800 Subject: [PATCH 21/30] docs: add Quidel page and parameters --- epidatpy/_endpoints.py | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/epidatpy/_endpoints.py b/epidatpy/_endpoints.py index 915f802..7ea0b68 100644 --- a/epidatpy/_endpoints.py +++ b/epidatpy/_endpoints.py @@ -1258,7 +1258,21 @@ 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. + epiweeks : EpiRangeParam, default "*" + Range or list of epiweeks. + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") return self._create_call( From cfb5bc4902357dd9b30432ab124d54c660c1c147 Mon Sep 17 00:00:00 2001 From: JavierMtzRdz Date: Wed, 28 Jan 2026 16:29:01 -0800 Subject: [PATCH 22/30] docs: add Sensors page and parameters --- epidatpy/_endpoints.py | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/epidatpy/_endpoints.py b/epidatpy/_endpoints.py index 7ea0b68..7b16049 100644 --- a/epidatpy/_endpoints.py +++ b/epidatpy/_endpoints.py @@ -1292,7 +1292,23 @@ 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 + List of sensor names. + locations : StringParam + List of locations. + epiweeks : EpiRangeParam, default "*" + Range or list of epiweeks. + """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") return self._create_call( From 5be08723a7c93ae8ea1546c12dd82c03ba690663 Mon Sep 17 00:00:00 2001 From: JavierMtzRdz Date: Wed, 28 Jan 2026 16:29:38 -0800 Subject: [PATCH 23/30] docs: add twitter and Wikipedia pages and parameters --- epidatpy/_endpoints.py | 36 ++++++++++++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) diff --git a/epidatpy/_endpoints.py b/epidatpy/_endpoints.py index 7b16049..e61e42c 100644 --- a/epidatpy/_endpoints.py +++ b/epidatpy/_endpoints.py @@ -1334,7 +1334,23 @@ 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. + time_type : Literal["day", "week"] + Literal used to set which temporal resolution to use. + time_values : EpiRangeParam, default "*" + Range or list of dates or epiweeks (depending on time_type). + """ if time_type == "day": dates = time_values epiweeks = None @@ -1375,7 +1391,23 @@ 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 + List of Wikipedia articles. + time_type : Literal["day", "week"] + Literal used to set which temporal resolution to use. + time_values : EpiRangeParam, default "*" + Range or list of dates or epiweeks (depending on time_type). + hours : IntParam, optional + List of hours (optional). + language : str, default "en" + Language code. + """ if time_type == "day": dates = time_values epiweeks = None From f2f65aa84edeaa432d81775bc7847e9f4c78c5f3 Mon Sep 17 00:00:00 2001 From: JavierMtzRdz Date: Mon, 2 Feb 2026 12:50:18 -0800 Subject: [PATCH 24/30] Add Napoleon in the Sphinx configuration. This helps to render NumPy style docstrings as those provided in the package. --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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"] From 906fb3d5ca77fabf39fe7851de54b0757b88cd7f Mon Sep 17 00:00:00 2001 From: JavierMtzRdz Date: Tue, 3 Feb 2026 10:08:29 -0800 Subject: [PATCH 25/30] docs: clean up parameter descriptions --- epidatpy/_endpoints.py | 287 ++++++++++++++++++++++++----------------- 1 file changed, 168 insertions(+), 119 deletions(-) diff --git a/epidatpy/_endpoints.py b/epidatpy/_endpoints.py index e61e42c..d2b3b41 100644 --- a/epidatpy/_endpoints.py +++ b/epidatpy/_endpoints.py @@ -63,9 +63,11 @@ def pvt_cdc( auth : str Private API key. locations : StringParam - List of locations. - epiweeks : EpiRangeParam, default "*" - Range or list of epiweeks. + Geographic locations to return. Supports a single string or a sequence of strings. + epiweeks : EpiRangeParam + Epiweeks to fetch. Supports `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") @@ -110,15 +112,15 @@ def pub_covid_hosp_facility_lookup( Parameters ---------- state : str, optional - State abbreviation. + Two-letter state abbreviation. ccn : str, optional CMS Certification Number. city : str, optional City name. zip : str, optional - Zip code. + 5-digit zip code. fips_code : str, optional - FIPS code. + 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") @@ -167,11 +169,13 @@ def pub_covid_hosp_facility( Parameters ---------- hospital_pks : StringParam - List of hospital identifiers. - collection_weeks : EpiRangeParam, default "*" - Range or list of epiweeks. + 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 `epirange()` and defaults to all ("*") weeks. + Note: This parameter expects dates in YYYY-MM-DD or YYYYMMDD format. + If provided as `Week` objects, they will be converted to the starting day of the week. publication_dates : EpiRangeParam, optional - Range or list of publication dates. + Publication dates to fetch. Supports `epirange()`. Format as YYYY-MM-DD (string or numeric). """ collection_weeks = get_wildcard_equivalent_dates(collection_weeks, "day") @@ -335,13 +339,18 @@ def pub_covid_hosp_state_timeseries( Parameters ---------- states : StringParam - List of state abbreviations. - dates : EpiRangeParam, default "*" - Range or list of dates. + 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 `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. + Range or list of issue dates to fetch. Supports `epirange()`. Format as YYYYMMDD. + Mutually exclusive with `as_of`. as_of : Union[int, str], optional - Fetch data as of this date. + 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") @@ -437,27 +446,6 @@ def pub_covidcast_meta(self) -> CALL_TYPE: `_ for descriptions of the available sources. - Parameters - ---------- - data_source : str - Data source name. - signals : StringParam - Signal name. - geo_type : GeoType - Geographic level. - time_type : TimeType - Temporal resolution. - geo_values : Union[str, Sequence[str]], default "*" - Which locations to return. - time_values : EpiRangeParam, default "*" - Which time points to return. - as_of : Union[str, int], optional - Fetch data as of this date. - issues : EpiRangeParam, optional - Range or list of issue dates. - lag : int, optional - Lag days. - Returns ------- CALL_TYPE @@ -564,23 +552,33 @@ def pub_covidcast( Parameters ---------- data_source : str - Data source name. + The name of the data source to query (see: + ). signals : StringParam - Signal name. + The signals to query from a specific source (see: + ). geo_type : GeoType - Geographic level. + The geographic resolution of the data (see: + ). time_type : TimeType - Temporal resolution. - geo_values : Union[str, Sequence[str]], default "*" - Which locations to return. - time_values : EpiRangeParam, default "*" - Which time points to return. + The temporal resolution. + 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: + ). + time_values : EpiRangeParam + Temporal points to fetch. Supports `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 of this date. + 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. + Range or list of issue dates to fetch. + Mutually exclusive with `as_of` and `lag`. lag : int, optional - Lag days. + 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.") @@ -612,9 +610,10 @@ def pub_delphi(self, system: str, epiweek: Union[int, str]) -> CALL_TYPE: Parameters ---------- system : str - System name. + The name of the forecast system. epiweek : Union[int, str] - Epiweek. + Epiweek to fetch. Does not support multiple dates. + Make separate calls to fetch data for multiple epiweeks. """ return self._create_call( "delphi/", @@ -635,9 +634,11 @@ def pub_dengue_nowcast(self, locations: StringParam, epiweeks: EpiRangeParam = " Parameters ---------- locations : StringParam - List of locations. - epiweeks : EpiRangeParam, default "*" - Range or list of epiweeks. + Geographic locations to return. Supports a single string or a sequence of strings. + epiweeks : EpiRangeParam + Epiweeks to fetch. Supports `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") @@ -668,11 +669,13 @@ def pvt_dengue_sensors( auth : str Private API key. names : StringParam - List of sensor names. + Sensor names to fetch. locations : StringParam - List of locations. - epiweeks : EpiRangeParam, default "*" - Range or list of epiweeks. + Geographic locations to fetch. Supports a single string or a sequence of strings. + epiweeks : EpiRangeParam + Epiweeks to fetch. Supports `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") @@ -712,13 +715,17 @@ def pub_ecdc_ili( Parameters ---------- regions : StringParam - List of regions. - epiweeks : EpiRangeParam, default "*" - Range or list of epiweeks. + List of regions to fetch. + epiweeks : EpiRangeParam + Epiweeks to fetch. Supports `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. + Range or list of issue dates to fetch. Supports `epirange()`. + Mutually exclusive with `lag`. lag : int, optional - Lag days. + Number of days between the observation and its publication. + Mutually exclusive with `issues`. """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") @@ -760,13 +767,17 @@ def pub_flusurv( Parameters ---------- locations : StringParam - List of locations. - epiweeks : EpiRangeParam, default "*" - Range or list of epiweeks. + List of locations to fetch. + epiweeks : EpiRangeParam + Epiweeks to fetch. Supports `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. + Range or list of issue dates to fetch. Supports `epirange()`. + Mutually exclusive with `lag`. lag : int, optional - Lag days. + Number of days between the observation and its publication. + Mutually exclusive with `issues`. """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") @@ -836,13 +847,17 @@ def pub_fluview_clinical( Parameters ---------- regions : StringParam - List of regions. + List of regions to fetch. epiweeks : EpiRangeParam, default "*" - Range or list of epiweeks. + Epiweeks to fetch. Supports `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. + Range or list of issue dates to fetch. Supports `epirange()`. + Mutually exclusive with `lag`. lag : int, optional - Lag days. + Number of days between the observation and its publication. + Mutually exclusive with `issues`. """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") @@ -905,13 +920,17 @@ def pub_fluview( Parameters ---------- regions : StringParam - List of regions. - epiweeks : EpiRangeParam, default "*" - Range or list of epiweeks. + List of regions to fetch. + epiweeks : EpiRangeParam + Epiweeks to fetch. Supports `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. + Range or list of issue dates to fetch. Supports `epirange()`. + Mutually exclusive with `lag`. lag : int, optional - Lag days. + Number of days between the observation and its publication. + Mutually exclusive with `issues`. auth : str, optional Private API key. """ @@ -961,9 +980,11 @@ def pub_gft(self, locations: StringParam, epiweeks: EpiRangeParam = "*") -> CALL Parameters ---------- locations : StringParam - List of locations. - epiweeks : EpiRangeParam, default "*" - Range or list of epiweeks. + List of locations to fetch. + epiweeks : EpiRangeParam + Epiweeks to fetch. Supports `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") @@ -995,9 +1016,11 @@ def pvt_ght( auth : str Private API key. locations : StringParam - List of locations. + List of locations to fetch. epiweeks : EpiRangeParam, default "*" - Range or list of epiweeks. + Epiweeks to fetch. Supports `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. """ @@ -1039,13 +1062,17 @@ def pub_kcdc_ili( Parameters ---------- regions : StringParam - List of regions. - epiweeks : EpiRangeParam, default "*" - Range or list of epiweeks. + List of regions to fetch. + epiweeks : EpiRangeParam + Epiweeks to fetch. Supports `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. + Range or list of issue dates to fetch. Supports `epirange()`. + Mutually exclusive with `lag`. lag : int, optional - Lag days. + Number of days between the observation and its publication. + Mutually exclusive with `issues`. """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") @@ -1102,9 +1129,11 @@ def pub_nidss_dengue(self, locations: StringParam, epiweeks: EpiRangeParam = "*" Parameters ---------- locations : StringParam - List of locations. - epiweeks : EpiRangeParam, default "*" - Range or list of epiweeks. + List of locations to fetch. + epiweeks : EpiRangeParam + Epiweeks to fetch. Supports `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") @@ -1132,13 +1161,17 @@ def pub_nidss_flu( Parameters ---------- regions : StringParam - List of regions. - epiweeks : EpiRangeParam, default "*" - Range or list of epiweeks. + List of regions to fetch. + epiweeks : EpiRangeParam + Epiweeks to fetch. Supports `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. + Range or list of issue dates to fetch. Supports `epirange()`. + Mutually exclusive with `lag`. lag : int, optional - Lag days. + Number of days between the observation and its publication. + Mutually exclusive with `issues`. """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") @@ -1171,9 +1204,11 @@ def pvt_norostat(self, auth: str, location: str, epiweeks: EpiRangeParam = "*") auth : str Private API key. location : str - Location. - epiweeks : EpiRangeParam, default "*" - Range or list of epiweeks. + Location to fetch. + epiweeks : EpiRangeParam + Epiweeks to fetch. Supports `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") @@ -1195,9 +1230,11 @@ def pub_nowcast(self, locations: StringParam, epiweeks: EpiRangeParam = "*") -> Parameters ---------- locations : StringParam - List of locations. - epiweeks : EpiRangeParam, default "*" - Range or list of epiweeks. + List of locations to fetch. + epiweeks : EpiRangeParam + Epiweeks to fetch. Supports `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") @@ -1226,13 +1263,17 @@ def pub_paho_dengue( Parameters ---------- regions : StringParam - List of regions. - epiweeks : EpiRangeParam, default "*" - Range or list of epiweeks. + List of regions to fetch. + epiweeks : EpiRangeParam + Epiweeks to fetch. Supports `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. + Range or list of issue dates to fetch. Supports `epirange()`. + Mutually exclusive with `lag`. lag : int, optional - Lag days. + Number of days between the observation and its publication. + Mutually exclusive with `issues`. """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") @@ -1269,9 +1310,11 @@ def pvt_quidel(self, auth: str, locations: StringParam, epiweeks: EpiRangeParam auth : str Private API key. locations : StringParam - List of locations. - epiweeks : EpiRangeParam, default "*" - Range or list of epiweeks. + List of locations to fetch. + epiweeks : EpiRangeParam + Epiweeks to fetch. Supports `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") @@ -1303,11 +1346,13 @@ def pvt_sensors( auth : str Private API key. names : StringParam - List of sensor names. + Sensor names to fetch. locations : StringParam - List of locations. - epiweeks : EpiRangeParam, default "*" - Range or list of epiweeks. + List of locations to fetch. + epiweeks : EpiRangeParam + Epiweeks to fetch. Supports `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") @@ -1345,11 +1390,13 @@ def pvt_twitter( auth : str Private API key. locations : StringParam - List of locations. + List of locations to fetch. time_type : Literal["day", "week"] - Literal used to set which temporal resolution to use. + The temporal resolution to use ("day" or "week"). time_values : EpiRangeParam, default "*" - Range or list of dates or epiweeks (depending on time_type). + Temporal points to fetch. Supports `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 @@ -1398,15 +1445,17 @@ def pub_wiki( Parameters ---------- articles : StringParam - List of Wikipedia articles. + The Wikipedia article(s) to fetch. Supports a single string or a sequence of strings. time_type : Literal["day", "week"] - Literal used to set which temporal resolution to use. + The temporal resolution to use ("day" or "week"). time_values : EpiRangeParam, default "*" - Range or list of dates or epiweeks (depending on time_type). + Temporal points to fetch. Supports `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 - List of hours (optional). + A list of hours to include. language : str, default "en" - Language code. + Two-letter language code. """ if time_type == "day": dates = time_values From d7119d2113c93e1cdef200278d35796f53d2c5d5 Mon Sep 17 00:00:00 2001 From: JavierMtzRdz Date: Thu, 5 Feb 2026 12:28:07 -0800 Subject: [PATCH 26/30] docs: add reference to specific valid parameter inputs. --- epidatpy/_endpoints.py | 54 ++++++++++++++++++++++++++++++------------ 1 file changed, 39 insertions(+), 15 deletions(-) diff --git a/epidatpy/_endpoints.py b/epidatpy/_endpoints.py index d2b3b41..9db8dcd 100644 --- a/epidatpy/_endpoints.py +++ b/epidatpy/_endpoints.py @@ -64,6 +64,7 @@ def pvt_cdc( 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 `epirange()` and defaults to all ("*") weeks. Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form @@ -552,20 +553,20 @@ def pub_covidcast( Parameters ---------- data_source : str - The name of the data source to query (see: - ). + The name of the data source to query. + See `Covidcast Signals `__. signals : StringParam - The signals to query from a specific source (see: - ). + The signals to query from a specific source. + See `Covidcast Signals `__. geo_type : GeoType - The geographic resolution of the data (see: - ). + The geographic resolution of the data. + See `Covidcast Geography `__. time_type : TimeType - The temporal resolution. + 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: - ). + or defaults to all locations ("*"). + See `Covidcast Geography `__. time_values : EpiRangeParam Temporal points to fetch. Supports `epirange()` and defaults to all ("*") dates/weeks. Format as `epirange(start, end)`, where start and end are of the form YYYY-MM-DD @@ -611,6 +612,7 @@ def pub_delphi(self, system: str, epiweek: Union[int, str]) -> CALL_TYPE: ---------- 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. @@ -635,6 +637,7 @@ def pub_dengue_nowcast(self, locations: StringParam, epiweeks: EpiRangeParam = " ---------- 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 `epirange()` and defaults to all ("*") weeks. Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form @@ -670,8 +673,10 @@ def pvt_dengue_sensors( Private API key. names : StringParam Sensor names to fetch. + See `Dengue Sensors Indicators `__. locations : StringParam - Geographic locations to fetch. Supports a single string or a sequence of strings. + List of countries in the Americas to fetch. + See `Countries and Territories in the Americas `_. epiweeks : EpiRangeParam Epiweeks to fetch. Supports `epirange()` and defaults to all ("*") weeks. Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form @@ -715,7 +720,8 @@ def pub_ecdc_ili( Parameters ---------- regions : StringParam - List of regions to fetch. + List of European countries to fetch. + See `European Countries `_. epiweeks : EpiRangeParam Epiweeks to fetch. Supports `epirange()` and defaults to all ("*") weeks. Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form @@ -768,6 +774,7 @@ def pub_flusurv( ---------- locations : StringParam List of locations to fetch. + See `FluSurv Locations `_. epiweeks : EpiRangeParam Epiweeks to fetch. Supports `epirange()` and defaults to all ("*") weeks. Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form @@ -848,6 +855,7 @@ def pub_fluview_clinical( ---------- regions : StringParam List of regions to fetch. + See `HHS Regions `_. epiweeks : EpiRangeParam, default "*" Epiweeks to fetch. Supports `epirange()` and defaults to all ("*") weeks. Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form @@ -921,6 +929,7 @@ def pub_fluview( ---------- regions : StringParam List of regions to fetch. + See `Geographic Codes `__. epiweeks : EpiRangeParam Epiweeks to fetch. Supports `epirange()` and defaults to all ("*") weeks. Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form @@ -981,6 +990,7 @@ def pub_gft(self, locations: StringParam, epiweeks: EpiRangeParam = "*") -> CALL ---------- locations : StringParam List of locations to fetch. + See `Geographic Codes `__. epiweeks : EpiRangeParam Epiweeks to fetch. Supports `epirange()` and defaults to all ("*") weeks. Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form @@ -1017,12 +1027,14 @@ def pvt_ght( Private API key. locations : StringParam List of locations to fetch. + See `Geographic Codes `__. epiweeks : EpiRangeParam, default "*" Epiweeks to fetch. Supports `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") @@ -1063,6 +1075,7 @@ def pub_kcdc_ili( ---------- regions : StringParam List of regions to fetch. + See `Republic of Korea `_. epiweeks : EpiRangeParam Epiweeks to fetch. Supports `epirange()` and defaults to all ("*") weeks. Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form @@ -1129,7 +1142,8 @@ def pub_nidss_dengue(self, locations: StringParam, epiweeks: EpiRangeParam = "*" Parameters ---------- locations : StringParam - List of locations to fetch. + List of Taiwan locations to fetch. + See `Taiwan Locations `_. epiweeks : EpiRangeParam Epiweeks to fetch. Supports `epirange()` and defaults to all ("*") weeks. Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form @@ -1161,7 +1175,8 @@ def pub_nidss_flu( Parameters ---------- regions : StringParam - List of regions to fetch. + List of Taiwan locations to fetch. + See `Taiwan Locations `_. epiweeks : EpiRangeParam Epiweeks to fetch. Supports `epirange()` and defaults to all ("*") weeks. Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form @@ -1204,7 +1219,9 @@ def pvt_norostat(self, auth: str, location: str, epiweeks: EpiRangeParam = "*") auth : str Private API key. location : str - Location to fetch. + 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 `epirange()` and defaults to all ("*") weeks. Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form @@ -1231,6 +1248,7 @@ def pub_nowcast(self, locations: StringParam, epiweeks: EpiRangeParam = "*") -> ---------- locations : StringParam List of locations to fetch. + See `Geographic Codes `__. epiweeks : EpiRangeParam Epiweeks to fetch. Supports `epirange()` and defaults to all ("*") weeks. Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form @@ -1263,7 +1281,8 @@ def pub_paho_dengue( Parameters ---------- regions : StringParam - List of regions to fetch. + List of American countries and territories to fetch. + See `Countries and Territories in the Americas `__. epiweeks : EpiRangeParam Epiweeks to fetch. Supports `epirange()` and defaults to all ("*") weeks. Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form @@ -1311,6 +1330,7 @@ def pvt_quidel(self, auth: str, locations: StringParam, epiweeks: EpiRangeParam Private API key. locations : StringParam List of locations to fetch. + See `Geographic Codes `__. epiweeks : EpiRangeParam Epiweeks to fetch. Supports `epirange()` and defaults to all ("*") weeks. Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form @@ -1347,8 +1367,10 @@ def pvt_sensors( 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 `epirange()` and defaults to all ("*") weeks. Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form @@ -1391,6 +1413,7 @@ def pvt_twitter( 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 "*" @@ -1446,6 +1469,7 @@ def pub_wiki( ---------- 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 "*" From c00a23a7833e5b64318c54f4ed338507e924deea Mon Sep 17 00:00:00 2001 From: JavierMtzRdz Date: Thu, 5 Feb 2026 13:47:35 -0800 Subject: [PATCH 27/30] docs: fix documentation formatting and replace duplicate links with valid geo_values --- epidatpy/_endpoints.py | 160 ++++++++++++++++++++--------------------- 1 file changed, 76 insertions(+), 84 deletions(-) diff --git a/epidatpy/_endpoints.py b/epidatpy/_endpoints.py index 9db8dcd..80eb69c 100644 --- a/epidatpy/_endpoints.py +++ b/epidatpy/_endpoints.py @@ -66,8 +66,8 @@ def pvt_cdc( Geographic locations to return. Supports a single string or a sequence of strings. See `Geographic Codes `__. epiweeks : EpiRangeParam - Epiweeks to fetch. Supports `epirange()` and defaults to all ("*") weeks. - Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form + 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") @@ -105,7 +105,7 @@ def pub_covid_hosp_facility_lookup( Obtains unique identifiers and other metadata for COVID hospitalization facilities of interest. This is a companion endpoint to the - `pub_covid_hosp_facility` endpoint. + :meth:`pub_covid_hosp_facility` endpoint. Only one location argument needs to be specified. Combinations of the arguments are not currently supported. @@ -161,7 +161,7 @@ def pub_covid_hosp_facility( 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 `pub_covid_hosp_facility_lookup` can be + 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 @@ -172,11 +172,11 @@ def pub_covid_hosp_facility( 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 `epirange()` and defaults to all ("*") weeks. + 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` objects, they will be converted to the starting day of the week. + If provided as ``Week``, they will be converted to the starting day of the week. publication_dates : EpiRangeParam, optional - Publication dates to fetch. Supports `epirange()`. Format as YYYY-MM-DD (string or numeric). + 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") @@ -343,11 +343,11 @@ def pub_covid_hosp_state_timeseries( 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 `epirange()` and defaults to all ("*") dates. - Format as `epirange(start, end)`, where start and end are of the form YYYYMMDD + 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 `epirange()`. Format as YYYYMMDD. + 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. @@ -450,7 +450,7 @@ def pub_covidcast_meta(self) -> CALL_TYPE: Returns ------- CALL_TYPE - A `EpiDataCall` object containing the following information: + A ``EpiDataCall`` object containing the following information: ``data_source`` Data source name. @@ -478,7 +478,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`` @@ -568,18 +568,18 @@ def pub_covidcast( or defaults to all locations ("*"). See `Covidcast Geography `__. time_values : EpiRangeParam - Temporal points to fetch. Supports `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`. + 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`. + Mutually exclusive with ``issues`` and ``lag``. issues : EpiRangeParam, optional Range or list of issue dates to fetch. - Mutually exclusive with `as_of` and `lag`. + 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`. + 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.") @@ -639,8 +639,8 @@ def pub_dengue_nowcast(self, locations: StringParam, epiweeks: EpiRangeParam = " 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 `epirange()` and defaults to all ("*") weeks. - Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form + 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") @@ -678,8 +678,8 @@ def pvt_dengue_sensors( List of countries in the Americas to fetch. See `Countries and Territories in the Americas `_. epiweeks : EpiRangeParam - Epiweeks to fetch. Supports `epirange()` and defaults to all ("*") weeks. - Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form + 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") @@ -714,24 +714,21 @@ def pub_ecdc_ili( Obtain information on influenza-like-illness from the European Centre for Disease Prevention and Control. - The list of location argument can be found in - . - Parameters ---------- regions : StringParam List of European countries to fetch. See `European Countries `_. epiweeks : EpiRangeParam - Epiweeks to fetch. Supports `epirange()` and defaults to all ("*") weeks. - Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form + 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`. + 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`. + Mutually exclusive with ``issues``. """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") @@ -767,24 +764,21 @@ def pub_flusurv( See also . - The list of location argument can be found in - . - Parameters ---------- locations : StringParam List of locations to fetch. See `FluSurv Locations `_. epiweeks : EpiRangeParam - Epiweeks to fetch. Supports `epirange()` and defaults to all ("*") weeks. - Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form + 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`. + Mutually exclusive with ``lag``. lag : int, optional Number of days between the observation and its publication. - Mutually exclusive with `issues`. + Mutually exclusive with ``issues``. """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") @@ -848,24 +842,21 @@ def pub_fluview_clinical( API docs: - The list of location argument can be found in - . - Parameters ---------- regions : StringParam List of regions to fetch. - See `HHS Regions `_. + See `US Regions and States `__. epiweeks : EpiRangeParam, default "*" - Epiweeks to fetch. Supports `epirange()` and defaults to all ("*") weeks. - Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form + 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`. + 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`. + Mutually exclusive with ``issues``. """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") @@ -929,17 +920,18 @@ def pub_fluview( ---------- regions : StringParam List of regions to fetch. - See `Geographic Codes `__. + See `US Regions and States `__ + and `FluView Cities `__. epiweeks : EpiRangeParam - Epiweeks to fetch. Supports `epirange()` and defaults to all ("*") weeks. - Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form + 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`. + 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`. + Mutually exclusive with ``issues``. auth : str, optional Private API key. """ @@ -992,8 +984,8 @@ def pub_gft(self, locations: StringParam, epiweeks: EpiRangeParam = "*") -> CALL List of locations to fetch. See `Geographic Codes `__. epiweeks : EpiRangeParam - Epiweeks to fetch. Supports `epirange()` and defaults to all ("*") weeks. - Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form + 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") @@ -1029,8 +1021,8 @@ def pvt_ght( List of locations to fetch. See `Geographic Codes `__. epiweeks : EpiRangeParam, default "*" - Epiweeks to fetch. Supports `epirange()` and defaults to all ("*") weeks. - Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form + 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. @@ -1077,15 +1069,15 @@ def pub_kcdc_ili( List of regions to fetch. See `Republic of Korea `_. epiweeks : EpiRangeParam - Epiweeks to fetch. Supports `epirange()` and defaults to all ("*") weeks. - Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form + 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`. + Mutually exclusive with ``lag``. lag : int, optional Number of days between the observation and its publication. - Mutually exclusive with `issues`. + Mutually exclusive with ``issues``. """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") @@ -1145,8 +1137,8 @@ def pub_nidss_dengue(self, locations: StringParam, epiweeks: EpiRangeParam = "*" List of Taiwan locations to fetch. See `Taiwan Locations `_. epiweeks : EpiRangeParam - Epiweeks to fetch. Supports `epirange()` and defaults to all ("*") weeks. - Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form + 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") @@ -1178,15 +1170,15 @@ def pub_nidss_flu( List of Taiwan locations to fetch. See `Taiwan Locations `_. epiweeks : EpiRangeParam - Epiweeks to fetch. Supports `epirange()` and defaults to all ("*") weeks. - Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form + 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`. + Mutually exclusive with ``lag``. lag : int, optional Number of days between the observation and its publication. - Mutually exclusive with `issues`. + Mutually exclusive with ``issues``. """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") @@ -1223,8 +1215,8 @@ def pvt_norostat(self, auth: str, location: str, epiweeks: EpiRangeParam = "*") 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 `epirange()` and defaults to all ("*") weeks. - Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form + 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") @@ -1250,8 +1242,8 @@ def pub_nowcast(self, locations: StringParam, epiweeks: EpiRangeParam = "*") -> List of locations to fetch. See `Geographic Codes `__. epiweeks : EpiRangeParam - Epiweeks to fetch. Supports `epirange()` and defaults to all ("*") weeks. - Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form + 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") @@ -1284,15 +1276,15 @@ def pub_paho_dengue( List of American countries and territories to fetch. See `Countries and Territories in the Americas `__. epiweeks : EpiRangeParam - Epiweeks to fetch. Supports `epirange()` and defaults to all ("*") weeks. - Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form + 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`. + Mutually exclusive with ``lag``. lag : int, optional Number of days between the observation and its publication. - Mutually exclusive with `issues`. + Mutually exclusive with ``issues``. """ epiweeks = get_wildcard_equivalent_dates(epiweeks, "week") @@ -1332,8 +1324,8 @@ def pvt_quidel(self, auth: str, locations: StringParam, epiweeks: EpiRangeParam List of locations to fetch. See `Geographic Codes `__. epiweeks : EpiRangeParam - Epiweeks to fetch. Supports `epirange()` and defaults to all ("*") weeks. - Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form + 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") @@ -1372,8 +1364,8 @@ def pvt_sensors( List of locations to fetch. See `Geographic Codes `__. epiweeks : EpiRangeParam - Epiweeks to fetch. Supports `epirange()` and defaults to all ("*") weeks. - Format as `epirange(startweek, endweek)`, where startweek and endweek are of the form + 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") @@ -1417,9 +1409,9 @@ def pvt_twitter( time_type : Literal["day", "week"] The temporal resolution to use ("day" or "week"). time_values : EpiRangeParam, default "*" - Temporal points to fetch. Supports `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`. + 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 @@ -1473,9 +1465,9 @@ def pub_wiki( time_type : Literal["day", "week"] The temporal resolution to use ("day" or "week"). time_values : EpiRangeParam, default "*" - Temporal points to fetch. Supports `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`. + 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" From 6711fd92c05b8f1d96479c8ddb9365d716d93dd1 Mon Sep 17 00:00:00 2001 From: JavierMtzRdz Date: Thu, 5 Feb 2026 14:52:37 -0800 Subject: [PATCH 28/30] docs: update notebooks to match updates on epidatr/pull/324 --- docs/getting_started.ipynb | 63 ++++- docs/signal_discovery.ipynb | 525 ++++++++++++++++++++++++++++++++++++ docs/versioned_data.ipynb | 34 ++- 3 files changed, 618 insertions(+), 4 deletions(-) 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/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, From 789b427006ec69e123218066e85d04a5aa85c821 Mon Sep 17 00:00:00 2001 From: JavierMtzRdz Date: Thu, 5 Feb 2026 15:54:42 -0800 Subject: [PATCH 29/30] docs: remove fluview duplicated location link --- epidatpy/_endpoints.py | 3 --- 1 file changed, 3 deletions(-) diff --git a/epidatpy/_endpoints.py b/epidatpy/_endpoints.py index 80eb69c..94c9271 100644 --- a/epidatpy/_endpoints.py +++ b/epidatpy/_endpoints.py @@ -913,9 +913,6 @@ def pub_fluview( See also . - The full list of location inputs can be accessed at - . - Parameters ---------- regions : StringParam From e7ed7c250ab52c641fa23f65c15f1a2c27ce1cfd Mon Sep 17 00:00:00 2001 From: JavierMtzRdz Date: Thu, 5 Feb 2026 22:44:14 -0800 Subject: [PATCH 30/30] docs: correct lint formatting errors --- docs/epidatpy.rst | 4 +-- docs/index.rst | 2 +- epidatpy/_endpoints.py | 58 ++++++++++++++++++++++++++++-------------- 3 files changed, 42 insertions(+), 22 deletions(-) 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/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/epidatpy/_endpoints.py b/epidatpy/_endpoints.py index 94c9271..db98c5b 100644 --- a/epidatpy/_endpoints.py +++ b/epidatpy/_endpoints.py @@ -172,7 +172,8 @@ def pub_covid_hosp_facility( 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. + 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 @@ -612,7 +613,8 @@ def pub_delphi(self, system: str, epiweek: Union[int, str]) -> CALL_TYPE: ---------- system : str The name of the forecast system. - See `Forecasting Systems `_. + See `Forecasting Systems + `_. epiweek : Union[int, str] Epiweek to fetch. Does not support multiple dates. Make separate calls to fetch data for multiple epiweeks. @@ -637,7 +639,8 @@ def pub_dengue_nowcast(self, locations: StringParam, epiweeks: EpiRangeParam = " ---------- locations : StringParam Geographic locations to return. Supports a single string or a sequence of strings. - See `Countries and Territories in the Americas `__. + 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 @@ -673,10 +676,12 @@ def pvt_dengue_sensors( Private API key. names : StringParam Sensor names to fetch. - See `Dengue Sensors Indicators `__. + See `Dengue Sensors Indicators + `__. locations : StringParam List of countries in the Americas to fetch. - See `Countries and Territories in the Americas `_. + 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 @@ -718,7 +723,8 @@ def pub_ecdc_ili( ---------- regions : StringParam List of European countries to fetch. - See `European Countries `_. + 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 @@ -768,7 +774,8 @@ def pub_flusurv( ---------- locations : StringParam List of locations to fetch. - See `FluSurv Locations `_. + 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 @@ -846,7 +853,8 @@ def pub_fluview_clinical( ---------- regions : StringParam List of regions to fetch. - See `US Regions and States `__. + 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 @@ -917,8 +925,10 @@ def pub_fluview( ---------- regions : StringParam List of regions to fetch. - See `US Regions and States `__ - and `FluView Cities `__. + 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 @@ -979,7 +989,8 @@ def pub_gft(self, locations: StringParam, epiweeks: EpiRangeParam = "*") -> CALL ---------- locations : StringParam List of locations to fetch. - See `Geographic Codes `__. + 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 @@ -1016,7 +1027,8 @@ def pvt_ght( Private API key. locations : StringParam List of locations to fetch. - See `Geographic Codes `__. + 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 @@ -1064,7 +1076,8 @@ def pub_kcdc_ili( ---------- regions : StringParam List of regions to fetch. - See `Republic of Korea `_. + 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 @@ -1132,7 +1145,8 @@ def pub_nidss_dengue(self, locations: StringParam, epiweeks: EpiRangeParam = "*" ---------- locations : StringParam List of Taiwan locations to fetch. - See `Taiwan Locations `_. + 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 @@ -1165,7 +1179,8 @@ def pub_nidss_flu( ---------- regions : StringParam List of Taiwan locations to fetch. - See `Taiwan Locations `_. + 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 @@ -1237,7 +1252,8 @@ def pub_nowcast(self, locations: StringParam, epiweeks: EpiRangeParam = "*") -> ---------- locations : StringParam List of locations to fetch. - See `Geographic Codes `__. + 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 @@ -1271,7 +1287,9 @@ def pub_paho_dengue( ---------- regions : StringParam List of American countries and territories to fetch. - See `Countries and Territories in the Americas `__. + 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 @@ -1319,7 +1337,8 @@ def pvt_quidel(self, auth: str, locations: StringParam, epiweeks: EpiRangeParam Private API key. locations : StringParam List of locations to fetch. - See `Geographic Codes `__. + 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 @@ -1458,7 +1477,8 @@ def pub_wiki( ---------- articles : StringParam The Wikipedia article(s) to fetch. Supports a single string or a sequence of strings. - See `Available Articles `_. + See `Available Articles + `_. time_type : Literal["day", "week"] The temporal resolution to use ("day" or "week"). time_values : EpiRangeParam, default "*"