287 add local morans i

docs/exploratory_analyses/local_morans_i.md

@@ -0,0 +1,3 @@
+# Local Moran's I
+
+::: eis_toolkit.exploratory_analyses.local_morans_i

eis_toolkit/exploratory_analyses/local_morans_i.py

@@ -0,0 +1,64 @@
+import geopandas as gpd
+import libpysal
+import numpy as np
+from beartype import beartype
+from beartype.typing import Literal, Union
+from esda.moran import Moran_Local
+
+from eis_toolkit import exceptions
+
+
+@beartype
+def _local_morans_i(
+    gdf: gpd.GeoDataFrame, column: str, weight_type: Literal["queen", "knn"], k: Union[int, None], permutations: int
+) -> gpd.GeoDataFrame:
+
+    if weight_type == "queen":
+        w = libpysal.weights.Queen.from_dataframe(gdf)
+    elif weight_type == "knn":
+        w = libpysal.weights.KNN.from_dataframe(gdf, k=k)
+    else:
+        raise ValueError("Invalid weight_type. Use 'queen' or 'knn'.")
+
+    if len(gdf[column]) != len(w.weights):
+        raise ValueError("Dimension mismatch between data and weights matrix.")
+
+    moran_loc = Moran_Local(gdf[column], w, permutations=permutations)
+
+    gdf[f"{column}_local_moran_I"] = moran_loc.Is
+    gdf[f"{column}_p_value"] = moran_loc.p_sim
+
+    gdf[f"{column}_p_value"].fillna(value=np.nan, inplace=True)
+
+    return gdf
+
+
+@beartype
+def local_morans_i(
+    gdf: gpd.GeoDataFrame,
+    column: str,
+    weight_type: Literal["queen", "knn"] = "queen",
+    k: Union[int, None] = 2,
+    permutations: int = 999,
+) -> gpd.GeoDataFrame:
+    """Execute Local Moran's I calculation for the area.
+
+    Args:
+        gdf: The geodataframe that contains the area to be examined with local morans I.
+        column: The column to be used in the analysis.
+        weight_type: The type of spatial weights matrix to be used. Defaults to "queen".
+        k: Number of nearest neighbors for the KNN weights matrix. Defaults to 2.
+        permutations: Number of permutations for significance testing. Defaults to 999.
+
+    Returns:
+        Geodataframe containing the calculations.
+
+    Raises:
+        EmptyDataFrameException if input geodataframe is empty.
+    """
+    if gdf.shape[0] == 0:
+        raise exceptions.EmptyDataFrameException("Geodataframe is empty.")
+
+    calculations = _local_morans_i(gdf, column, weight_type, k, permutations)
+
+    return calculations

tests/exploratory_analyses/local_morans_i_test.py

@@ -0,0 +1,56 @@
+import geopandas as gpd
+import libpysal
+import numpy as np
+import pytest
+from esda.moran import Moran_Local
+
+from eis_toolkit import exceptions
+from eis_toolkit.exploratory_analyses.local_morans_i import local_morans_i
+
+
+def test_local_morans_i_queen_correctness():
+    """Test Local Moran's I Queen correctness."""
+
+    permutations = 999
+
+    column = "gdp_md_est"
+    data = gpd.read_file(gpd.datasets.get_path("naturalearth_lowres"))
+    gdf = gpd.GeoDataFrame(data)
+
+    w = libpysal.weights.Queen.from_dataframe(gdf)
+
+    moran_loc = Moran_Local(gdf[column], w, permutations=permutations)
+
+    result = local_morans_i(gdf=gdf, column=column, weight_type="queen", permutations=permutations)
+
+    np.testing.assert_allclose(result[f"{column}_local_moran_I"], moran_loc.Is, rtol=0.1, atol=0.1)
+    np.testing.assert_allclose(result[f"{column}_p_value"], moran_loc.p_sim, rtol=0.1, atol=0.1)
+
+
+def test_local_morans_i_knn_correctness():
+    """Test Local Moran's I KNN correctness."""
+
+    k = 3
+    permutations = 999
+
+    column = "gdp_md_est"
+    data = gpd.read_file(gpd.datasets.get_path("naturalearth_lowres"))
+    gdf = gpd.GeoDataFrame(data)
+
+    w = libpysal.weights.KNN.from_dataframe(gdf, k=k)
+    moran_loc = Moran_Local(gdf[column], w, permutations=permutations)
+
+    result = local_morans_i(gdf, column, "knn", k=k, permutations=permutations)
+
+    np.testing.assert_allclose(result[f"{column}_local_moran_I"], moran_loc.Is, rtol=0.1, atol=0.1)
+    np.testing.assert_allclose(result[f"{column}_p_value"], moran_loc.p_sim, rtol=0.1, atol=0.1)
+
+
+def test_empty_geodataframe():
+    """Test Local Moran's I raises EmptyDataFrameException."""
+
+    empty_gdf = gpd.GeoDataFrame()
+
+    # Use pytest.raises to check the expected exception
+    with pytest.raises(exceptions.EmptyDataFrameException):
+        local_morans_i(empty_gdf, column="value", weight_type="queen", k=2, permutations=999)