From c484af3870b7ff5a722cd987f2aaa9fc31082d82 Mon Sep 17 00:00:00 2001 From: cheginit Date: Thu, 27 May 2021 01:02:37 -0500 Subject: [PATCH] DOC: Add async_retriever and more example notebooks openjournals/joss-reviews#3175 --- .../async_retriever/async_retriever/index.rst | 50 +++++ docs/source/autoapi/async_retriever/index.rst | 20 ++ docs/source/autoapi/index.rst | 107 ++++++--- docs/source/autoapi/py3dep/cli/index.rst | 58 +++++ docs/source/autoapi/py3dep/index.rst | 1 + docs/source/autoapi/py3dep/py3dep/index.rst | 8 +- docs/source/autoapi/pydaymet/cli/index.rst | 51 +++++ docs/source/autoapi/pydaymet/core/index.rst | 122 +++++++++++ docs/source/autoapi/pydaymet/index.rst | 2 + .../autoapi/pydaymet/pydaymet/index.rst | 204 ++++-------------- .../autoapi/pygeohydro/pygeohydro/index.rst | 90 +++----- docs/source/autoapi/pygeoogc/core/index.rst | 2 +- .../autoapi/pygeoogc/pygeoogc/index.rst | 2 +- docs/source/autoapi/pygeoogc/utils/index.rst | 25 +-- docs/source/autoapi/pynhd/pynhd/index.rst | 49 ++++- docs/source/conf.py | 58 ++++- docs/source/getting_started.rst | 75 +++++-- docs/source/index.rst | 4 +- docs/source/notebooks/aridity.nblink | 1 + docs/source/notebooks/ndvi.nblink | 1 + docs/source/notebooks/noaa.nblink | 1 + docs/source/notebooks/us_coasts.nblink | 1 + 22 files changed, 628 insertions(+), 304 deletions(-) create mode 100644 docs/source/autoapi/async_retriever/async_retriever/index.rst create mode 100644 docs/source/autoapi/async_retriever/index.rst create mode 100644 docs/source/autoapi/py3dep/cli/index.rst create mode 100644 docs/source/autoapi/pydaymet/cli/index.rst create mode 100644 docs/source/autoapi/pydaymet/core/index.rst create mode 100644 docs/source/notebooks/aridity.nblink create mode 100644 docs/source/notebooks/ndvi.nblink create mode 100644 docs/source/notebooks/noaa.nblink create mode 100644 docs/source/notebooks/us_coasts.nblink diff --git a/docs/source/autoapi/async_retriever/async_retriever/index.rst b/docs/source/autoapi/async_retriever/async_retriever/index.rst new file mode 100644 index 0000000..a984b64 --- /dev/null +++ b/docs/source/autoapi/async_retriever/async_retriever/index.rst @@ -0,0 +1,50 @@ +:mod:`async_retriever.async_retriever` +====================================== + +.. py:module:: async_retriever.async_retriever + +.. autoapi-nested-parse:: + + Core async functions. + + + +Module Contents +--------------- + +.. function:: retrieve(urls: List[str], read: str, request_kwds: Optional[List[Dict[str, Any]]] = None, request: str = 'GET', max_workers: int = 8, cache_name: Optional[Union[Path, str]] = None) -> List[Union[str, Dict[str, Any], bytes]] + + Send async requests. + + This function is based on + `this `__ + script. + + :Parameters: * **urls** (:class:`list` of :class:`str`) -- A list of URLs. + * **read** (:class:`str`) -- The method for returning the request; binary, json, and text. + * **request_kwds** (:class:`list` of :class:`dict`, *optional*) -- A list of requests kwds corresponding to input URLs (1 on 1 mapping), defaults to None. + For example, [{"params": {...}, "headers": {...}}, ...]. + * **request** (:class:`str`, *optional*) -- The request type; GET or POST, defaults to GET. + * **max_workers** (:class:`int`, *optional*) -- The maximum number of async processes, defaults to 8. + * **cache_name** (:class:`str`, *optional*) -- Path to a file for caching the session, default to None which uses a file + called aiohttp_cache.sqlite under the systems' cache directory: ~/.cache + for Linux and MacOS, and %Temp% for Windows. + + :returns: :class:`list` -- A list of responses which are not in the order of input requests. + + .. rubric:: Examples + + >>> import async_retriever as ar + >>> stations = ["01646500", "08072300", "11073495"] + >>> base = "https://waterservices.usgs.gov/nwis/site" + >>> urls, kwds = zip( + ... *[ + ... (base, {"params": {"format": "rdb", "sites": s, "siteStatus": "all"}}) + ... for s in stations + ... ] + ... ) + >>> resp = ar.retrieve(urls, "text", request_kwds=kwds) + >>> resp[0].split('\n')[-2].split('\t')[1] + '01646500' + + diff --git a/docs/source/autoapi/async_retriever/index.rst b/docs/source/autoapi/async_retriever/index.rst new file mode 100644 index 0000000..9ce6d83 --- /dev/null +++ b/docs/source/autoapi/async_retriever/index.rst @@ -0,0 +1,20 @@ +:mod:`async_retriever` +====================== + +.. py:module:: async_retriever + +.. autoapi-nested-parse:: + + Top-level package. + + + +Submodules +---------- +.. toctree:: + :titlesonly: + :maxdepth: 1 + + async_retriever/index.rst + + diff --git a/docs/source/autoapi/index.rst b/docs/source/autoapi/index.rst index 6d2ac0b..c596acc 100644 --- a/docs/source/autoapi/index.rst +++ b/docs/source/autoapi/index.rst @@ -1,49 +1,108 @@ -Reference -========= +API References +============== -Versions --------- +.. panels:: + :container: container-lg pb-3 + :body: text-center + :column: col-lg-3 col-md-3 col-sm-4 col-xs-6 p-2 -- |pygeoogc| -- |pygeoutils| -- |pynhd| -- |pygeohydro| -- |py3dep| -- |pydaymet| + .. link-button:: /autoapi/pynhd/index + :type: ref + :text: PyNHD + :classes: stretched-link -APIs ----- + |pynhd| + + --- + + .. link-button:: /autoapi/pygeohydro/index + :type: ref + :text: PyGeoHydro + :classes: stretched-link + + |pygeohydro| + + --- + + .. link-button:: /autoapi/py3dep/index + :type: ref + :text: Py3DEP + :classes: stretched-link + + |py3dep| + + --- + + .. link-button:: /autoapi/pydaymet/index + :type: ref + :text: PyDaymet + :classes: stretched-link + + |pydaymet| + + --- + + .. link-button:: /autoapi/pygeoogc/index + :type: ref + :text: PyGeoOGC + :classes: stretched-link + + |pygeoogc| + + --- + + .. link-button:: /autoapi/pygeoutils/index + :type: ref + :text: PyGeoUtils + :classes: stretched-link + + |pygeoutils| + + --- + + .. link-button:: /autoapi/async_retriever/index + :type: ref + :text: AsyncRetriever + :classes: stretched-link + + |async| .. toctree:: :titlesonly: + :hidden: - /autoapi/pygeoogc/index - /autoapi/pygeoutils/index - /autoapi/pynhd/index - /autoapi/py3dep/index - /autoapi/pygeohydro/index - /autoapi/pydaymet/index + PyNHD + PyGeoHydro + Py3DEP + PyDaymet + PyGeoOGC + PyGeoUtils + AsyncRetriever -.. |pygeohydro| image:: https://img.shields.io/pypi/v/pygeohydro?label=PyGeoHydro&color=blue +.. |pygeohydro| image:: https://img.shields.io/pypi/v/pygeohydro?label=%20&color=blue :target: https://github.com/cheginit/pygeohydro :alt: PyPi Version -.. |pygeoogc| image:: https://img.shields.io/pypi/v/pygeoogc?label=PyGeoOGC&color=blue +.. |pygeoogc| image:: https://img.shields.io/pypi/v/pygeoogc?label=%20&color=blue :target: https://github.com/cheginit/pygeoogc :alt: PyPi Version -.. |pygeoutils| image:: https://img.shields.io/pypi/v/pygeoutils?label=PyGeoUtils&color=blue +.. |pygeoutils| image:: https://img.shields.io/pypi/v/pygeoutils?label=%20&color=blue :target: https://github.com/cheginit/pygeoutils :alt: PyPi Version -.. |pynhd| image:: https://img.shields.io/pypi/v/pynhd?label=PyNHD&color=blue +.. |pynhd| image:: https://img.shields.io/pypi/v/pynhd?label=%20&color=blue :target: https://github.com/cheginit/pynhd :alt: PyPi Version -.. |py3dep| image:: https://img.shields.io/pypi/v/py3dep?label=Py3DEP&color=blue +.. |py3dep| image:: https://img.shields.io/pypi/v/py3dep?label=%20&color=blue :target: https://github.com/cheginit/py3dep :alt: PyPi Version -.. |pydaymet| image:: https://img.shields.io/pypi/v/pydaymet?label=PyDaymet&color=blue +.. |pydaymet| image:: https://img.shields.io/pypi/v/pydaymet?label=%20&color=blue :target: https://github.com/cheginit/pydaymet :alt: PyPi Version + +.. |async| image:: https://img.shields.io/pypi/v/async_retriever?label=%20&color=blue + :target: https://github.com/cheginit/async_retriever + :alt: PyPi Version diff --git a/docs/source/autoapi/py3dep/cli/index.rst b/docs/source/autoapi/py3dep/cli/index.rst new file mode 100644 index 0000000..9e4e747 --- /dev/null +++ b/docs/source/autoapi/py3dep/cli/index.rst @@ -0,0 +1,58 @@ +:mod:`py3dep.cli` +================= + +.. py:module:: py3dep.cli + +.. autoapi-nested-parse:: + + Command-line interface for Py3DEP. + + + +Module Contents +--------------- + +.. function:: from_coords(coords: List[Tuple[float, float]], crs: str, csv_path: Union[str, Path]) -> None + + Get elevations of a set of coordinates in meter from airmap. + + +.. function:: from_geometry(layer: str, geometry: Union[Polygon, MultiPolygon, Tuple[float, float, float, float]], res: float, crs: str, nc_path: Union[str, Path]) -> None + + Get topographic data from 3DEP for a geometry. + + +.. function:: get_target_df(tdf: Union[pd.DataFrame, gpd.GeoDataFrame], req_cols: List[str]) -> Union[pd.DataFrame, gpd.GeoDataFrame] + + Check if all required columns exists in the dataframe. + + It also re-orders the columns based on req_cols order. + + +.. function:: main(target: Path, target_type: str, crs: str, layer: Optional[str] = None, save_dir: Union[str, Path] = 'topo_3dep') + + Retrieve topographic data within geometries or elevations for a list of coordinates. + + TARGET: Path to a geospatial file (any file that geopandas.read_file can open) or a csv file. + + The geospatial file should have three columns: + + - id: Feature identifiers that py3dep uses as the output netcdf/csv filenames. + + - res: Target resolution in meters. + + - geometry: A Polygon or MultiPloygon. + + The csv file should have two column: x and y. + + TARGET_TYPE: Type of input file: "coords" for csv and "geometry" for geospatial. + + CRS: CRS of the input data. + + Examples: + + $ py3dep ny_coords.csv coords epsg:4326 + + $ py3dep ny_geom.gpkg geometry epsg:3857 --layer "Slope Map" + + diff --git a/docs/source/autoapi/py3dep/index.rst b/docs/source/autoapi/py3dep/index.rst index d60a3c5..1e91252 100644 --- a/docs/source/autoapi/py3dep/index.rst +++ b/docs/source/autoapi/py3dep/index.rst @@ -15,6 +15,7 @@ Submodules :titlesonly: :maxdepth: 1 + cli/index.rst py3dep/index.rst diff --git a/docs/source/autoapi/py3dep/py3dep/index.rst b/docs/source/autoapi/py3dep/py3dep/index.rst index 2500033..741602f 100644 --- a/docs/source/autoapi/py3dep/py3dep/index.rst +++ b/docs/source/autoapi/py3dep/py3dep/index.rst @@ -14,7 +14,7 @@ Module Contents .. function:: deg2mpm(da: xr.DataArray) -> xr.DataArray - Convert ``xarray.Data[Array,set]`` from degree to meter/meter. + Convert slope from degree to meter/meter. .. function:: elevation_bycoords(coords: List[Tuple[float, float]], crs: str = DEF_CRS) -> List[int] @@ -42,12 +42,13 @@ Module Contents * **dim_names** (:class:`tuple`) -- A tuple of length two containing the coordinate names, defaults to ["x", "y"] * **resampling** (:class:`rasterio.warp.Resampling`) -- The reasmpling method to use if the input crs is not in the supported 3DEP's CRS list which are epsg:4326 and epsg:3857. It defaults to bilinear. - The available methods can be found `here `__ + The available methods can be found + `here `__ :returns: :class:`xarray.DataArray` -- An data array with name elevation and the given dim names. -.. function:: get_map(layers: Union[str, List[str]], geometry: Union[Polygon, Tuple[float, float, float, float]], resolution: float, geo_crs: str = DEF_CRS, crs: str = DEF_CRS, output_dir: Optional[Union[str, Path]] = None) -> Dict[str, bytes] +.. function:: get_map(layers: Union[str, List[str]], geometry: Union[Polygon, MultiPolygon, Tuple[float, float, float, float]], resolution: float, geo_crs: str = DEF_CRS, crs: str = DEF_CRS) -> Union[xr.DataArray, xr.Dataset] Access to `3DEP `__ service. @@ -75,7 +76,6 @@ Module Contents epsg:4326. * **crs** (:class:`str`, *optional*) -- The spatial reference system to be used for requesting the data, defaults to epsg:4326. - * **output_dir** (:class:`str` or :class:`~~pathlib.Path`, *optional*) -- The output directory to also save the map as GTiff file(s), defaults to None. :returns: :class:`dict` -- A dict where the keys are the layer name and values are the returned response from the WMS service as bytes. You can use ``utils.create_dataset`` function diff --git a/docs/source/autoapi/pydaymet/cli/index.rst b/docs/source/autoapi/pydaymet/cli/index.rst new file mode 100644 index 0000000..b6b3e9e --- /dev/null +++ b/docs/source/autoapi/pydaymet/cli/index.rst @@ -0,0 +1,51 @@ +:mod:`pydaymet.cli` +=================== + +.. py:module:: pydaymet.cli + +.. autoapi-nested-parse:: + + Command-line interface for PyDaymet. + + + +Module Contents +--------------- + +.. function:: get_target_df(tdf: Union[pd.DataFrame, gpd.GeoDataFrame], req_cols: List[str]) -> Union[pd.DataFrame, gpd.GeoDataFrame] + + Check if all required columns exists in the dataframe. + + It also re-orders the columns based on req_cols order. + + +.. function:: main(target: Path, target_type: str, crs: str, variables: Optional[Union[List[str], str]] = None, time_scale: str = 'daily', pet: bool = False, save_dir: Union[str, Path] = 'clm_daymet') + + Retrieve cliamte data within geometries or elevations for a list of coordinates. + + TARGET: Path to a geospatial file (any file that geopandas.read_file can open) or a csv file. + + The input files should have three columns: + + - id: Feature identifiers that daymet uses as the output netcdf filenames. + + - start: Starting time. + + - end: Ending time. + + - region: Target region (na for CONUS, hi for Hawaii, and pr for Puerto Rico. + + If target_type is geometry, an additional geometry column is required. + If it is coords, two additional columns are needed: x and y. + + TARGET_TYPE: Type of input file: "coords" for csv and "geometry" for geospatial. + + CRS: CRS of the input data. + + Examples: + + $ pydaymet ny_coords.csv coords epsg:4326 -v prcp -v tmin -p -t monthly + + $ pydaymet ny_geom.gpkg geometry epsg:3857 -v prcp + + diff --git a/docs/source/autoapi/pydaymet/core/index.rst b/docs/source/autoapi/pydaymet/core/index.rst new file mode 100644 index 0000000..56931c3 --- /dev/null +++ b/docs/source/autoapi/pydaymet/core/index.rst @@ -0,0 +1,122 @@ +:mod:`pydaymet.core` +==================== + +.. py:module:: pydaymet.core + +.. autoapi-nested-parse:: + + Core class for the Daymet functions. + + + +Module Contents +--------------- + +.. py:class:: Daymet(variables: Optional[Union[Iterable[str], str]] = None, pet: bool = False, time_scale: str = 'daily', region: str = 'na') + + Base class for Daymet requests. + + :Parameters: * **variables** (:class:`str` or :class:`list` or :class:`tuple`, *optional*) -- List of variables to be downloaded. The acceptable variables are: + ``tmin``, ``tmax``, ``prcp``, ``srad``, ``vp``, ``swe``, ``dayl`` + Descriptions can be found `here `__. + Defaults to None i.e., all the variables are downloaded. + * **pet** (:class:`bool`, *optional*) -- Whether to compute evapotranspiration based on + `UN-FAO 56 paper `__. + The default is False + * **time_scale** (:class:`str`, *optional*) -- Data time scale which can be daily, monthly (monthly summaries), + or annual (annual summaries). Defaults to daily. + * **region** (:class:`str`, *optional*) -- Region in the US, defaults to na. Acceptable values are: + * na: Continental North America + * hi: Hawaii + * pr: Puerto Rico + + .. method:: check_dates(dates: Union[Tuple[str, str], Union[int, List[int]]]) -> None + :staticmethod: + + Check if input dates are in correct format and valid. + + + .. method:: check_input_validity(inp: str, valid_list: Iterable[str]) -> str + :staticmethod: + + Check the validity of input based on a list of valid options. + + + .. method:: dates_todict(dates: Tuple[str, str]) -> Dict[str, str] + :staticmethod: + + Set dates by start and end dates as a tuple, (start, end). + + + .. method:: dates_tolist(self, dates: Tuple[str, str]) -> List[Tuple[pd.DatetimeIndex, pd.DatetimeIndex]] + + Correct dates for Daymet accounting for leap years. + + Daymet doesn't account for leap years and removes Dec 31 when + it's leap year. + + :Parameters: **dates** (:class:`tuple`) -- Target start and end dates. + + :returns: :class:`list` -- All the dates in the Daymet database within the provided date range. + + + .. method:: pet_bycoords(clm_df: pd.DataFrame, coords: Tuple[float, float], crs: str = DEF_CRS, alt_unit: bool = False) -> pd.DataFrame + :staticmethod: + + Compute Potential EvapoTranspiration using Daymet dataset for a single location. + + .. rubric:: Notes + + The method is based on + `FAO Penman-Monteith equation `__. + Moreover, we assume that soil heat flux density is zero and wind speed at 2 m height + is 2 m/s. The following variables are required: + tmin (deg c), tmax (deg c), lat, lon, vp (Pa), srad (W/m2), dayl (s/day) + The computed PET's unit is mm/day. + + :Parameters: * **clm_df** (:class:`~pandas.DataFrame`) -- A dataframe with columns named as follows: + ``tmin (deg c)``, ``tmax (deg c)``, ``vp (Pa)``, ``srad (W/m^2)``, ``dayl (s)`` + * **coords** (:class:`tuple` of :class:`floats`) -- Coordinates of the daymet data location as a tuple, (x, y). + * **crs** (:class:`str`, *optional*) -- The spatial reference of the input coordinate, defaults to epsg:4326 + * **alt_unit** (:class:`str`, *optional*) -- Whether to use alternative units rather than the official ones, defaults to False. + + :returns: :class:`pandas.DataFrame` -- The input DataFrame with an additional column named ``pet (mm/day)`` + + + .. method:: pet_bygrid(clm_ds: xr.Dataset) -> xr.Dataset + :staticmethod: + + Compute Potential EvapoTranspiration using Daymet dataset. + + The method is based on + `FAO Penman-Monteith equation `__. + Moreover, we assume that soil heat flux density is zero and wind speed at 2 m height + is 2 m/s. The following variables are required: + tmin (deg c), tmax (deg c), lat, lon, vp (Pa), srad (W/m2), dayl (s/day) + The computed PET's unit is mm/day. + + :Parameters: **clm_ds** (:class:`xarray.DataArray`) -- The dataset should include the following variables: + ``tmin``, ``tmax``, ``lat``, ``lon``, ``vp``, ``srad``, ``dayl`` + + :returns: :class:`xarray.DataArray` -- The input dataset with an additional variable called ``pet``. + + + .. method:: years_todict(years: Union[List[int], int]) -> Dict[str, str] + :staticmethod: + + Set date by list of year(s). + + + .. method:: years_tolist(self, years: Union[List[int], int]) -> List[Tuple[pd.DatetimeIndex, pd.DatetimeIndex]] + + Correct dates for Daymet accounting for leap years. + + Daymet doesn't account for leap years and removes Dec 31 when + it's leap year. + + :Parameters: **years** (:class:`list`) -- A list of target years. + + :returns: :class:`list` -- All the dates in the Daymet database within the provided date range. + + + diff --git a/docs/source/autoapi/pydaymet/index.rst b/docs/source/autoapi/pydaymet/index.rst index b38ea59..70c21bf 100644 --- a/docs/source/autoapi/pydaymet/index.rst +++ b/docs/source/autoapi/pydaymet/index.rst @@ -15,6 +15,8 @@ Submodules :titlesonly: :maxdepth: 1 + cli/index.rst + core/index.rst pydaymet/index.rst diff --git a/docs/source/autoapi/pydaymet/pydaymet/index.rst b/docs/source/autoapi/pydaymet/pydaymet/index.rst index 58059d5..b9062db 100644 --- a/docs/source/autoapi/pydaymet/pydaymet/index.rst +++ b/docs/source/autoapi/pydaymet/pydaymet/index.rst @@ -12,118 +12,7 @@ Module Contents --------------- -.. py:class:: Daymet(variables: Optional[Union[List[str], str]] = None, pet: bool = False, time_scale: str = 'daily') - - Base class for Daymet requests. - - :Parameters: * **variables** (:class:`str` or :class:`list` or :class:`tuple`, *optional*) -- List of variables to be downloaded. The acceptable variables are: - ``tmin``, ``tmax``, ``prcp``, ``srad``, ``vp``, ``swe``, ``dayl`` - Descriptions can be found `here `__. - Defaults to None i.e., all the variables are downloaded. - * **pet** (:class:`bool`, *optional*) -- Whether to compute evapotranspiration based on - `UN-FAO 56 paper `__. - The default is False - * **time_scale** (:class:`str`, *optional*) -- Data time scale which can be daily, monthly (monthly summaries), - or annual (annual summaries). Defaults to daily. - - .. method:: check_dates(dates: Union[Tuple[str, str], Union[int, List[int]]]) -> None - :staticmethod: - - Check if input dates are in correct format and valid. - - - .. method:: dates_todict(dates: Tuple[str, str]) -> Dict[str, str] - :staticmethod: - - Set dates by start and end dates as a tuple, (start, end). - - - .. method:: dates_tolist(self, dates: Tuple[str, str]) -> List[Tuple[pd.DatetimeIndex, pd.DatetimeIndex]] - - Correct dates for Daymet accounting for leap years. - - Daymet doesn't account for leap years and removes Dec 31 when - it's leap year. - - :Parameters: **dates** (:class:`tuple`) -- Target start and end dates. - - :returns: :class:`list` -- All the dates in the Daymet database within the provided date range. - - - .. method:: pet_bygrid(clm_ds: xr.Dataset) -> xr.Dataset - :staticmethod: - - Compute Potential EvapoTranspiration using Daymet dataset. - - The method is based on `FAO 56 paper `__. - The following variables are required: - tmin (deg c), tmax (deg c), lat, lon, vp (Pa), srad (W/m2), dayl (s/day) - The computed PET's unit is mm/day. - - :Parameters: **clm_ds** (:class:`xarray.DataArray`) -- The dataset should include the following variables: - ``tmin``, ``tmax``, ``lat``, ``lon``, ``vp``, ``srad``, ``dayl`` - - :returns: :class:`xarray.DataArray` -- The input dataset with an additional variable called ``pet``. - - - .. method:: pet_byloc(clm_df: pd.DataFrame, coords: Tuple[float, float], crs: str = DEF_CRS, alt_unit: bool = False) -> pd.DataFrame - :staticmethod: - - Compute Potential EvapoTranspiration using Daymet dataset for a single location. - - The method is based on `FAO-56 `__. - The following variables are required: - tmin (deg c), tmax (deg c), lat, lon, vp (Pa), srad (W/m2), dayl (s/day) - The computed PET's unit is mm/day. - - :Parameters: * **clm_df** (:class:`~pandas.DataFrame`) -- A dataframe with columns named as follows: - ``tmin (deg c)``, ``tmax (deg c)``, ``vp (Pa)``, ``srad (W/m^2)``, ``dayl (s)`` - * **coords** (:class:`tuple` of :class:`floats`) -- Coordinates of the daymet data location as a tuple, (x, y). - * **crs** (:class:`str`, *optional*) -- The spatial reference of the input coordinate, defaults to epsg:4326 - * **alt_unit** (:class:`str`, *optional*) -- Whether to use alternative units rather than the official ones, defaults to False. - - :returns: :class:`pandas.DataFrame` -- The input DataFrame with an additional column named ``pet (mm/day)`` - - - .. method:: years_todict(years: Union[List[int], int]) -> Dict[str, str] - :staticmethod: - - Set date by list of year(s). - - - .. method:: years_tolist(self, years: Union[List[int], int]) -> List[Tuple[pd.DatetimeIndex, pd.DatetimeIndex]] - - Correct dates for Daymet accounting for leap years. - - Daymet doesn't account for leap years and removes Dec 31 when - it's leap year. - - :Parameters: **years** (:class:`list`) -- A list of target years. - - :returns: :class:`list` -- All the dates in the Daymet database within the provided date range. - - - -.. function:: coord_urls(code: int, coord: Tuple[float, float], region: str, variables: List[str], dates: List[Tuple[pd.DatetimeIndex, pd.DatetimeIndex]]) -> Iterator[List[Tuple[str, Dict[str, str]]]] - - Generate an iterable URL list for downloading Daymet data. - - :Parameters: * **code** (:class:`int`) -- Endpoint code which should be one of the following: - * 1840: Daily - * 1855: Monthly average - * 1852: Annual average - * **coord** (:class:`tuple` of :class:`length 2`) -- Coordinates in EPSG:4326 CRS (lon, lat) - * **region** (:class:`str`) -- Region in the US. Acceptable values are: - * na: Continental North America - * hi: Hawaii - * pr: Puerto Rico - * **variables** (:class:`list`) -- A list of Daymet variables - * **dates** (:class:`list`) -- A list of dates - - :returns: :class:`generator` -- An iterator of generated URLs. - - -.. function:: get_bycoords(coords: Tuple[float, float], dates: Union[Tuple[str, str], Union[int, List[int]]], loc_crs: str = DEF_CRS, variables: Optional[List[str]] = None, pet: bool = False, region: str = 'na', time_scale: str = 'daily') -> xr.Dataset +.. function:: get_bycoords(coords: Tuple[float, float], dates: Union[Tuple[str, str], Union[int, List[int]]], crs: str = DEF_CRS, variables: Optional[Union[Iterable[str], str]] = None, pet: bool = False, region: str = 'na', time_scale: str = 'daily') -> xr.Dataset Get point-data from the Daymet database at 1-km resolution. @@ -132,36 +21,46 @@ Module Contents data directly from the server. :Parameters: * **coords** (:class:`tuple`) -- Coordinates of the location of interest as a tuple (lon, lat) - * **dates** (:class:`tuple` or :class:`list`, *optional*) -- Start and end dates as a tuple (start, end) or a list of years [2001, 2010, ...]. - * **loc_crs** (:class:`str`, *optional*) -- The CRS of the input geometry, defaults to epsg:4326. + * **dates** (:class:`tuple` or :class:`list`, *optional*) -- Start and end dates as a tuple (start, end) or a list of years ``[2001, 2010, ...]``. + * **crs** (:class:`str`, *optional*) -- The CRS of the input geometry, defaults to ``"epsg:4326"``. * **variables** (:class:`str` or :class:`list`) -- List of variables to be downloaded. The acceptable variables are: ``tmin``, ``tmax``, ``prcp``, ``srad``, ``vp``, ``swe``, ``dayl`` Descriptions can be found `here `__. * **pet** (:class:`bool`) -- Whether to compute evapotranspiration based on - `UN-FAO 56 paper `__. + `FAO Penman-Monteith equation `__. The default is False - * **region** (:class:`str`, *optional*) -- Region in the US, defaults to na. Acceptable values are: - * na: Continental North America - * hi: Hawaii - * pr: Puerto Rico + * **region** (:class:`str`, *optional*) -- Target region in the US, defaults to ``na``. Acceptable values are: + + * ``na``: Continental North America + * ``hi``: Hawaii + * ``pr``: Puerto Rico * **time_scale** (:class:`str`, *optional*) -- Data time scale which can be daily, monthly (monthly summaries), or annual (annual summaries). Defaults to daily. - :returns: :class:`xarray.Dataset` -- Daily climate data within a geometry + :returns: :class:`pandas.DataFrame` -- Daily climate data for a location. + + .. rubric:: Examples + >>> import pydaymet as daymet + >>> coords = (-1431147.7928, 318483.4618) + >>> dates = ("2000-01-01", "2000-12-31") + >>> clm = daymet.get_bycoords(coords, dates, crs="epsg:3542", pet=True) + >>> clm["pet (mm/day)"].mean() + 4.076187138002121 -.. function:: get_bygeom(geometry: Union[Polygon, MultiPolygon, Tuple[float, float, float, float]], dates: Union[Tuple[str, str], Union[int, List[int]]], geo_crs: str = DEF_CRS, variables: Optional[List[str]] = None, pet: bool = False, region: str = 'na', time_scale: str = 'daily') -> xr.Dataset + +.. function:: get_bygeom(geometry: Union[Polygon, MultiPolygon, Tuple[float, float, float, float]], dates: Union[Tuple[str, str], Union[int, List[int]]], crs: str = DEF_CRS, variables: Optional[Union[Iterable[str], str]] = None, pet: bool = False, region: str = 'na', time_scale: str = 'daily') -> xr.Dataset Get gridded data from the Daymet database at 1-km resolution. :Parameters: * **geometry** (:class:`Polygon`, :class:`MultiPolygon`, or :class:`bbox`) -- The geometry of the region of interest. * **dates** (:class:`tuple` or :class:`list`, *optional*) -- Start and end dates as a tuple (start, end) or a list of years [2001, 2010, ...]. - * **geo_crs** (:class:`str`, *optional*) -- The CRS of the input geometry, defaults to epsg:4326. + * **crs** (:class:`str`, *optional*) -- The CRS of the input geometry, defaults to epsg:4326. * **variables** (:class:`str` or :class:`list`) -- List of variables to be downloaded. The acceptable variables are: ``tmin``, ``tmax``, ``prcp``, ``srad``, ``vp``, ``swe``, ``dayl`` Descriptions can be found `here `__. * **pet** (:class:`bool`) -- Whether to compute evapotranspiration based on - `UN-FAO 56 paper `__. + `FAO Penman-Monteith equation `__. The default is False * **region** (:class:`str`, *optional*) -- Region in the US, defaults to na. Acceptable values are: * na: Continental North America @@ -170,16 +69,26 @@ Module Contents * **time_scale** (:class:`str`, *optional*) -- Data time scale which can be daily, monthly (monthly average), or annual (annual average). Defaults to daily. - :returns: :class:`xarray.Dataset` -- Daily climate data within a geometry + :returns: :class:`xarray.Dataset` -- Daily climate data within the target geometry. + + .. rubric:: Examples + + >>> from shapely.geometry import Polygon + >>> import pydaymet as daymet + >>> geometry = Polygon( + ... [[-69.77, 45.07], [-69.31, 45.07], [-69.31, 45.45], [-69.77, 45.45], [-69.77, 45.07]] + ... ) + >>> clm = daymet.get_bygeom(geometry, 2010, variables="tmin", time_scale="annual") + >>> clm["tmin"].mean().values + array(1.3613942, dtype=float32) -.. function:: get_byloc(coords: Tuple[float, float], dates: Union[Tuple[str, str], Union[int, List[int]]], crs: str = DEF_CRS, variables: Optional[Union[List[str], str]] = None, pet: bool = False) -> pd.DataFrame +.. function:: get_byloc(coords: Tuple[float, float], dates: Union[Tuple[str, str], Union[int, List[int]]], crs: str = DEF_CRS, variables: Optional[Union[Iterable[str], str]] = None, pet: bool = False) -> pd.DataFrame Get daily climate data from Daymet for a single point. - This function uses Daymet's RESTful service to get the daily - climate data and does not support monthly and annual summaries. - If you want to get the summaries directly use get_bycoords function. + .. deprecated:: 0.9.0 + Please use ``get_bycoords`` instead. This function will be removed in the future. :Parameters: * **coords** (:class:`tuple`) -- Longitude and latitude of the location of interest as a tuple (lon, lat) * **dates** (:class:`tuple` or :class:`list`) -- Either a tuple (start, end) or a list of years [YYYY, ...]. @@ -189,44 +98,9 @@ Module Contents Descriptions can be found `here `__. Defaults to None i.e., all the variables are downloaded. * **pet** (:class:`bool`, *optional*) -- Whether to compute evapotranspiration based on - `UN-FAO 56 paper `__. + `FAO Penman-Monteith equation `__. The default is False - :returns: :class:`pandas.DataFrame` -- Daily climate data for a location - - -.. function:: get_filename(code: int, region: str) -> Dict[int, Callable[[str], str]] - - Generate an iterable URL list for downloading Daymet data. - - :Parameters: * **code** (:class:`int`) -- Endpoint code which should be one of the following: - * 1840: Daily - * 1855: Monthly average - * 1852: Annual average - * **region** (:class:`str`) -- Region in the US. Acceptable values are: - * na: Continental North America - * hi: Hawaii - * pr: Puerto Rico - - :returns: :class:`generator` -- An iterator of generated URLs. - - -.. function:: gridded_urls(code: int, bounds: Tuple[float, float, float, float], region: str, variables: List[str], dates: List[Tuple[pd.DatetimeIndex, pd.DatetimeIndex]]) -> Iterator[Tuple[str, Dict[str, str]]] - - Generate an iterable URL list for downloading Daymet data. - - :Parameters: * **code** (:class:`int`) -- Endpoint code which should be one of the following: - * 1840: Daily - * 1855: Monthly average - * 1852: Annual average - * **bounds** (:class:`tuple` of :class:`length 4`) -- Bounding box (west, south, east, north) - * **region** (:class:`str`) -- Region in the US. Acceptable values are: - * na: Continental North America - * hi: Hawaii - * pr: Puerto Rico - * **variables** (:class:`list`) -- A list of Daymet variables - * **dates** (:class:`list`) -- A list of dates - - :returns: :class:`generator` -- An iterator of generated URLs. + :returns: :class:`pandas.DataFrame` -- Daily climate data for a location. diff --git a/docs/source/autoapi/pygeohydro/pygeohydro/index.rst b/docs/source/autoapi/pygeohydro/pygeohydro/index.rst index 45d57aa..92c5702 100644 --- a/docs/source/autoapi/pygeohydro/pygeohydro/index.rst +++ b/docs/source/autoapi/pygeohydro/pygeohydro/index.rst @@ -28,7 +28,7 @@ Module Contents .. method:: get_xlsx(self) -> io.BytesIO - Get the excel file that containes the dam data. + Get the excel file that contains the dam data. @@ -36,58 +36,26 @@ Module Contents Access NWIS web service. - .. method:: get_info(self, query: Dict[str, str], expanded: bool = False) -> pd.DataFrame - - Get NWIS stations by a list of IDs or within a bounding box. - - Only stations that record(ed) daily streamflow data are returned. - The following columns are included in the dataframe with expanded - set to False: - - ================== ================================== - Name Description - ================== ================================== - site_no Site identification number - station_nm Site name - site_tp_cd Site type - dec_lat_va Decimal latitude - dec_long_va Decimal longitude - coord_acy_cd Latitude-longitude accuracy - dec_coord_datum_cd Decimal Latitude-longitude datum - alt_va Altitude of Gage/land surface - alt_acy_va Altitude accuracy - alt_datum_cd Altitude datum - huc_cd Hydrologic unit code - parm_cd Parameter code - stat_cd Statistical code - ts_id Internal timeseries ID - loc_web_ds Additional measurement description - medium_grp_cd Medium group code - parm_grp_cd Parameter group code - srs_id SRS ID - access_cd Access code - begin_date Begin date - end_date End date - count_nu Record count - hcdn_2009 Whether is in HCDN-2009 stations - ================== ================================== - - :Parameters: * **query** (:class:`dict`) -- A dictionary containing query by IDs or BBOX. Use ``query_byid`` or ``query_bbox`` - class methods to generate the queries. - * **expanded** (:class:`bool`, *optional*) -- Whether to get expanded sit information for example drainage area. - - :returns: :class:`pandas.DataFrame` -- NWIS stations - - - .. method:: get_streamflow(self, station_ids: Union[List[str], str], dates: Tuple[str, str], mmd: bool = False) -> pd.DataFrame - - Get daily streamflow observations from USGS. + .. method:: get_info(self, queries: Union[Dict[str, str], List[Dict[str, str]]], expanded: bool = False) -> pd.DataFrame + + Send multiple queries to USGS Site Web Service. + + :Parameters: * **queries** (:class:`dict` or :class:`list` of :class:`dict`) -- A single or a list of valid queries. + * **expanded** (:class:`bool`, *optional*) -- Whether to get expanded sit information for example drainage area, default to False. + + :returns: :class:`pandas.DataFrame` -- A typed dataframe containing the site information. + + + .. method:: get_streamflow(self, station_ids: Union[Sequence[str], str], dates: Tuple[str, str], mmd: bool = False) -> pd.DataFrame + + Get mean daily streamflow observations from USGS. :Parameters: * **station_ids** (:class:`str`, :class:`list`) -- The gage ID(s) of the USGS station. * **dates** (:class:`tuple`) -- Start and end dates as a tuple (start, end). * **mmd** (:class:`bool`) -- Convert cms to mm/day based on the contributing drainage area of the stations. - :returns: :class:`pandas.DataFrame` -- Streamflow data observations in cubic meter per second (cms) + :returns: :class:`pandas.DataFrame` -- Streamflow data observations in cubic meter per second (cms). The stations that + don't provide mean daily discharge in the target period will be dropped. .. method:: query_bybox(bbox: Tuple[float, float, float, float]) -> Dict[str, str] @@ -96,7 +64,7 @@ Module Contents Generate the geometry keys and values of an ArcGISRESTful query. - .. method:: query_byid(ids: Union[str, List[str]]) -> Dict[str, str] + .. method:: query_byid(ids: Iterable[str]) -> Dict[str, str] :staticmethod: Generate the geometry keys and values of an ArcGISRESTful query. @@ -107,7 +75,7 @@ Module Contents Percentages of the categorical NLCD cover data. - :Parameters: **ds** (:class:`xarray.Dataset`) -- Cover dataarray of a LULC dataset from the `nlcd` function. + :Parameters: **ds** (:class:`xarray.Dataset`) -- Cover DataArray from a LULC Dataset from the ``nlcd`` function. :returns: :class:`dict` -- Statistics of NLCD cover data @@ -118,7 +86,7 @@ Module Contents .. rubric:: Notes - This function downloads a 25 MB `xlsx` file and convert it into a + This function downloads a 25 MB excel file and convert it into a GeoDataFrame. So, your net speed might be a bottleneck. Another bottleneck is data loading since the dataset has more than 91K rows, it might take sometime for Pandas to load the data into memory. @@ -138,17 +106,27 @@ Module Contents letter codes. For example, ``tables.loc[('Core Type', 'A')]`` returns Bituminous Concrete. -.. function:: interactive_map(bbox: Tuple[float, float, float, float]) -> folium.Map +.. function:: interactive_map(bbox: Tuple[float, float, float, float], crs: str = DEF_CRS, dv: bool = False, iv: bool = False, param_cd: Optional[str] = None) -> folium.Map Generate an interactive map including all USGS stations within a bounding box. - .. rubric:: Notes + :Parameters: * **bbox** (:class:`tuple`) -- List of corners in this order (west, south, east, north) + * **crs** (:class:`str`, *optional*) -- CRS of the input bounding box, defaults to EPSG:4326. + * **dv** (:class:`bool`, *optional*) -- Only include stations that record daily values, default to False. + * **iv** (:class:`bool`, *optional*) -- Only include stations that record instantaneous/real-time values, default to False. + * **param_cd** (:class:`str`, *optional*) -- Parameter code for further filtering the stations, defaults to None. + A list of parameter codes can be found + `here `__. - Only stations that record(ed) daily streamflow data are included. + :returns: :class:`folium.Map` -- Interactive map within a bounding box. - :Parameters: **bbox** (:class:`tuple`) -- List of corners in this order (west, south, east, north) + .. rubric:: Examples - :returns: :class:`folium.Map` -- Interactive map within a bounding box. + >>> import pygeohydro as gh + >>> m = gh.interactive_map((-69.77, 45.07, -69.31, 45.45), dv=True, iv=True) + >>> n_stations = len(m.to_dict()["children"]) - 1 + >>> n_stations + 10 .. function:: nlcd(geometry: Union[Polygon, MultiPolygon, Tuple[float, float, float, float]], resolution: float, years: Optional[Dict[str, Optional[int]]] = None, geo_crs: str = DEF_CRS, crs: str = DEF_CRS) -> xr.Dataset diff --git a/docs/source/autoapi/pygeoogc/core/index.rst b/docs/source/autoapi/pygeoogc/core/index.rst index 2204e91..39d85b3 100644 --- a/docs/source/autoapi/pygeoogc/core/index.rst +++ b/docs/source/autoapi/pygeoogc/core/index.rst @@ -131,7 +131,7 @@ Module Contents .. method:: get_validlayers(self) -> Dict[str, str] - Get the layers supportted by the WMS service. + Get the layers supported by the WMS service. .. method:: validate_wms(self) -> None diff --git a/docs/source/autoapi/pygeoogc/pygeoogc/index.rst b/docs/source/autoapi/pygeoogc/pygeoogc/index.rst index ad0ab2f..b0a3e13 100644 --- a/docs/source/autoapi/pygeoogc/pygeoogc/index.rst +++ b/docs/source/autoapi/pygeoogc/pygeoogc/index.rst @@ -12,7 +12,7 @@ Module Contents --------------- -.. py:class:: ArcGISRESTful +.. py:class:: ArcGISRESTful(base_url: str, outformat: str = 'geojson', outfields: Union[List[str], str] = '*', spatial_relation: str = 'esriSpatialRelIntersects', crs: str = DEF_CRS, n_threads: int = 1) diff --git a/docs/source/autoapi/pygeoogc/utils/index.rst b/docs/source/autoapi/pygeoogc/utils/index.rst index e3417bd..d3ecea1 100644 --- a/docs/source/autoapi/pygeoogc/utils/index.rst +++ b/docs/source/autoapi/pygeoogc/utils/index.rst @@ -81,7 +81,7 @@ Module Contents -.. py:class:: RetrySession(retries: int = 3, backoff_factor: float = 0.3, status_to_retry: Tuple[int, ...] = (500, 502, 504), prefixes: Tuple[str, ...] = ('https://', )) +.. py:class:: RetrySession(retries: int = 3, backoff_factor: float = 0.3, status_to_retry: Tuple[int, ...] = (500, 502, 504), prefixes: Tuple[str, ...] = ('https://', ), cache_name: Optional[Union[str, Path]] = None) Configures the passed-in session to retry on failed requests. @@ -93,6 +93,8 @@ Module Contents * **backoff_factor** (:class:`float`, *optional*) -- A factor used to compute the waiting time between retries, defaults to 0.5. * **status_to_retry** (:class:`tuple`, *optional*) -- A tuple of status codes that trigger the reply behaviour, defaults to (500, 502, 504). * **prefixes** (:class:`tuple`, *optional*) -- The prefixes to consider, defaults to ("http://", "https://") + * **cache_name** (:class:`str`, *optional*) -- Path to a folder for caching the session, default to None (no caching). + It is recommended to use caching as it can significantly speed up the function. .. method:: get(self, url: str, payload: Optional[Mapping[str, Any]] = None, headers: Optional[MutableMapping[str, Any]] = None) -> Response @@ -111,22 +113,6 @@ Module Contents -.. function:: async_requests(url_payload: List[Tuple[str, Optional[MutableMapping[str, Any]]]], read: str, request: str = 'GET', max_workers: int = 8) -> List[Union[str, MutableMapping[str, Any], bytes]] - - Send async requests. - - This function is based on - `this `__ - script. - - :Parameters: * **url_payload** (:class:`list` of :class:`tuples`) -- A list of URLs and payloads as a tuple. - * **read** (:class:`str`) -- The method for returning the request; binary, json, and text. - * **request** (:class:`str`, *optional*) -- The request type; GET or POST, defaults to GET. - * **max_workers** (:class:`int`, *optional*) -- The maximum number of async processes, defaults to 8. - - :returns: :class:`list` -- A list of responses - - .. function:: bbox_decompose(bbox: Tuple[float, float, float, float], resolution: float, box_crs: str = DEF_CRS, max_px: int = 8000000) -> List[Tuple[Tuple[float, float, float, float], str, int, int]] Split the bounding box vertically for WMS requests. @@ -161,6 +147,11 @@ Module Contents Check if a ``requests.Resonse`` returned an error message. +.. function:: create_cachefile(db_name: str = 'http_cache') -> Optional[Path] + + Create a cache file if dependencies are met. + + .. function:: threading(func: Callable, iter_list: Iterable, param_list: Optional[List[Any]] = None, max_workers: int = 8) -> List[Any] Run a function in parallel with threading. diff --git a/docs/source/autoapi/pynhd/pynhd/index.rst b/docs/source/autoapi/pynhd/pynhd/index.rst index 7937e17..bef3096 100644 --- a/docs/source/autoapi/pynhd/pynhd/index.rst +++ b/docs/source/autoapi/pynhd/pynhd/index.rst @@ -81,6 +81,7 @@ Module Contents * **outfields** (:class:`str` or :class:`list`, *optional*) -- Target field name(s), default to "*" i.e., all the fields. * **crs** (:class:`str`, *optional*) -- Target spatial reference, default to EPSG:4326 * **service** (:class:`str`, *optional*) -- Name of the web service to use, defaults to hydro. Supported web services are: + * hydro: https://hydro.nationalmap.gov/arcgis/rest/services/NHDPlus_HR/MapServer * edits: https://edits.nationalmap.gov/arcgis/rest/services/NHDPlus_HR/NHDPlus_HR/MapServer * **auto_switch** (:class:`bool`, *optional*) -- Automatically switch to other services' URL if the first one doesn't work, default to False. @@ -98,7 +99,7 @@ Module Contents * **loc_crs** (:class:`str`, *optional*) -- The spatial reference of the input coordinate, defaults to EPSG:4326. :returns: :class:`geopandas.GeoDataFrame` or :class:`(geopandas.GeoDataFrame`, :class:`list)` -- NLDI indexed ComID(s) in EPSG:4326. If some coords don't return any ComID - a list of missing coords are returnd as well. + a list of missing coords are returned as well. .. method:: get_basins(self, station_ids: Union[str, List[str]]) -> Union[gpd.GeoDataFrame, Tuple[gpd.GeoDataFrame, List[str]]] @@ -108,12 +109,12 @@ Module Contents :Parameters: **station_ids** (:class:`str` or :class:`list`) -- USGS station ID(s). :returns: :class:`geopandas.GeoDataFrame` or :class:`(geopandas.GeoDataFrame`, :class:`list)` -- NLDI indexed basins in EPSG:4326. If some IDs don't return any features - a list of missing ID(s) are returnd as well. + a list of missing ID(s) are returned as well. .. method:: get_validchars(self, char_type: str) -> pd.DataFrame - Get all the avialable characteristics IDs for a give characteristics type. + Get all the available characteristics IDs for a give characteristics type. .. method:: getcharacteristic_byid(self, comids: Union[List[str], str], char_type: str, char_ids: Union[str, List[str]] = 'all', values_only: bool = True) -> Union[pd.DataFrame, Tuple[pd.DataFrame, pd.DataFrame]] @@ -142,29 +143,30 @@ Module Contents * **fid** (:class:`str` or :class:`list`) -- Feature ID(s). :returns: :class:`geopandas.GeoDataFrame` or :class:`(geopandas.GeoDataFrame`, :class:`list)` -- NLDI indexed features in EPSG:4326. If some IDs don't return any features - a list of missing ID(s) are returnd as well. + a list of missing ID(s) are returned as well. .. method:: navigate_byid(self, fsource: str, fid: str, navigation: str, source: str, distance: int = 500) -> gpd.GeoDataFrame - Navigate the NHDPlus databse from a single feature id up to a distance. + Navigate the NHDPlus database from a single feature id up to a distance. :Parameters: * **fsource** (:class:`str`) -- The name of feature source. The valid sources are: - comid, huc12pp, nwissite, wade, WQP. + ``comid``, ``huc12pp``, ``nwissite``, ``wade``, ``WQP``. * **fid** (:class:`str`) -- The ID of the feature. * **navigation** (:class:`str`) -- The navigation method. * **source** (:class:`str`, *optional*) -- Return the data from another source after navigating the features using fsource, defaults to None. * **distance** (:class:`int`, *optional*) -- Limit the search for navigation up to a distance in km, defaults is 500 km. Note that this is an expensive request so you - have be mindful of the value that you provide. + have be mindful of the value that you provide. The value must be + between 1 to 9999 km. :returns: :class:`geopandas.GeoDataFrame` -- NLDI indexed features in EPSG:4326. .. method:: navigate_byloc(self, coords: Tuple[float, float], navigation: Optional[str] = None, source: Optional[str] = None, loc_crs: str = DEF_CRS, distance: int = 500) -> gpd.GeoDataFrame - Navigate the NHDPlus databse from a coordinate. + Navigate the NHDPlus database from a coordinate. :Parameters: * **coords** (:class:`tuple`) -- A tuple of length two (x, y). * **navigation** (:class:`str`, *optional*) -- The navigation method, defaults to None which throws an exception @@ -194,7 +196,7 @@ Module Contents .. method:: get_children(self, item: str) -> Dict[str, Any] - Get childern items of an item. + Get children items of an item. .. method:: get_files(self, item: str) -> Dict[str, Tuple[str, str]] @@ -243,8 +245,8 @@ Module Contents * **xy** (:class:`bool`, *optional*) -- Whether axis order of the input geometry is xy or yx. * **predicate** (:class:`str`, *optional*) -- The geometric prediacte to use for requesting the data, defaults to INTERSECTS. Valid predicates are: - EQUALS, DISJOINT, INTERSECTS, TOUCHES, CROSSES, WITHIN, CONTAINS, - OVERLAPS, RELATE, BEYOND + ``EQUALS``, ``DISJOINT``, ``INTERSECTS``, ``TOUCHES``, ``CROSSES``, ``WITHIN`` + ``CONTAINS``, ``OVERLAPS``, ``RELATE``, ``BEYOND`` :returns: :class:`geopandas.GeoDataFrame` -- The requested features in the given geometry. @@ -270,3 +272,28 @@ Module Contents :returns: :class:`pandas.DataFrame` -- Either a dataframe containing the database metadata or the requested attribute over CONUS. +.. function:: nhdplus_vaa(parquet_name: Optional[Union[Path, str]] = None) -> pd.DataFrame + + Get NHDPlus Value Added Attributes with ComID-level roughness and slope values. + + .. rubric:: Notes + + This downloads a 200 MB ``parquet`` file from + `here `__ . + Although this dataframe does not include geometry, it can be linked to other geospatial + NHDPlus dataframes through ComIDs. + + :Parameters: **parquet_name** (:class:`str` or :class:`~~pathlib.Path`) -- Path to a file with ``.parquet`` extension for saving the processed to disk for + later use. + + :returns: :class:`pandas.DataFrame` -- A dataframe that includes ComID-level attributes for 2.7 million NHDPlus flowlines. + + .. rubric:: Examples + + >>> import tempfile + >>> from pathlib import Path + >>> vaa = nhdplus_vaa(Path(tempfile.gettempdir(), "nhdplus_vaa.parquet")) + >>> print(vaa.slope.max()) + 4.6 + + diff --git a/docs/source/conf.py b/docs/source/conf.py index b32f646..4b1248f 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -26,7 +26,7 @@ "sphinx.ext.napoleon", "sphinx.ext.intersphinx", "sphinx.ext.extlinks", - "sphinx.ext.viewcode", + "sphinx.ext.linkcode", "sphinx.ext.mathjax", "IPython.sphinxext.ipython_directive", "IPython.sphinxext.ipython_console_highlighting", @@ -56,6 +56,7 @@ autoapi_dirs = [ "../../pygeoogc", "../../pygeoutils", + "../../async_retriever", "../../pynhd", "../../pygeohydro", "../../py3dep", @@ -84,6 +85,7 @@ # typehints configurations autodoc_typehints = "description" +autodoc_typehints_description_target = "documented" # nbsphinx configurations nbsphinx_timeout = 600 @@ -249,3 +251,57 @@ def setup(app): True, ) app.add_transform(AutoStructify) + +# -- link to source ---------------------------------------------------------- + +# based on numpy doc/source/conf.py +def linkcode_resolve(domain, info): + """ + Determine the URL corresponding to Python object + """ + if domain != "py": + return None + + p_name = info["module"].split(".")[0] + p_obj = sys.modules.get(p_name) + + modname = info["module"] + fullname = info["fullname"] + + submod = sys.modules.get(modname) + if submod is None: + return None + + obj = submod + for part in fullname.split("."): + try: + obj = getattr(obj, part) + except AttributeError: + return None + + try: + fn = inspect.getsourcefile(inspect.unwrap(obj)) + except TypeError: + fn = None + if not fn: + return None + + try: + source, lineno = inspect.getsourcelines(obj) + except OSError: + lineno = None + + if lineno: + linespec = f"#L{lineno}-L{lineno + len(source) - 1}" + else: + linespec = "" + + fn = os.path.relpath(fn, start=os.path.dirname(p_obj.__file__)) + + if "+" in p_obj.__version__: + return f"https://github.com/cheginit/{p_name}/blob/main/{p_name}/{fn}{linespec}" + else: + return ( + f"https://github.com/cheginit/{p_name}/blob/" + f"v{p_obj.__version__}/{p_name}/{fn}{linespec}" + ) \ No newline at end of file diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 2461dc2..b46c417 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -27,7 +27,7 @@ You can install all the packages using ``pip``: .. code-block:: console - $ pip install pygeoogc pygeoutils py3dep pynhd pygeohydro pydaymet + $ pip install py3de pynhd pygeohydro pydaymet pygeoogc pygeoutils async_retriever Please note that installation with ``pip`` fails if ``libgdal`` is not installed on your system. You should install this package manually beforehand. For example, on Ubuntu-based distros @@ -39,50 +39,79 @@ the ``conda-forge`` repository: .. code-block:: console - $ conda install -c conda-forge pygeoogc pygeoutils py3de pynhd pygeohydro pydaymet + $ conda install -c conda-forge py3de pynhd pygeohydro pydaymet pygeoogc pygeoutils async_retriever or: .. code-block:: console - $ mamba install -c conda-forge --strict-channel-priority pygeoogc pygeoutils py3de pynhd pygeohydro pydaymet + $ mamba install -c conda-forge --strict-channel-priority py3de pynhd pygeohydro pydaymet pygeoogc pygeoutils async_retriever Dependencies ------------ .. panels:: - :column: col-lg-12 p-2 + :column: col-lg-12 col-md-12 col-sm-12 col-xs-12 p-2 .. tabbed:: PyNHD - - ``pygeoutils`` + - ``cytoolz`` + - ``geopandas`` - ``networkx`` + - ``numpy`` + - ``pandas`` - ``pyarrow`` + - ``pygeoogc`` + - ``pygeoutils`` + - ``requests`` + - ``shapely`` + - ``simplejson`` .. tabbed:: PyGeoHydro - - ``pynhd`` + - ``defusedxml`` - ``folium`` + - ``geopandas`` - ``lxml`` - ``matplotlib`` + - ``numpy`` - ``openpyxl`` + - ``pandas`` + - ``pygeoogc`` + - ``pygeoutils`` + - ``pynhd`` + - ``rasterio`` + - ``shapely`` .. tabbed:: Py3DEP + - ``click`` + - ``cytoolz`` + - ``numpy`` + - ``pygeoogc`` - ``pygeoutils`` + - ``rasterio`` + - ``shapely`` + - ``xarray`` .. tabbed:: PyDaymet - - ``py3dep`` - - ``aiohttp-client-cache`` (optional) - - ``aiosqlite`` (optional) - ``async_retriever`` - - ``dask`` + - ``click`` + - ``dask[complete]`` - ``lxml`` + - ``numpy`` + - ``pandas`` + - ``py3dep`` + - ``pygeoogc`` + - ``pygeoutils`` + - ``rasterio`` - ``scipy`` + - ``shapely`` + - ``xarray`` .. panels:: - :column: col-lg-12 p-2 + :column: col-lg-12 col-md-12 col-sm-12 col-xs-12 p-2 .. tabbed:: PyGeoOGC @@ -90,31 +119,33 @@ Dependencies - ``defusedxml`` - ``owslib`` - ``pyproj`` + - ``pyyaml`` - ``requests`` - - ``requests_cache`` (optional) - - ``setuptools`` + - ``shapely`` + - ``simplejson`` + - ``urllib3`` .. tabbed:: PyGeoUtils - - ``pygeoogc`` + - ``affine`` - ``geopandas`` - ``netcdf4`` + - ``numpy`` + - ``orjson`` + - ``pygeoogc`` + - ``pyproj`` - ``rasterio`` + - ``shapely`` - ``xarray`` .. tabbed:: AsyncRetriever - - ``aiodns`` - - ``aiohttp`` - - ``aiohttp-client-cache`` (optional) - - ``aiosqlite`` (optional) - - ``brotlipy`` - - ``chardet`` + - ``aiohttp-client-cache`` + - ``aiohttp[speedups]`` + - ``aiosqlite`` - ``cytoolz`` - ``nest-asyncio`` - ``orjson`` - - ``setuptools`` - Additionally, you can also install ``bottleneck``, ``pygeos``, and ``rtree`` to improve performance of ``xarray`` and ``geopandas``. For handling vector and diff --git a/docs/source/index.rst b/docs/source/index.rst index fd9d5ad..241e416 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -72,7 +72,7 @@ Hydroclimate Data Retriever | `HyRiver `__ (formerly named -`hydrodata `__) is a software stack consisting of six +`hydrodata `__) is a software stack consisting of seven Python libraries that are designed to aid in watershed analysis through web services. Currently, this project only includes hydrology and climatology data within the US. @@ -134,7 +134,7 @@ Currently, this project only includes hydrology and climatology data within the .. tabbed:: PyGeoOGC - Send queries to and recieve responses from any ArcGIS RESTful-, WMS-, + Send queries to and receive responses from any ArcGIS RESTful-, WMS-, and WFS-based services. |pygeoogc| |pygeoogc_stat| diff --git a/docs/source/notebooks/aridity.nblink b/docs/source/notebooks/aridity.nblink new file mode 100644 index 0000000..1caae62 --- /dev/null +++ b/docs/source/notebooks/aridity.nblink @@ -0,0 +1 @@ +{"path": "../../../HyRiver-Examples/notebooks/aridity.ipynb"} diff --git a/docs/source/notebooks/ndvi.nblink b/docs/source/notebooks/ndvi.nblink new file mode 100644 index 0000000..73a592c --- /dev/null +++ b/docs/source/notebooks/ndvi.nblink @@ -0,0 +1 @@ +{"path": "../../../HyRiver-Examples/notebooks/ndvi.ipynb"} diff --git a/docs/source/notebooks/noaa.nblink b/docs/source/notebooks/noaa.nblink new file mode 100644 index 0000000..4a39219 --- /dev/null +++ b/docs/source/notebooks/noaa.nblink @@ -0,0 +1 @@ +{"path": "../../../HyRiver-Examples/notebooks/noaa.ipynb"} diff --git a/docs/source/notebooks/us_coasts.nblink b/docs/source/notebooks/us_coasts.nblink new file mode 100644 index 0000000..0c86199 --- /dev/null +++ b/docs/source/notebooks/us_coasts.nblink @@ -0,0 +1 @@ +{"path": "../../../HyRiver-Examples/notebooks/us_coasts.ipynb"}