DOC: Add async_retriever and more example notebooks openjournals/joss…

…-reviews#3175

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 <https://github.com/HydrologicEngineeringCenter/data-retrieval-scripts/blob/master/qpe_async_download.py>`__
+   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'
+
+

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
+
+

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 </autoapi/pynhd/index>
+   PyGeoHydro </autoapi/pygeohydro/index>
+   Py3DEP </autoapi/py3dep/index>
+   PyDaymet </autoapi/pydaymet/index>
+   PyGeoOGC </autoapi/pygeoogc/index>
+   PyGeoUtils </autoapi/pygeoutils/index>
+   AsyncRetriever </autoapi/async_retriever/index>
 
-.. |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

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"
+
+

docs/source/autoapi/py3dep/index.rst

@@ -15,6 +15,7 @@ Submodules
    :titlesonly:
    :maxdepth: 1
 
+   cli/index.rst
    py3dep/index.rst
 
 

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 <https://rasterio.readthedocs.io/en/latest/api/rasterio.enums.html#rasterio.enums.Resampling>`__
+                  The available methods can be found
+                  `here <https://rasterio.readthedocs.io/en/latest/api/rasterio.enums.html#rasterio.enums.Resampling>`__
 
    :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 <https://www.usgs.gov/core-science-systems/ngp/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

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
+
+