Add the k nearest p-median module and the tutorial example for capacitated p-median (#397)

* add capacitated p-median case to the notebook

* add the k nearest p median part to the p_median.py

Create a new class

* add the reference of k nearest p median

* modify the KNearestPMedian class

* Create test_knearest_p_median.py

* add the part that can validate the initial k list

* Update test_knearest_p_median.py

* update the p_median and test_knearest_p_median.py

change the name of k to k_array and add the tests for specific errors

* update p-median.ipynb again

add the intro about predefined facilities above cell 49, sorry for only adding it above cell 24 in the previous commit

* clear all the output in p-median.ipynb

* add 'pointpats' to the environment file

* update the pointpats part

* Update .ci/310.yaml

Co-authored-by: James Gaboardi <[email protected]>

* Update .ci/311-DEV.yaml

Co-authored-by: James Gaboardi <[email protected]>

* Update .ci/311.yaml

Co-authored-by: James Gaboardi <[email protected]>

* Update .ci/39.yaml

Co-authored-by: James Gaboardi <[email protected]>

* Update pyproject.toml

(trigger a CI run)

---------

Co-authored-by: James Gaboardi <[email protected]>

Author: rongboxu

.ci/310.yaml

@@ -15,6 +15,7 @@ dependencies:
   - shapely
   - spaghetti
   - tqdm
+  - pointpats
   # testing
   - codecov
   - coverage

.ci/311-DEV.yaml

@@ -14,6 +14,7 @@ dependencies:
   - scipy
   - spaghetti
   - tqdm
+  - pointpats
   # testing
   - codecov
   - coverage

.ci/311.yaml

@@ -14,6 +14,7 @@ dependencies:
   - scipy
   - spaghetti
   - tqdm
+  - pointpats
   # testing
   - codecov
   - coverage

.ci/38-MIN.yaml

@@ -13,6 +13,7 @@ dependencies:
   - scipy=1.7
   - shapely=2.0
   - spaghetti
+  - pointpats=2.3
   # testing
   - codecov
   - coverage

.ci/39.yaml

@@ -14,6 +14,7 @@ dependencies:
   - scipy
   - shapely
   - spaghetti
+  - pointpats
   # testing
   - codecov
   - coverage

docs/_static/references.bib

@@ -168,6 +168,18 @@ @article{openshaw1995algorithms
 }
 
 
+@article{richard_2018,
+  author = {Richard L. Church},
+  title ={Tobler's Law and Spatial Optimization: Why Bakersfield?},
+  journal = {International Regional Science Review},
+  volume = {41},
+  number = {3},
+  pages = {287-310},
+  year = {2018},
+  doi = {10.1177/0160017616650612}
+}
+
+
 @article{shi_malik_2000,
     author={Jianbo Shi and Malik, J.},
     journal={{IEEE Transactions on Pattern Analysis and Machine Intelligence}},

environment.yml

@@ -16,6 +16,7 @@ dependencies:
   - scipy>=1.3.2
   - shapely>=2.0
   - tqdm>=4.27.0
+  - pointpats>=2.3.0
 
   # notebook/binder specific
   - folium

notebooks/p-median.ipynb

@@ -16,11 +16,7 @@ maintainers = [{ name = "spopt contributors" }]
 license = { text = "BSD 3-Clause" }
 description = "Spatial Optimization in PySAL"
 keywords = ["spatial optimization"]
-readme = { text = """\
-Spopt is an open-source Python library for solving optimization problems with spatial data. Originating from the `region` module in `PySAL`_ (Python Spatial Analysis Library), it is under active development for the inclusion of newly proposed models and methods for regionalization, facility location, and transportation-oriented solutions.
-
-.. _PySAL: http://pysal.org
-""", content-type = "text/x-rst" }
+readme = "README.md"
 classifiers = [
     "Programming Language :: Python :: 3",
     "License :: OSI Approved :: BSD License",
@@ -42,6 +38,7 @@ dependencies = [
     "shapely>=2",
     "spaghetti",
     "tqdm>=4.27.0",
+    "pointpats>=2.3.0"
 ]
 
 

pyproject.toml

@@ -0,0 +1,121 @@
+import numpy
+import geopandas
+import pandas
+import pulp
+from shapely.geometry import Point
+
+from spopt.locate.p_median import KNearestPMedian
+import os
+import pickle
+import platform
+import pytest
+import warnings
+
+
+class TestKNearestPMedian:
+    def setup_method(self) -> None:
+        # Create the test data
+        k = numpy.array([1, 1])
+        self.demand_data = {
+            "ID": [1, 2],
+            "geometry": [Point(0.5, 1), Point(1.5, 1)],
+            "demand": [1, 1],
+        }
+        self.facility_data = {
+            "ID": [101, 102, 103],
+            "geometry": [Point(1, 1), Point(0, 2), Point(2, 0)],
+            "capacity": [1, 1, 1],
+        }
+        gdf_demand = geopandas.GeoDataFrame(self.demand_data, crs="EPSG:4326")
+        gdf_fac = geopandas.GeoDataFrame(self.facility_data, crs="EPSG:4326")
+        self.k_nearest_pmedian = KNearestPMedian.from_geodataframe(
+            gdf_demand,
+            gdf_fac,
+            "geometry",
+            "geometry",
+            "demand",
+            p_facilities=2,
+            facility_capacity_col="capacity",
+            k_array=k,
+        )
+
+    def test_knearest_p_median_from_geodataframe(self):
+        result = self.k_nearest_pmedian.solve(pulp.PULP_CBC_CMD(msg=False))
+        assert isinstance(result, KNearestPMedian)
+
+    def test_knearest_p_median_from_geodataframe_no_results(self):
+        result = self.k_nearest_pmedian.solve(
+            pulp.PULP_CBC_CMD(msg=False), results=False
+        )
+        assert isinstance(result, KNearestPMedian)
+
+        with pytest.raises(AttributeError):
+            result.cli2fac
+        with pytest.raises(AttributeError):
+            result.fac2cli
+        with pytest.raises(AttributeError):
+            result.mean_dist
+
+    def test_solve(self):
+        solver = pulp.PULP_CBC_CMD(msg=False)
+        self.k_nearest_pmedian.solve(solver)
+        assert self.k_nearest_pmedian.problem.status == pulp.LpStatusOptimal
+
+        fac2cli_known = [[1], [0], []]
+        cli2fac_known = [[1], [0]]
+        mean_dist_known = 0.8090169943749475
+        assert self.k_nearest_pmedian.fac2cli == fac2cli_known
+        assert self.k_nearest_pmedian.cli2fac == cli2fac_known
+        assert self.k_nearest_pmedian.mean_dist == mean_dist_known
+
+    def test_error_k_array_non_numpy_array(self):
+        gdf_demand = geopandas.GeoDataFrame(self.demand_data, crs="EPSG:4326")
+        gdf_fac = geopandas.GeoDataFrame(self.facility_data, crs="EPSG:4326")
+        k = [1, 1]
+        with pytest.raises(TypeError):
+            KNearestPMedian.from_geodataframe(
+                gdf_demand,
+                gdf_fac,
+                "geometry",
+                "geometry",
+                "demand",
+                p_facilities=2,
+                facility_capacity_col="capacity",
+                k_array=k,
+            )
+
+    def test_error_k_array_invalid_value(self):
+        gdf_demand = geopandas.GeoDataFrame(self.demand_data, crs="EPSG:4326")
+        gdf_fac = geopandas.GeoDataFrame(self.facility_data, crs="EPSG:4326")
+
+        k = numpy.array([1, 4])
+        with pytest.raises(ValueError):
+            KNearestPMedian.from_geodataframe(
+                gdf_demand,
+                gdf_fac,
+                "geometry",
+                "geometry",
+                "demand",
+                p_facilities=2,
+                facility_capacity_col="capacity",
+                k_array=k,
+            )
+
+    def test_error_geodataframe_crs_mismatch(self):
+        gdf_demand = geopandas.GeoDataFrame(self.demand_data, crs="EPSG:4326")
+        gdf_fac = geopandas.GeoDataFrame(
+            self.facility_data, crs="EPSG:3857"
+        )  # Different CRS
+
+        k = numpy.array([1, 1])
+        with pytest.raises(ValueError):
+            KNearestPMedian.from_geodataframe(
+                gdf_demand,
+                gdf_fac,
+                "geometry",
+                "geometry",
+                "demand",
+                p_facilities=2,
+                facility_capacity_col="capacity",
+                k_array=k,
+            )