added functions and tests

Author: ValentinGebhart

climada/util/coordinates.py

@@ -1687,6 +1687,104 @@ def _ensure_utf8(val):
     return admin1_info, admin1_shapes
 
 
+def boundsNESW_from_global():
+    """
+    Return global NESW bounds in EPSG 4326
+
+    Returns
+    -------
+    list:
+        The calculated bounding box as [north, east, south, west] in EPSG 4326
+    """
+    return [90, 180, -90, -180]
+
+
+def boundsNESW_from_country_codes(country_codes, rel_margin=0.2):
+    """
+    Return NESW bounds in EPSG 4326 for the combined area defined by given country ISO codes.
+
+    Parameters
+    ----------
+    country_codes : list
+        A list of ISO country codes (e.g.,['ITA'], ['ITA', 'CHE']).
+    rel_margin : float
+        A relative margin to extend the bounding box in all directions. Default is 0.2.
+
+    Returns
+    -------
+    list:
+        The calculated bounding box as [north, east, south, west] in EPSG 4326
+    """
+    [north, east, south, west] = [-90, -180, 90, 180]
+
+    # loop through ISO codes
+    for iso in country_codes:
+        geo = get_country_geometries(iso).to_crs(epsg=4326)
+        iso_west, iso_south, iso_east, iso_north = geo.total_bounds
+        if np.any(np.isnan([iso_west, iso_south, iso_east, iso_north])):
+            LOGGER.warning(
+                f"ISO code '{iso}' not recognized. This region will not be included."
+            )
+            continue
+
+        north = max(north, iso_north)
+        east = max(east, iso_east)
+        south = min(south, iso_south)
+        west = min(west, iso_west)
+
+    # no countries recognized
+    if [north, east, south, west] == [-90, -180, 90, 180]:
+        raise Exception("No ISO code was recognized.")
+
+    # add relative margin
+    lat_margin = rel_margin * (north - south)
+    lon_margin = rel_margin * (east - west)
+    north = min(north + lat_margin, 90)
+    east = min(east + lon_margin, 180)
+    south = max(south - lat_margin, -90)
+    west = max(west - lon_margin, -180)
+
+    return [north, east, south, west]
+
+
+def boundsNESW_from_NESW(*, north, east, south, west, rel_margin=0.0):
+    """
+    Return NESW bounds in EPSG 4326 with relative margin from given NESW values in EPSG 4326.
+
+    Parameters
+    ----------
+    north : (float, int)
+        Maximal latitude in EPSG 4326.
+    east : (float, int)
+        Maximal longitute in EPSG 4326.
+    south : (float, int)
+        Minimal latitude in EPSG 4326.
+    west : (float, int)
+        Minimal longitude in EPSG 4326.
+    rel_margin : float
+        A relative margin to extend the bounding box in all directions. Default is 0.2.
+
+    Returns
+    -------
+    list:
+        The calculated bounding box as [north, east, south, west] in EPSG 4326
+    """
+
+    # simple bounds check
+    if not ((90 >= north > south >= -90) and (180 >= east > west >= -180)):
+        raise ValueError("Given bounds are not in standard order or standard bounds")
+
+    # add relative margin
+    lat_margin = rel_margin * (north - south)
+    lon_margin = rel_margin * (east - west)
+    north = min(north + lat_margin, 90)
+    east = min(east + lon_margin, 180)
+    south = max(south - lat_margin, -90)
+    west = max(west - lon_margin, -180)
+
+    return [north, east, south, west]
+
+
 def get_admin1_geometries(countries):
     """
     return geometries, names and codes of admin 1 regions in given countries

climada/util/test/test_coordinates.py

@@ -2294,6 +2294,62 @@ def test_mask_raster_with_geometry(self):
         )
 
 
+class TestBoundsFromUserInput(unittest.TestCase):
+    """Unit tests for the bounds_from_user_input function."""
+
+    def test_boundsNESW_from_global(self):
+        """Test for 'global' area selection."""
+        result = u_coord.boundsNESW_from_global()
+        expected = [90, 180, -90, -180]
+        np.testing.assert_almost_equal(result, expected)
+
+    def test_boundsNESW_from_country_codes(self):
+        """Test for a list of ISO country codes."""
+        result = u_coord.boundsNESW_from_country_codes(
+            ["ITA"], rel_margin=0.2
+        )  # Testing with Italy (ITA)
+        # Real expected bounds for Italy (calculated or manually known)
+        expected = [
+            49.404409157600064,
+            20.900365510000075,
+            33.170049669400036,
+            4.219788779000066,
+        ]  # Italy's bounding box
+
+        np.testing.assert_array_almost_equal(result, expected, decimal=4)
+
+    def test_bounding_box(self):
+        """Test for bounding box input with margin applied."""
+        [north, east, south, west] = [50, -100, 30, -120]
+        result = u_coord.boundsNESW_from_NESW(
+            north=north, south=south, west=west, east=east, rel_margin=0.1
+        )
+        expected = [
+            50 + 2,
+            -100 + 2,
+            30 - 2,
+            -120 - 2,
+        ]  # Apply margin calculation
+        np.testing.assert_array_almost_equal(result, expected)
+
+    def test_invalid_input_string(self):
+        """Test for invalid string input."""
+        with self.assertRaises(Exception):
+            u_coord.boundsNESW_from_country_codes("DEU")
+
+    def test_empty_input(self):
+        """Test for empty input."""
+        with self.assertRaises(Exception):
+            u_coord.boundsNESW_from_country_codes([])
+
+    def test_invalid_coordinate_input(self):
+        """Test for str in coordinates input input."""
+        with self.assertRaises(ValueError):
+            u_coord.boundsNESW_from_NESW(north=40, south=50, east=30, west=10)
+        with self.assertRaises(TypeError):
+            u_coord.boundsNESW_from_NESW(north=40, south="20", east=30, west=10)
+
+
 # Execute Tests
 if __name__ == "__main__":
     TESTS = unittest.TestLoader().loadTestsFromTestCase(TestFunc)
@@ -2302,4 +2358,5 @@ def test_mask_raster_with_geometry(self):
     TESTS.addTests(unittest.TestLoader().loadTestsFromTestCase(TestRasterMeta))
     TESTS.addTests(unittest.TestLoader().loadTestsFromTestCase(TestRasterIO))
     TESTS.addTests(unittest.TestLoader().loadTestsFromTestCase(TestDistance))
+    TESTS.addTests(unittest.TestLoader().loadTestsFromTestCase(TestBoundsFromUserInput))
     unittest.TextTestRunner(verbosity=2).run(TESTS)