Merge branch 'master' of github.com:makepath/xarray-spatial

Author: brendancol

.github/workflows/docs-publish.yml

@@ -14,16 +14,7 @@ jobs:
         run: |
           sudo apt-get -y install pandoc
           python -m pip install --upgrade pip
-          pip install setuptools \
-                      wheel \
-                      geopandas \
-                      nbsphinx \
-                      pandoc \
-                      pydata_sphinx_theme \
-                      sphinx \
-                      sphinx-multiversion \
-                      sphinx-panels \
-                      sphinx_rtd_theme
+          pip install -r docs/source/requirements.txt
       - name: Build
         run: |
           pip install .

conda.recipe/README.md

@@ -86,6 +86,7 @@
     html_theme = 'sphinx_rtd_theme'
 else:
     html_theme = 'pydata_sphinx_theme'
+    extensions.append('matplotlib.sphinxext.plot_directive')
 
 html_logo = '_static/img/Xarray-Spatial-logo.svg'
 
@@ -96,7 +97,11 @@
 if os.getenv('THEME') == 'sphinx_rtd_theme':
     smv_tag_whitelist = r'^v([0]\.[1]\.[0-5]|[0]\.[0]\.[0-9])'
 else:
-    smv_tag_whitelist = r'^v([0-9]\.[1]\.[6-9]|[1-9]\.[0-9]\.[0-9])'
+    smv_tag_whitelist = (
+        r'^v([0-9]\.[1]\.[6-8]|'
+        r'[0-9]\.[2]\.[1-9]|'
+        r'[1-9]\.[0-9]\.[0-9])'
+    )
 
 # Load releases
 with open("releases.json") as f:
@@ -210,5 +215,8 @@
 # A list of files that should not be packed into the epub file.
 epub_exclude_files = ['search.html']
 
+# sphinxext config
+plot_html_show_source_link = False
+
 # nbsphinx configuration
 nbsphinx_allow_errors = True

conda.recipe/build.sh

@@ -31,10 +31,9 @@ Focal Statistics
 .. autosummary::
    :toctree: _autosummary
 
-   xrspatial.focal.annulus_kernel
-   xrspatial.focal.calc_cellsize
+   xrspatial.convolution.annulus_kernel
+   xrspatial.convolution.calc_cellsize
    xrspatial.focal.calc_mean
    xrspatial.focal.calc_sum
-   xrspatial.focal.circle_kernel
+   xrspatial.convolution.circle_kernel
    xrspatial.focal.custom_kernel
-   xrspatial.focal.upper_bound_p_value

conda.recipe/meta.yaml

@@ -1,8 +1,12 @@
 geopandas
+ipykernel
+matplotlib
 nbsphinx
 pandoc
 pydata_sphinx_theme
+setuptools
 sphinx
 sphinx-multiversion
 sphinx-panels
-sphinx_rtd_theme
+sphinx_rtd_theme
+wheel

conda.recipe/run_test.py

