Deprecate Hazard.from_raster_xarray_file

* Make `Hazard.from_raster_xarray` handle files.
* Update tests
* Fix linter issues

Author: peanutfun

climada/hazard/io.py

@@ -32,6 +32,7 @@
 import pandas as pd
 import rasterio
 import xarray as xr
+from deprecation import deprecated
 from scipy import sparse
 
 import climada.util.constants as u_const
@@ -274,6 +275,10 @@ def from_raster(
         )
 
     @classmethod
+    @deprecated(
+        details="Hazard.from_xarray_raster now supports a filepath for the 'data' "
+        "parameter"
+    )
     def from_xarray_raster_file(
         cls, filepath: Union[pathlib.Path, str], *args, **kwargs
     ):
@@ -301,26 +306,14 @@ def from_xarray_raster_file(
         Examples
         --------
 
-        >>> hazard = Hazard.from_xarray_raster_file("path/to/file.nc", "", "")
-
-        Notes
-        -----
-
-        If you have specific requirements for opening a data file, prefer opening it
-        yourself and using :py:meth:`~Hazard.from_xarray_raster`, following this pattern:
-
-        >>> open_kwargs = dict(engine="h5netcdf", chunks=dict(x=-1, y="auto"))
-        >>> with xarray.open_dataset("path/to/file.nc", **open_kwargs) as dset:
-        ...     hazard = Hazard.from_xarray_raster(dset, "", "")
         """
-        reader = HazardXarrayReader.from_file(filepath, *args, **kwargs)
-        kwargs = reader.get_hazard_kwargs()
-        return cls(**cls._check_and_cast_attrs(kwargs))
+        args = (filepath,) + args
+        return cls.from_xarray_raster(*args, **kwargs)
 
     @classmethod
     def from_xarray_raster(
         cls,
-        data: xr.Dataset,
+        data: xr.Dataset | pathlib.Path | str,
         hazard_type: str,
         intensity_unit: str,
         *,
@@ -329,6 +322,7 @@ def from_xarray_raster(
         data_vars: Optional[Dict[str, str]] = None,
         crs: str = u_const.DEF_CRS,
         rechunk: bool = False,
+        open_dataset_kws: dict[str, Any] | None = None,
     ):
         """Read raster-like data from an xarray Dataset
 
@@ -352,13 +346,10 @@ def from_xarray_raster(
         meaning that the object can be used in all CLIMADA operations without throwing
         an error due to missing data or faulty data types.
 
-        Use :py:meth:`~Hazard.from_xarray_raster_file` to open a file on disk
-        and load the resulting dataset with this method in one step.
-
         Parameters
         ----------
-        data : xarray.Dataset
-            The dataset to read from.
+        data : xarray.Dataset or Path or str
+            The filepath to read the data from or the already opened dataset
         hazard_type : str
             The type identifier of the hazard. Will be stored directly in the hazard
             object.
@@ -406,6 +397,9 @@ def from_xarray_raster(
             be forced by rechunking the data. Ideally, you would select the chunks in
             that manner when opening the dataset before passing it to this function.
             Defaults to ``False``.
+        open_dataset_kws : dict(str, any)
+            Keyword arguments passed to ``xarray.open_dataset`` if ``data`` is a file
+            path. Ignored otherwise.
 
         Returns
         -------
@@ -414,8 +408,8 @@ def from_xarray_raster(
 
         See Also
         --------
-        :py:meth:`~Hazard.from_xarray_raster_file`
-            Use this method if you want CLIMADA to open and read a file on disk for you.
+        :py:class:`HazardXarrayReader`
+            The helper class used to read the data.
 
         Notes
         -----
@@ -457,6 +451,21 @@ def from_xarray_raster(
         ... )
         >>> hazard = Hazard.from_xarray_raster(dset, "", "")
 
+        Data can also be read from a file.
+
+        >>> dset.to_netcdf("path/to/file.nc")
+        >>> hazard = Hazard.from_xarray_raster("path/to/file.nc", "", "")
+
+        If you have specific requirements for opening a data file, you can pass
+        ``open_dataset_kws``.
+
+        >>> hazard = Hazard.from_xarray_raster(
+        ...     dset,
+        ...     "",
+        ...     "",
+        ...     open_dataset_kws={"chunks": {"x": -1, "y": "auto"}, "engine": "netcdf4"}
+        ... )
+
         For non-default coordinate names, use the ``coordinate_vars`` argument.
 
         >>> dset = xr.Dataset(
@@ -568,26 +577,29 @@ def from_xarray_raster(
         >>> dset = dset.expand_dims(time=[numpy.datetime64("2000-01-01")])
         >>> hazard = Hazard.from_xarray_raster(dset, "", "")
         """
+        reader_kwargs = {
+            "intensity": intensity,
+            "coordinate_vars": coordinate_vars,
+            "data_vars": data_vars,
+            "crs": crs,
+            "rechunk": rechunk,
+        }
         if not isinstance(data, xr.Dataset):
-            if isinstance(data, (pathlib.Path, str)):
+            if isinstance(data, xr.DataArray):
                 raise TypeError(
-                    "Passing a path to this classmethod is not supported. "
-                    "Use Hazard.from_xarray_raster_file instead."
+                    "This method only supports passing xr.Dataset. Consider promoting "
+                    "your xr.DataArray to a Dataset."
                 )
+            reader = HazardXarrayReader.from_file(
+                filename=data, open_dataset_kws=open_dataset_kws, **reader_kwargs
+            )
+        else:
+            reader = HazardXarrayReader(data=data, **reader_kwargs)
 
-            raise TypeError("This method only supports xarray.Dataset as input data")
-
-        reader = HazardXarrayReader(
-            data=data,
-            hazard_type=hazard_type,
-            intensity_unit=intensity_unit,
-            intensity=intensity,
-            coordinate_vars=coordinate_vars,
-            data_vars=data_vars,
-            crs=crs,
-            rechunk=rechunk,
-        )
-        kwargs = reader.get_hazard_kwargs()
+        kwargs = reader.get_hazard_kwargs() | {
+            "haz_type": hazard_type,
+            "units": intensity_unit,
+        }
         return cls(**cls._check_and_cast_attrs(kwargs))
 
     @staticmethod

climada/hazard/test/test_xarray.py

@@ -46,13 +46,13 @@ def setUpClass(cls):
         cls.time = np.array([dt.datetime(1999, 1, 1), dt.datetime(2000, 1, 1)])
         cls.latitude = np.array([0, 1])
         cls.longitude = np.array([0, 1, 2])
-        dset = xr.Dataset(
+        cls.dset = xr.Dataset(
             {
                 "intensity": (["time", "latitude", "longitude"], cls.intensity),
             },
             dict(time=cls.time, latitude=cls.latitude, longitude=cls.longitude),
         )
-        dset.to_netcdf(cls.netcdf_path)
+        cls.dset.to_netcdf(cls.netcdf_path)
 
     @classmethod
     def tearDownClass(cls):
@@ -108,49 +108,49 @@ def _assert_default_types(self, hazard):
 
     def test_load_path(self):
         """Load the data with path as argument"""
+        hazard = Hazard.from_xarray_raster(self.netcdf_path, "", "")
+        self._assert_default(hazard)
+
+        # Check deprecated method
         hazard = Hazard.from_xarray_raster_file(self.netcdf_path, "", "")
         self._assert_default(hazard)
 
         # Check wrong paths
-        with self.assertRaises(FileNotFoundError) as cm:
-            Hazard.from_xarray_raster_file("file-does-not-exist.nc", "", "")
-        self.assertIn("file-does-not-exist.nc", str(cm.exception))
-        with self.assertRaises(KeyError) as cm:
-            Hazard.from_xarray_raster_file(
+        with self.assertRaisesRegex(FileNotFoundError, "file-does-not-exist.nc"):
+            Hazard.from_xarray_raster("file-does-not-exist.nc", "", "")
+        with self.assertRaisesRegex(KeyError, "wrong-intensity-path"):
+            Hazard.from_xarray_raster(
                 self.netcdf_path, "", "", intensity="wrong-intensity-path"
             )
-        self.assertIn("wrong-intensity-path", str(cm.exception))
 
-    def test_load_dataset(self):
+    @patch("climada.hazard.xarray.xr.open_dataset")
+    def test_load_dataset(self, open_dataset_mock):
         """Load the data from an opened dataset as argument"""
+        open_dataset_mock.return_value.__enter__.return_value = self.dset
 
-        def _load_and_assert(chunks):
-            with xr.open_dataset(self.netcdf_path, chunks=chunks) as dataset:
-                hazard = Hazard.from_xarray_raster(dataset, "", "")
-                self._assert_default(hazard)
+        def _load_and_assert(**kwargs):
+            hazard = Hazard.from_xarray_raster(
+                self.netcdf_path, "", "", open_dataset_kws=kwargs
+            )
+            self._assert_default(hazard)
 
-        _load_and_assert(chunks=None)
-        _load_and_assert(chunks=dict(latitude=1, longitude=1, time=1))
+        _load_and_assert()
+        open_dataset_mock.assert_called_once_with(self.netcdf_path, chunks="auto")
+        open_dataset_mock.reset_mock()
+        _load_and_assert(chunks=dict(latitude=1, longitude=1, time=1), engine="netcdf4")
+        open_dataset_mock.assert_called_once_with(
+            self.netcdf_path,
+            chunks=dict(latitude=1, longitude=1, time=1),
+            engine="netcdf4",
+        )
 
     def test_type_error(self):
         """Calling 'from_xarray_raster' with wrong data type should throw"""
-        # Passing a path
-        with self.assertRaises(TypeError) as cm:
-            Hazard.from_xarray_raster(self.netcdf_path, "", "")
-        self.assertIn(
-            "Use Hazard.from_xarray_raster_file instead",
-            str(cm.exception),
-        )
-
         # Passing a DataArray
-        with xr.open_dataset(self.netcdf_path) as dset, self.assertRaises(
-            TypeError
-        ) as cm:
+        with xr.open_dataset(self.netcdf_path) as dset, self.assertRaisesRegex(
+            TypeError, "This method only supports passing xr.Dataset"
+        ):
             Hazard.from_xarray_raster(dset["intensity"], "", "")
-        self.assertIn(
-            "This method only supports xarray.Dataset as input data",
-            str(cm.exception),
-        )
 
     def test_type_and_unit(self):
         """Test passing a custom type and unit"""
@@ -352,9 +352,7 @@ def test_crs(self):
 
         def test_crs_from_input(crs_input):
             crs = CRS.from_user_input(crs_input)
-            hazard = Hazard.from_xarray_raster_file(
-                self.netcdf_path, "", "", crs=crs_input
-            )
+            hazard = Hazard.from_xarray_raster(self.netcdf_path, "", "", crs=crs_input)
             self.assertEqual(hazard.centroids.geometry.crs, crs)
 
         test_crs_from_input("EPSG:3857")
@@ -366,6 +364,7 @@ def test_missing_dims(self):
         # Drop time as dimension, but not as coordinate!
         with xr.open_dataset(self.netcdf_path) as ds:
             ds = ds.isel(time=0).squeeze()
+            print(ds)
             hazard = Hazard.from_xarray_raster(ds, "", "")
             self._assert_default_types(hazard)
             np.testing.assert_array_equal(
@@ -447,7 +446,7 @@ def _assert_intensity_fraction(self, hazard):
 
     def test_dimension_naming(self):
         """Test if dimensions with different names can be read"""
-        hazard = Hazard.from_xarray_raster_file(
+        hazard = Hazard.from_xarray_raster(
             self.netcdf_path,
             "",
             "",
@@ -462,7 +461,7 @@ def test_dimension_naming(self):
 
     def test_coordinate_naming(self):
         """Test if coordinates with different names than dimensions can be read"""
-        hazard = Hazard.from_xarray_raster_file(
+        hazard = Hazard.from_xarray_raster(
             self.netcdf_path,
             "",
             "",
@@ -477,7 +476,7 @@ def test_coordinate_naming(self):
 
     def test_2D_coordinates(self):
         """Test if read method correctly handles 2D coordinates"""
-        hazard = Hazard.from_xarray_raster_file(
+        hazard = Hazard.from_xarray_raster(
             self.netcdf_path,
             "",
             "",
@@ -579,18 +578,17 @@ def test_2D_time(self):
     def test_errors(self):
         """Check if expected errors are thrown"""
         # Wrong coordinate key
-        with self.assertRaises(ValueError) as cm:
-            Hazard.from_xarray_raster_file(
+        with self.assertRaisesRegex(ValueError, "Unknown coordinates passed"):
+            Hazard.from_xarray_raster(
                 self.netcdf_path,
                 "",
                 "",
                 coordinate_vars=dict(bar="latitude", longitude="baz"),
             )
-        self.assertIn("Unknown coordinates passed: '['bar']'.", str(cm.exception))
 
         # Correctly specified, but the custom dimension does not exist
         with self.assertRaisesRegex(RuntimeError, "lalalatitude"):
-            Hazard.from_xarray_raster_file(
+            Hazard.from_xarray_raster(
                 self.netcdf_path,
                 "",
                 "",