diff --git a/esda/shape.py b/esda/shape.py index 1a620447..27d5ff9b 100644 --- a/esda/shape.py +++ b/esda/shape.py @@ -1,4 +1,5 @@ import contextlib +import warnings import numpy import pandas @@ -198,7 +199,23 @@ def radii_ratio(collection): """ The Flaherty & Crumplin (1992) index, OS_3 in :cite:`altman1998Districting`. + Also known as Schumm's shape index (Schumm (1956) in MacEachren 1985). + The ratio of the radius of the equi-areal circle to the radius of the MBC + + .. math:: + {\\sqrt{{A} \\over {\\pi}}} \\over {R} + + where :math:`A` is the area and :math:`R` is the radius of the minimum bounding + circle. + + Notes + ----- + Implementation follows :cite:`maceachren1985compactness`. + + See Also + -------- + shape_index : Deprecated alias for this function. """ ga = _cast(collection) r_eac = numpy.sqrt(shapely.area(ga) / numpy.pi) @@ -350,7 +367,12 @@ def rectangularity(collection): def shape_index(collection): """ - Schumm’s shape index (Schumm (1956) in MacEachren 1985) + .. deprecated:: 2.5.0 + ``shape_index`` is deprecated and will be removed in future. + Use :func:`radii_ratio` instead, which computes the same Schumm's shape index + (Schumm (1956) in MacEachren 1985). + + Schumm's shape index (Schumm (1956) in MacEachren 1985) .. math:: {\\sqrt{{A} \\over {\\pi}}} \\over {R} @@ -363,8 +385,13 @@ def shape_index(collection): Implementation follows :cite:`maceachren1985compactness`. """ - ga = _cast(collection) - return numpy.sqrt(shapely.area(ga) / numpy.pi) / shapely.minimum_bounding_radius(ga) + warnings.warn( + "shape_index is deprecated and will be removed in future. " + "Use radii_ratio instead, which computes the same index.", + DeprecationWarning, + stacklevel=2, + ) + return radii_ratio(collection) def equivalent_rectangular_index(collection): diff --git a/esda/tests/test_shape.py b/esda/tests/test_shape.py index d049aa2a..4c169bdd 100644 --- a/esda/tests/test_shape.py +++ b/esda/tests/test_shape.py @@ -1,3 +1,5 @@ +import warnings + import geopandas import numpy import pytest @@ -176,8 +178,13 @@ def test_rectangularity(): def test_shape_index(): - observed = esda.shape.shape_index(shape) - testing.assert_allclose(observed, 0.659366, atol=ATOL) + """Test that shape_index is deprecated and returns same value as radii_ratio.""" + with pytest.warns(DeprecationWarning, match="deprecated"): + observed = esda.shape.shape_index(shape) + + # Check that result matches radii_ratio + expected = esda.shape.radii_ratio(shape) + testing.assert_allclose(observed, expected, atol=ATOL) def test_equivalent_rectangular_index():