@@ -155,70 +155,119 @@ def _run_dask_numpy(data: da.Array) -> da.Array:
 def aspect(agg: xr.DataArray,
            name: Optional[str] = 'aspect') -> xr.DataArray:
     """
-    Calculates, for all cells in the array,
-    the downward slope direction of each cell
-    based on the elevation of its neighbors in a 3x3 grid.
-    The value is measured clockwise in degrees with 0 and 360 at due north.
-    Flat areas are given a value of -1.
-    Values along the edges are not calculated.
-
-    Parameters:
+    Calculates the aspect value of an elevation aggregate.
+
+    Calculates, for all cells in the array, the downward slope direction
+    of each cell based on the elevation of its neighbors in a 3x3 grid.
+    The value is measured clockwise in degrees with 0 and 360 at due
+    north. Flat areas are given a value of -1. Values along the edges
+    are not calculated.
+
+    Parameters
     ----------
-    agg: xarray.DataArray
-        2D array of elevation values. NumPy, CuPy, NumPy-backed Dask,
-        or Cupy-backed Dask array.
-    name: str, optional (default = "aspect")
+    agg : xarray.DataArray
+        2D NumPy, CuPy, NumPy-backed Dask, or Cupy-backed Dask array
+        of elevation values.
+    name : str, default='aspect'
         Name of ouput DataArray.
 
-    Returns:
-    ----------
-    xarray.DataArray
-        2D array, of the same type as the input, of calculated aspect values.
+    Returns
+    -------
+    aspect_agg : xarray.DataArray of the same type as `agg`
+        2D aggregate array of calculated aspect values.
         All other input attributes are preserved.
 
-    Notes:
+    References
     ----------
-    Algorithm References:
-    - esri, How Aspect Works, http://desktop.arcgis.com/en/arcmap/10.3/tools/spatial-analyst-toolbox/how-aspect-works.htm#ESRI_SECTION1_4198691F8852475A9F4BC71246579FAA, Accessed Apr. 21, 2021. # noqa
-    - Burrough, P. A., McDonnell, R., McDonnell, R. A., & Lloyd, C. D. (2015). Principles of geographical information systems. Oxford university press. pp 406. # noqa
-
-    Examples:
-    ----------
-    Imports
-    >>> import numpy as np
-    >>> import xarray as xr
-    >>> import xrspatial
-
-    Create Elevation DataArray
-    >>> agg = xr.DataArray(np.array([[0, 1, 0, 0],
-    >>>                              [1, 1, 0, 0],
-    >>>                              [0, 1, 2, 2],
-    >>>                              [1, 0, 2, 0],
-    >>>                              [0, 2, 2, 2]]),
-    >>>                    dims = ["lat", "lon"])
-    >>> height, width = agg.shape
-    >>> _lon = np.linspace(0, width - 1, width)
-    >>> _lat = np.linspace(0, height - 1, height)
-    >>> agg["lon"] = _lon
-    >>> agg["lat"] = _lat
-
-    Create Aspect DataArray
-    >>> aspect = xrspatial.aspect(agg)
-    >>> print(aspect)
-    <xarray.DataArray 'aspect' (lat: 5, lon: 4)>
-    array([[nan,  nan,  nan,  nan],
-           [nan,   0.,  18.43494882,  nan],
-           [nan, 270., 341.56505118,  nan],
-           [nan, 288.43494882, 315.,  nan],
-           [nan,  nan,  nan,  nan]])
-    Coordinates:
-    * lon      (lon) float64 0.0 1.0 2.0 3.0
-    * lat      (lat) float64 0.0 1.0 2.0 3.0 4.0
-
-    Terrain Example:
-    - makepath, User Guide, https://makepath.github.io/xarray-spatial/assets/examples/user-guide.html, Accessed Apr. 21, 2021 # noqa
+        - arcgis: http://desktop.arcgis.com/en/arcmap/10.3/tools/spatial-analyst-toolbox/how-aspect-works.htm#ESRI_SECTION1_4198691F8852475A9F4BC71246579FAA # noqa
+
+    Examples
+    --------
+    .. plot::
+       :include-source:
+
+        import datashader as ds
+        import matplotlib.pyplot as plt
+        from xrspatial import generate_terrain, aspect
+
+        # Create Canvas
+        W = 500
+        H = 300
+        cvs = ds.Canvas(plot_width = W,
+                        plot_height = H,
+                        x_range = (-20e6, 20e6),
+                        y_range = (-20e6, 20e6))
+
+        # Generate Example Terrain
+        terrain_agg = generate_terrain(canvas = cvs)
+
+        # Edit Attributes
+        terrain_agg = terrain_agg.assign_attrs(
+            {
+                'Description': 'Example Terrain',
+                'units': 'km',
+                'Max Elevation': '4000',
+            }
+        )
+        
+        terrain_agg = terrain_agg.rename({'x': 'lon', 'y': 'lat'})
+        terrain_agg = terrain_agg.rename('Elevation')
+
+        # Create Aspect Aggregate Array
+        aspect_agg = aspect(agg = terrain_agg, name = 'Aspect')
+
+        # Edit Attributes
+        aspect_agg = aspect_agg.assign_attrs(
+            {
+                'Description': 'Example Aspect',
+                'units': 'deg',
+            }
+        )
+
+        # Plot Terrain
+        terrain_agg.plot(cmap = 'terrain', aspect = 2, size = 4)
+        plt.title("Terrain")
+        plt.ylabel("latitude")
+        plt.xlabel("longitude")
+
+        # Plot Aspect
+        aspect_agg.plot(aspect = 2, size = 4)
+        plt.title("Aspect")
+        plt.ylabel("latitude")
+        plt.xlabel("longitude")
+
+    .. sourcecode:: python
+
+        >>> print(terrain_agg[200:203, 200:202])
+        <xarray.DataArray 'Elevation' (lat: 3, lon: 2)>
+        array([[1264.02249454, 1261.94748873],
+               [1285.37061171, 1282.48046696],
+               [1306.02305679, 1303.40657515]])
+        Coordinates:
+          * lon      (lon) float64 -3.96e+06 -3.88e+06
+          * lat      (lat) float64 6.733e+06 6.867e+06 7e+06
+        Attributes:
+            res:            1
+            Description:    Example Terrain
+            units:          km
+            Max Elevation:  4000
+
+    .. sourcecode:: python
+
+        >>> print(aspect_agg[200:203, 200:202])
+        <xarray.DataArray 'Aspect' (lat: 3, lon: 2)>
+        array([[ 8.18582638,  8.04675084],
+               [ 5.49302641,  9.86625477],
+               [12.04270534, 16.87079619]])
+        Coordinates:
+          * lon      (lon) float64 -3.96e+06 -3.88e+06
+          * lat      (lat) float64 6.733e+06 6.867e+06 7e+06
+        Attributes:
+            res:            1
+            Description:    Example Aspect
+            units:          deg
+            Max Elevation:  4000
     """
-
     # numpy case
     if isinstance(agg.data, np.ndarray):
         out = _run_numpy(agg.data)