[WIP]: Optimized raster-based weights builder

ci/38.yaml

@@ -15,4 +15,6 @@ dependencies:
   # optional
   - geopandas>=0.7.0
   - numba
+  - xarray
+  - joblib
   - zstd

libpysal/weights/contiguity.py

@@ -183,9 +183,21 @@ def from_dataframe(
         )
 
     @classmethod
-    def from_xarray(cls, da, z_value=None, coords_labels={}, sparse=False, **kwargs):
+    def from_xarray(
+        cls,
+        da,
+        z_value=None,
+        coords_labels={},
+        k=1,
+        include_nodata=False,
+        n_jobs=1,
+        sparse=True,
+        **kwargs,
+    ):
         """
-        Construct a weights object from a xarray.DataArray.
+        Construct a weights object from a xarray.DataArray with an additional
+        attribute index containing coordinate values of the raster
+        in the form of Pandas.Index/MultiIndex.
 
         Parameters
         ----------
@@ -196,27 +208,42 @@ def from_xarray(cls, da, z_value=None, coords_labels={}, sparse=False, **kwargs)
         coords_labels : dictionary
             Pass dimension labels for coordinates and layers if they do not
             belong to default dimensions, which are (band/time, y/lat, x/lon)
-            e.g. dims = {"y_label": "latitude", "x_label": "longitude", "z_label": "year"}
+            e.g. coords_labels = {"y_label": "latitude", "x_label": "longitude", "z_label": "year"}
             Default is {} empty dictionary.
         sparse : boolean
-            type of weight object. Default is False. For sparse, sparse = True
+            type of weight object. Default is True. For libpysal.weights.W, sparse = False
+        k : int
+            Order of contiguity, this will select all neighbors upto kth order.
+            Default is 1.
+        include_nodata : boolean
+            If True, missing values will be assumed as non-missing when
+            selecting higher_order neighbors, Default is False
+        n_jobs : int
+            Number of cores to be used in the sparse weight construction. If -1,
+            all available cores are used. Default is 1.
         **kwargs : keyword arguments
             optional arguments passed when sparse = False
 
         Returns
         -------
         w : libpysal.weights.W/libpysal.weights.WSP
-            instance of spatial weights class W or WSP
+            instance of spatial weights class W or WSP with an index attribute 
+
+        Notes
+        -----
+        1. Lower order contiguities are also selected.
+        2. Returned object contains `index` attribute that includes a 
+        `Pandas.MultiIndex` object from the DataArray.
 
         See Also
         --------
         :class:`libpysal.weights.weights.W`
-        :class:`libpysal.weights.weights.WSP`   
+        :class:`libpysal.weights.weights.WSP`
         """
         if sparse:
-            w = da2WSP(da, "rook", z_value, coords_labels)
+            w = da2WSP(da, "rook", z_value, coords_labels, k, include_nodata)
         else:
-            w = da2W(da, "rook", z_value, coords_labels, **kwargs)
+            w = da2W(da, "rook", z_value, coords_labels, k, include_nodata, **kwargs)
         return w
 
 
@@ -386,9 +413,21 @@ def from_dataframe(cls, df, geom_col=None, **kwargs):
         return w
 
     @classmethod
-    def from_xarray(cls, da, z_value=None, coords_labels={}, sparse=False, **kwargs):
+    def from_xarray(
+        cls,
+        da,
+        z_value=None,
+        coords_labels={},
+        k=1,
+        include_nodata=False,
+        n_jobs=1,
+        sparse=True,
+        **kwargs,
+    ):
         """
-        Construct a weights object from a xarray.DataArray.
+        Construct a weights object from a xarray.DataArray with an additional
+        attribute index containing coordinate values of the raster
+        in the form of Pandas.Index/MultiIndex.
 
         Parameters
         ----------
@@ -399,27 +438,42 @@ def from_xarray(cls, da, z_value=None, coords_labels={}, sparse=False, **kwargs)
         coords_labels : dictionary
             Pass dimension labels for coordinates and layers if they do not
             belong to default dimensions, which are (band/time, y/lat, x/lon)
-            e.g. dims = {"y_label": "latitude", "x_label": "longitude", "z_label": "year"}
+            e.g. coords_labels = {"y_label": "latitude", "x_label": "longitude", "z_label": "year"}
             Default is {} empty dictionary.
         sparse : boolean
-            type of weight object. Default is False. For sparse, sparse = True
+            type of weight object. Default is True. For libpysal.weights.W, sparse = False
+        k : int
+            Order of contiguity, this will select all neighbors upto kth order.
+            Default is 1.
+        include_nodata : boolean
+            If True, missing values will be assumed as non-missing when
+            selecting higher_order neighbors, Default is False
+        n_jobs : int
+            Number of cores to be used in the sparse weight construction. If -1,
+            all available cores are used. Default is 1.
         **kwargs : keyword arguments
             optional arguments passed when sparse = False
 
         Returns
         -------
         w : libpysal.weights.W/libpysal.weights.WSP
-            instance of spatial weights class W or WSP
+            instance of spatial weights class W or WSP with an index attribute 
+
+        Notes
+        -----
+        1. Lower order contiguities are also selected.
+        2. Returned object contains `index` attribute that includes a 
+        `Pandas.MultiIndex` object from the DataArray.
 
         See Also
         --------
         :class:`libpysal.weights.weights.W`
-        :class:`libpysal.weights.weights.WSP`   
+        :class:`libpysal.weights.weights.WSP`
         """
         if sparse:
-            w = da2WSP(da, "queen", z_value, coords_labels)
+            w = da2WSP(da, "queen", z_value, coords_labels, k, include_nodata)
         else:
-            w = da2W(da, "queen", z_value, coords_labels, **kwargs)
+            w = da2W(da, "queen", z_value, coords_labels, k, include_nodata, **kwargs)
         return w