cloudnetpy 1.96.8__tar.gz → 1.97.1__tar.gz

{cloudnetpy-1.96.8/cloudnetpy.egg-info → cloudnetpy-1.97.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloudnetpy
-Version: 1.96.8
+Version: 1.97.1
 Summary: Python package for Cloudnet processing
 Author: Simo Tukiainen
 License: MIT License

{cloudnetpy-1.96.8 → cloudnetpy-1.97.1}/cloudnetpy/categorize/radar.py

@@ -270,6 +270,7 @@ class Radar(DataSource):
 
             z_error = utils.l2norm(
                 z_precision,
+                attenuations.gas.error,
                 attenuations.liquid.error.filled(0),
                 attenuations.rain.error.filled(0),
                 attenuations.melting.error.filled(0),

{cloudnetpy-1.96.8 → cloudnetpy-1.97.1}/cloudnetpy/plotting/plot_meta.py

@@ -668,7 +668,7 @@ ATTRIBUTES = {
         ),
         "lwc_error": PlotMeta(
             cmap="RdYlGn_r",
-            plot_range=(0, 2),
+            plot_range=(0, 100),
         ),
         "lwc_retrieval_status": PlotMeta(
             clabel=_CLABEL["lwc_retrieval_status"],

{cloudnetpy-1.96.8 → cloudnetpy-1.97.1}/cloudnetpy/plotting/plotting.py

@@ -464,6 +464,7 @@ class Plot:
             "air_pressure": (multiply, 0.01, "hPa"),
             "relative_humidity": (multiply, 100, "%"),
             "rh": (multiply, 100, "%"),
+            "lwc_error": (multiply, 100, "%"),
             "rainfall_amount": (multiply, con.M_TO_MM, "mm"),
             "snowfall_amount": (multiply, con.M_TO_MM, "mm"),
             "precipitation_amount": (multiply, con.M_TO_MM, "mm"),
@@ -725,29 +726,28 @@ class Plot2D(Plot):
         if figure_data.is_mwrpy_product():
             self._fill_flagged_data(figure_data)
 
-        if figure_data.variables[0].name == "signal_source_status":
+        if self.sub_plot.variable.name == "signal_source_status":
             self._indicate_rainy_profiles(figure_data)
 
     def _indicate_rainy_profiles(self, figure_data: FigureData) -> None:
         if "rain_detected" not in figure_data.file.variables:
             return
-        rain = figure_data.file.variables["rain_detected"][:]
-        is_rain: ma.MaskedArray = ma.array(np.zeros_like(rain), mask=(rain == 0))
-        if is_rain.mask.all():
+        is_rain = figure_data.file.variables["rain_detected"][:] == 1
+        if not is_rain.any():
             return
-        self._ax.plot(
+        self._ax.fill_between(
             figure_data.time,
-            is_rain,
-            color="red",
-            marker="|",
-            linestyle="None",
-            markersize=10,
-            zorder=-999,
+            *self._get_y_limits(),
+            where=is_rain,
+            step="mid",
+            facecolor="#1f77b4",
+            alpha=0.18,
+            linewidth=0,
             label="Rain",
+            zorder=_get_zorder("flags"),
         )
         self._ax.legend(
-            markerscale=0.75,
-            numpoints=1,
+            loc="upper right",
             frameon=False,
         )
 

{cloudnetpy-1.96.8 → cloudnetpy-1.97.1}/cloudnetpy/products/ier.py

@@ -20,7 +20,7 @@ def generate_ier(
 ) -> UUID:
     """Generates Cloudnet ice effective radius product.
 
-    This function calculates ice particle effective radius using the Grieche
+    This function calculates ice particle effective radius using the Griesche
     et al. 2020 method which uses Hogan et al. 2006 to estimate ice water content
     and alpha from Delanoë et al. 2007. In this method, effective radius
     of ice particles is calculated from attenuated-corrected radar reflectivity

{cloudnetpy-1.96.8 → cloudnetpy-1.97.1}/cloudnetpy/products/iwc.py

@@ -3,14 +3,20 @@
 from os import PathLike
 from uuid import UUID
 
+import numpy as np
 import numpy.typing as npt
 from numpy import ma
 
 from cloudnetpy import output, utils
-from cloudnetpy.constants import G_TO_KG
 from cloudnetpy.metadata import MetaData
 from cloudnetpy.products.product_tools import IceClassification, IceSource
 
+# Rms error (dB) of the Z-T retrieval at warm (-20...-10 degC) and cold
+# (< -40 degC) temperatures from Hogan et al. (2006).
+RETRIEVAL_UNCERTAINTY = {"Ka": (1.5, 3.0), "W": (1.9, 2.8)}
+T_WARM = -15.0  # degC
+T_COLD = -40.0  # degC
+
 
 def generate_iwc(
     categorize_file: str | PathLike,
@@ -50,12 +56,12 @@ def generate_iwc(
         iwc_source.append_icy_data(ice_classification)
         iwc_source.append_bias()
         iwc_source.append_sensitivity()
-        lwp_prior, bias = iwc_source.append_error(ice_classification)
+        iwc_source.append_error(ice_classification)
         iwc_source.append_status(ice_classification)
         date = iwc_source.get_date()
         attributes = output.add_time_attribute(IWC_ATTRIBUTES, date)
         attributes = _add_iwc_comment(attributes, iwc_source)
-        attributes = _add_iwc_error_comment(attributes, lwp_prior, bias)
+        attributes = _add_iwc_error_comment(attributes, iwc_source.wl_band)
         output.update_attributes(iwc_source.data, attributes)
         output.save_product_file(product, iwc_source, output_file, uuid)
         return uuid
@@ -74,9 +80,7 @@ class IwcSource(IceSource):
         bias = self.getvar("Z_bias") * self.coefficients.Z * 10
         self.append_data(bias, f"{self.product}_bias")
 
-    def append_error(
-        self, ice_classification: IceClassification
-    ) -> tuple[float, float]:
+    def append_error(self, ice_classification: IceClassification) -> None:
         """Estimates error of ice water content."""
 
         def _calc_random_error() -> npt.NDArray:
@@ -84,39 +88,28 @@ class IwcSource(IceSource):
             scaled_temperature += self.coefficients.Z
             return self.getvar("Z_error") * scaled_temperature * 10
 
-        def _calc_error_in_uncorrected_ice() -> float:
-            spec_liq_atten = 1.0 if self.wl_band == "Ka" else 4.5
-            liq_atten_scaled = spec_liq_atten * self.coefficients.Z
-            return lwp_prior * G_TO_KG * liq_atten_scaled * 2 * 10
+        def _calc_retrieval_uncertainty() -> npt.NDArray:
+            # Linear in temperature between the cold and warm values
+            warm, cold = RETRIEVAL_UNCERTAINTY[self.wl_band]
+            return np.interp(self.temperature, [T_COLD, T_WARM], [cold, warm])
 
-        lwp_prior = 250  # g m-2
-        retrieval_uncertainty = 1.7  # dB
+        retrieval_uncertainty = _calc_retrieval_uncertainty()
         random_error = _calc_random_error()
-        error_uncorrected = _calc_error_in_uncorrected_ice()
         iwc_error = utils.l2norm(retrieval_uncertainty, random_error)
-        iwc_error[ice_classification.uncorrected_ice] = utils.l2norm(
-            retrieval_uncertainty,
-            error_uncorrected,
-        )
         iwc_error[~ice_classification.is_ice | ice_classification.uncorrected_ice] = (
             ma.masked
         )
         self.append_data(iwc_error, f"{self.product}_error")
-        return lwp_prior, retrieval_uncertainty
 
 
-def _add_iwc_error_comment(
-    attributes: dict, lwp_prior: float, uncertainty: float
-) -> dict:
+def _add_iwc_error_comment(attributes: dict, wl_band: str) -> dict:
+    warm, cold = RETRIEVAL_UNCERTAINTY[wl_band]
     attributes["iwc_error"] = attributes["iwc_error"]._replace(
         comment="This variable is an estimate of the one-standard-deviation random\n"
         "error in ice water content due to both the uncertainty of the retrieval\n"
-        f"(about {uncertainty} dB), and the random error in radar reflectivity\n"
-        "factor from which ice water content was calculated. When liquid water is\n"
-        "present beneath the ice but no microwave radiometer data were available to\n"
-        "correct for the associated attenuation, the error also includes a\n"
-        f"contribution equivalent to approximately {lwp_prior} g m-2 of liquid water\n"
-        "path being uncorrected for.",
+        f"(about {warm} dB between -20 and -10 degC, rising linearly to {cold} dB\n"
+        f"at -40 degC and below), and the random error in radar reflectivity\n"
+        "factor from which ice water content was calculated.",
     )
     return attributes
 
@@ -141,17 +134,15 @@ def _add_iwc_comment(attributes: dict, iwc: IwcSource) -> dict:
         "supercooled drizzle will erroneously be identified as ice. Missing data\n"
         "indicates either that ice cloud was present but it was only detected by\n"
         "the lidar so its ice water content could not be estimated, or that there\n"
-        "was rain below the ice associated with uncertain attenuation of the\n"
-        "reflectivities in the ice. Note that where microwave radiometer liquid water\n"
-        "path was available it was used to correct the radar for liquid attenuation\n"
-        "when liquid cloud occurred below the ice; this is indicated a value of 3\n"
-        "in the iwc_retrieval_status variable. There is some uncertainty in this\n"
-        "procedure which is reflected by an increase in the associated values\n"
-        "in the iwc_error variable. When microwave radiometer data were not available\n"
-        "and liquid cloud occurred below the ice, the retrieval was still performed\n"
-        "but its reliability is questionable due to the uncorrected liquid water\n"
-        "attenuation. This is indicated by a value of 2 in the iwc_retrieval_status\n"
-        "variable, and an increase in the value of the iwc_error variable.",
+        "was liquid cloud, rain or melting layer below the ice whose attenuation\n"
+        "could not be corrected for. Where microwave radiometer liquid water path\n"
+        "and disdrometer rainfall rate were available they were used to correct the\n"
+        "radar for liquid, rain and melting layer attenuation; this is indicated by\n"
+        "a value of 3 in the iwc_retrieval_status variable. There is some uncertainty\n"
+        "in this procedure which is reflected by an increase in the associated\n"
+        "values in the iwc_error variable. Where no correction was possible, no\n"
+        "retrieval was performed; this is indicated by a value of 2 in the\n"
+        "iwc_retrieval_status variable.",
     )
     return attributes
 
@@ -177,8 +168,8 @@ DEFINITIONS = {
         {
             0: """No ice present.""",
             1: """Reliable retrieval.""",
-            2: """Unreliable retrieval due to uncorrected liquid, rain or
-                  melting attenuation.""",
+            2: """No retrieval due to uncorrected liquid, rain or melting
+                  layer attenuation.""",
             3: """Retrieval performed with radar corrected for liquid, rain and
                   melting attenuation.""",
             4: """Ice detected only by the lidar.""",

{cloudnetpy-1.96.8 → cloudnetpy-1.97.1}/cloudnetpy/products/lwc.py

@@ -117,7 +117,7 @@ class LwcSource(DataSource):
     ) -> None:
         self.append_data(lwc, "lwc", units="kg m-3")
         self.append_data(status, "lwc_retrieval_status")
-        self.append_data(error, "lwc_error", units="dB")
+        self.append_data(error, "lwc_error", units="1")
 
     @staticmethod
     def _get_atmosphere(
@@ -348,15 +348,16 @@ class LwcError:
         return self._fill_error_array(combined_error)
 
     def _calc_lwc_relative_error(self) -> npt.NDArray:
+        # Half a range gate uncertainty in cloud base and top height
         lwc_gradient = self._calc_lwc_gradient()
         error = lwc_gradient / self.lwc / 2
         return self._limit_error(error, 5)
 
     def _calc_lwc_gradient(self) -> npt.NDArray:
+        """Returns absolute vertical gradient of LWC per range gate."""
         if not isinstance(self.lwc, ma.MaskedArray):
             self.lwc = ma.array(self.lwc)
-        gradient_elements = np.gradient(self.lwc.filled(0))
-        return utils.l2norm(*gradient_elements)
+        return np.abs(np.gradient(self.lwc.filled(0), axis=1))
 
     def _calc_lwp_relative_error(self) -> npt.NDArray:
         err = self.lwc_source.lwp_error
@@ -412,9 +413,15 @@ COMMENTS = {
         "   liquid layers is difficult to ascertain."
     ),
     "lwc_error": (
-        "This variable is an estimate of the random error in liquid water content\n"
-        "due to the uncertainty in the microwave radiometer liquid water path\n"
-        "retrieval and the uncertainty in cloud base and/or cloud top height."
+        "This variable is an estimate of the one-standard-deviation random error\n"
+        "in liquid water content, expressed as a fraction of the liquid water\n"
+        "content. It combines the relative uncertainty in the microwave radiometer\n"
+        "liquid water path retrieval (limited to 10) and the uncertainty in cloud\n"
+        "base and cloud top height, taken as half a range gate and estimated from\n"
+        "the vertical gradient of liquid water content (limited to 5). If the liquid\n"
+        "layer is detected by the lidar only, there is the potential for cloud top\n"
+        "height to be underestimated. The error contribution from using the model\n"
+        "temperature and pressure at cloud base is assumed to be negligible."
     ),
     "lwc_retrieval_status": (
         "This variable describes whether a retrieval was performed for each pixel,\n"
@@ -469,9 +476,9 @@ LWC_ATTRIBUTES = {
         dimensions=("time", "height"),
     ),
     "lwc_error": MetaData(
-        long_name="Random error in liquid water content, one standard deviation",
+        long_name="Relative random error in liquid water content",
         comment=COMMENTS["lwc_error"],
-        units="dB",
+        units="1",
         dimensions=("time", "height"),
     ),
     "lwc_retrieval_status": MetaData(

{cloudnetpy-1.96.8 → cloudnetpy-1.97.1}/cloudnetpy/version.py

@@ -1,4 +1,4 @@
 MAJOR = 1
-MINOR = 96
-PATCH = 8
+MINOR = 97
+PATCH = 1
 __version__ = f"{MAJOR}.{MINOR}.{PATCH}"

{cloudnetpy-1.96.8 → cloudnetpy-1.97.1/cloudnetpy.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloudnetpy
-Version: 1.96.8
+Version: 1.97.1
 Summary: Python package for Cloudnet processing
 Author: Simo Tukiainen
 License: MIT License