Update docstrings, docs, tests, and CHANGELOG.md

Author: peanutfun

CHANGELOG.md

@@ -27,6 +27,7 @@ Removed:
 - World Bank indicator data is now downloaded directly from their API via the function `download_world_bank_indicator`, instead of relying on the `pandas-datareader` package [#1033](https://github.com/CLIMADA-project/climada_python/pull/1033)
 - `Exposures.write_hdf5` pickles geometry data in WKB format, which is faster and more sustainable. [#1051](https://github.com/CLIMADA-project/climada_python/pull/1051)
 - The online documentation has been completely overhauled, now uses PyData theme: [#977](https://github.com/CLIMADA-project/climada_python/pull/977)
+- Add `climada.hazard.xarray` module with helper structures for reading Hazard objects from `xarray` data [#1063](https://github.com/CLIMADA-project/climada_python/pull/1063)
 
 ### Fixed
 
@@ -35,6 +36,8 @@ Removed:
 
 ### Deprecated
 
+- `Hazard.from_xarray_raster_file`. Use `Hazard.from_xarray_raster` and pass the file path as `data` argument [#1063](https://github.com/CLIMADA-project/climada_python/pull/1063)
+
 ### Removed
 
 - `climada.util.interpolation.round_to_sig_digits` [#1012](https://github.com/CLIMADA-project/climada_python/pull/1012)

climada/hazard/io.py

@@ -276,21 +276,24 @@ def from_raster(
 
     @classmethod
     @deprecated(
-        details="Hazard.from_xarray_raster now supports a filepath for the 'data' "
-        "parameter"
+        6.0,
+        details="Hazard.from_xarray_raster now supports a filepath as 'data' parameter",
     )
     def from_xarray_raster_file(
         cls, filepath: Union[pathlib.Path, str], *args, **kwargs
     ):
         """Read raster-like data from a file that can be loaded with xarray
 
-        This wraps :py:meth:`~Hazard.from_xarray_raster` by first opening the target file
+        .. deprecated:: 6.0
+           Pass ``filepath`` as ``data`` argument to :py:meth:`from_xarray_raster`
+           instead.
+
+        This wraps :py:meth:`from_xarray_raster` by first opening the target file
         as xarray dataset and then passing it to that classmethod. Use this wrapper as a
         simple alternative to opening the file yourself. The signature is exactly the
         same, except for the first argument, which is replaced by a file path here.
 
-        Additional (keyword) arguments are passed to
-        :py:meth:`~Hazard.from_xarray_raster`.
+        Additional (keyword) arguments are passed to :py:meth:`from_xarray_raster`.
 
         Parameters
         ----------
@@ -302,10 +305,6 @@ def from_xarray_raster_file(
         -------
         hazard : climada.Hazard
             A hazard object created from the input data
-
-        Examples
-        --------
-
         """
         args = (filepath,) + args
         return cls.from_xarray_raster(*args, **kwargs)
@@ -356,13 +355,13 @@ def from_xarray_raster(
         intensity_unit : str
             The physical units of the intensity.
         intensity : str, optional
-            Identifier of the `xarray.DataArray` containing the hazard intensity data.
+            Identifier of the ``xarray.DataArray`` containing the hazard intensity data.
         coordinate_vars : dict(str, str), optional
             Mapping from default coordinate names to coordinate names used in the data
             to read. The default is
-            ``dict(event="time", longitude="longitude", latitude="latitude")``, as most
-            of the commonly used hazard data happens to have a "time" attribute but no
-            "event" attribute.
+            ``{"event": "time", "longitude": "longitude", "latitude": "latitude"}``, as
+            most of the commonly used hazard data happens to have a "time" attribute but
+            no "event" attribute.
         data_vars : dict(str, str), optional
             Mapping from default variable names to variable names used in the data
             to read. The default names are ``fraction``, ``hazard_type``, ``frequency``,
@@ -377,7 +376,7 @@ def from_xarray_raster(
             * ``date``: The ``event`` coordinate interpreted as date or ordinal, or
               ones if that fails (which will issue a warning).
             * ``fraction``: ``None``, which results in a value of 1.0 everywhere, see
-              :py:meth:`Hazard.__init__` for details.
+              :py:meth:`~climada.hazard.base.Hazard.__init__` for details.
             * ``hazard_type``: Empty string
             * ``frequency``: 1.0 for every event
             * ``event_name``: String representation of the event date or empty strings
@@ -386,8 +385,9 @@ def from_xarray_raster(
 
         crs : str, optional
             Identifier for the coordinate reference system of the coordinates. Defaults
-            to ``EPSG:4326`` (WGS 84), defined by ``climada.util.constants.DEF_CRS``.
-            See https://pyproj4.github.io/pyproj/dev/api/crs/crs.html#pyproj.crs.CRS.from_user_input
+            to ``"EPSG:4326"`` (WGS 84), defined by
+            :py:const:`climada.util.coordinates.DEF_CRS`. See
+            https://pyproj4.github.io/pyproj/dev/api/crs/crs.html#pyproj.crs.CRS.from_user_input
             for further information on how to specify the coordinate system.
         rechunk : bool, optional
             Rechunk the dataset before flattening. This might have serious performance
@@ -403,12 +403,12 @@ def from_xarray_raster(
 
         Returns
         -------
-        hazard : climada.Hazard
+        Hazard
             A hazard object created from the input data
 
         See Also
         --------
-        :py:class:`HazardXarrayReader`
+        :py:class:`climada.hazard.xarray.HazardXarrayReader`
             The helper class used to read the data.
 
         Notes
@@ -426,8 +426,9 @@ def from_xarray_raster(
           ``data_vars``` parameter documentation above.
         * To avoid confusion in the call signature, several parameters are keyword-only
           arguments.
-        * The attributes ``Hazard.haz_type`` and ``Hazard.unit`` currently cannot be
-          read from the Dataset. Use the method parameters to set these attributes.
+        * The attributes :py:attr:`~climada.hazard.base.Hazard.haz_type` and
+          :py:attr:`~climada.hazard.base.Hazard.units` currently cannot be read from the
+          Dataset. Use the method parameters to set these attributes.
         * This method does not read coordinate system metadata. Use the ``crs`` parameter
           to set a custom coordinate system identifier.
 

climada/hazard/test/test_xarray.py

@@ -42,7 +42,7 @@ def setUpClass(cls):
         """Write a simple NetCDF file to read"""
         cls.tempdir = TemporaryDirectory()
         cls.netcdf_path = Path(cls.tempdir.name) / "default.nc"
-        cls.intensity = np.array([[[0, 1, 2], [3, 4, 5]], [[6, 7, 8], [9, 10, 11]]])
+        cls.intensity = np.array([[[0, 1, 2], [3, 4, 5]], [[6, 7, 8], [9, 10, np.nan]]])
         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])
@@ -84,8 +84,10 @@ def _assert_default_values(self, hazard):
         self.assertEqual(hazard.centroids.geometry.crs, DEF_CRS)
 
         # Intensity data
+        # NOTE: NaN converted to zero
+        self.assertEqual(hazard.intensity.nnz, 10)
         np.testing.assert_array_equal(
-            hazard.intensity.toarray(), [[0, 1, 2, 3, 4, 5], [6, 7, 8, 9, 10, 11]]
+            hazard.intensity.toarray(), [[0, 1, 2, 3, 4, 5], [6, 7, 8, 9, 10, 0]]
         )
 
         # Fraction default
@@ -172,7 +174,7 @@ def test_event_no_time(self):
             hazard = Hazard.from_xarray_raster(dataset, "", "")
             self._assert_default_types(hazard)
             np.testing.assert_array_equal(
-                hazard.intensity.toarray(), [[0, 1, 2, 3, 4, 5], [6, 7, 8, 9, 10, 11]]
+                hazard.intensity.toarray(), [[0, 1, 2, 3, 4, 5], [6, 7, 8, 9, 10, 0]]
             )
             np.testing.assert_array_equal(hazard.date, time)
             np.testing.assert_array_equal(hazard.event_name, np.full(size, ""))

climada/hazard/xarray.py

@@ -148,10 +148,11 @@ def load_from_xarray_or_return_default(
     """Load data for a single Hazard attribute or return the default value
 
     Does the following based on the ``user_key``:
+
     * If the key is an empty string, return the default value
     * If the key is a non-empty string, load the data for that key and return it.
-    * If the key is ``None``, look for the ``default_key`` in the data. If it
-        exists, return that data. If not, return the default value.
+    * If the key is ``None``, look for the ``default_key`` in the data. If it exists,
+      return that data. If not, return the default value.
 
     Parameters
     ----------
@@ -169,7 +170,7 @@ def load_from_xarray_or_return_default(
 
     Returns
     -------
-    The object that will be stored in the ``Hazard`` attribute ``hazard_attr``.
+    The object that will be stored in the ``Hazard`` attribute with name ``hazard_attr``
 
     Raises
     ------

doc/api/climada/climada.hazard.rst

@@ -22,6 +22,16 @@ climada\.hazard\.io module
     :undoc-members:
     :show-inheritance:
 
+climada\.hazard\.xarray module
+------------------------------
+
+Helper module ro read xarray data as Hazard.
+
+.. automodule:: climada.hazard.xarray
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 climada\.hazard\.isimip\_data module
 ------------------------------------