feat: sort featurecollection by area (#482)

Author: 12rambau

geetools/ee_feature_collection.py

@@ -767,3 +767,32 @@ def fromGeoInterface(
 
         # create the feature collection
         return ee.FeatureCollection(data)
+
+    def areaSort(self, ascending: bool = True) -> ee.FeatureCollection:
+        """Sort the features in the collection by area.
+
+        Args:
+            ascending: Whether to sort in ascending order.
+
+        Returns:
+            The sorted collection.
+
+        Examples:
+            .. jupyter-execute::
+
+                import ee, geetools
+                from geetools.utils import initialize_documentation
+
+                initialize_documentation()
+
+                fc = ee.FeatureCollection("FAO/GAUL/2015/level0").limit(5)
+                fc = fc.geetools.areaSort()
+                fc.aggregate_array("ADM0_NAME").getInfo()
+        """
+        # generate an area property
+        name = "__geetools_area__"
+        fc = self._obj.map(lambda feat: feat.set(name, feat.geometry().area(1)))
+
+        # sort by area and remove the property from the output
+        properties = fc.first().propertyNames().remove(name)
+        return fc.sort(name, ascending).map(lambda feat: feat.select(properties))

tests/test_FeatureCollection.py

@@ -362,3 +362,12 @@ def gdfZ(self):
             ],
         }
         return gpd.GeoDataFrame.from_features(data["features"])
+
+    class TestAreaSort:
+        """Test the ``areaSort`` method."""
+
+        def test_area_sort(self, ee_list_regression):
+            fc = ee.FeatureCollection("FAO/GAUL/2015/level0").limit(5)
+            fc = fc.geetools.areaSort()
+            property = fc.aggregate_array("ADM0_NAME")
+            ee_list_regression.check(property)

tests/test_FeatureCollection/serialized_test_area_sort.yml

@@ -0,0 +1,96 @@
+result: '0'
+values:
+  '0':
+    functionInvocationValue:
+      arguments:
+        collection:
+          functionInvocationValue:
+            arguments:
+              baseAlgorithm:
+                functionDefinitionValue:
+                  argumentNames:
+                  - _MAPPING_VAR_1_0
+                  body: '1'
+              collection:
+                functionInvocationValue:
+                  arguments:
+                    ascending:
+                      constantValue: true
+                    collection:
+                      valueReference: '3'
+                    key:
+                      valueReference: '2'
+                  functionName: Collection.limit
+            functionName: Collection.map
+        property:
+          constantValue: ADM0_NAME
+      functionName: AggregateFeatureCollection.array
+  '1':
+    functionInvocationValue:
+      arguments:
+        input:
+          argumentReference: _MAPPING_VAR_1_0
+        propertySelectors:
+          functionInvocationValue:
+            arguments:
+              element:
+                valueReference: '2'
+              list:
+                functionInvocationValue:
+                  arguments:
+                    element:
+                      functionInvocationValue:
+                        arguments:
+                          collection:
+                            valueReference: '3'
+                        functionName: Collection.first
+                  functionName: Element.propertyNames
+            functionName: List.remove
+      functionName: Feature.select
+  '2':
+    constantValue: __geetools_area__
+  '3':
+    functionInvocationValue:
+      arguments:
+        baseAlgorithm:
+          functionDefinitionValue:
+            argumentNames:
+            - _MAPPING_VAR_0_0
+            body: '4'
+        collection:
+          functionInvocationValue:
+            arguments:
+              collection:
+                functionInvocationValue:
+                  arguments:
+                    tableId:
+                      constantValue: FAO/GAUL/2015/level0
+                  functionName: Collection.loadTable
+              limit:
+                constantValue: 5
+            functionName: Collection.limit
+      functionName: Collection.map
+  '4':
+    functionInvocationValue:
+      arguments:
+        key:
+          valueReference: '2'
+        object:
+          argumentReference: _MAPPING_VAR_0_0
+        value:
+          functionInvocationValue:
+            arguments:
+              geometry:
+                functionInvocationValue:
+                  arguments:
+                    feature:
+                      argumentReference: _MAPPING_VAR_0_0
+                  functionName: Feature.geometry
+              maxError:
+                functionInvocationValue:
+                  arguments:
+                    value:
+                      constantValue: 1
+                  functionName: ErrorMargin
+            functionName: Geometry.area
+      functionName: Element.set

tests/test_FeatureCollection/test_area_sort.yml

@@ -0,0 +1,5 @@
+- Montenegro
+- Taiwan
+- Serbia
+- South Sudan
+- Sudan