cloudnetpy 1.49.9__py3-none-any.whl → 1.87.3__py3-none-any.whl

cloudnetpy/products/ier.py

@@ -1,15 +1,23 @@
 """Module for creating Cloudnet ice effective radius file using Z-T method."""
+
+from os import PathLike
+from uuid import UUID
+
 import numpy as np
 from numpy import ma
 
-from cloudnetpy import constants, output, utils
+from cloudnetpy import constants, output
 from cloudnetpy.metadata import MetaData
+from cloudnetpy.products.iwc import DEFINITIONS as IWC_DEFINITION
 from cloudnetpy.products.product_tools import IceClassification, IceSource
+from cloudnetpy.utils import get_uuid
 
 
 def generate_ier(
-    categorize_file: str, output_file: str, uuid: str | None = None
-) -> str:
+    categorize_file: str | PathLike,
+    output_file: str | PathLike,
+    uuid: str | UUID | None = None,
+) -> UUID:
     """Generates Cloudnet ice effective radius product.
 
     This function calculates ice particle effective radius using the Grieche
@@ -51,41 +59,39 @@ def generate_ier(
         from https://doi.org/10.5194/amt-13-5335-2020,
 
     """
+    uuid = get_uuid(uuid)
     product = "ier"
     with IerSource(categorize_file, product) as ier_source:
         ice_classification = IceClassification(categorize_file)
-        ier_source.append_main_variable_including_rain(ice_classification)
-        ier_source.append_main_variable(ice_classification)
+        ier_source.append_icy_data(ice_classification)
         ier_source.convert_units()
         ier_source.append_status(ice_classification)
-        ier_source.append_ier_error(ice_classification)
+        ier_source.append_ier_error()
         date = ier_source.get_date()
         attributes = output.add_time_attribute(IER_ATTRIBUTES, date)
         attributes = _add_ier_comment(attributes, ier_source)
         output.update_attributes(ier_source.data, attributes)
-        uuid = output.save_product_file(product, ier_source, output_file, uuid)
-    return uuid
+        output.save_product_file(product, ier_source, output_file, uuid)
+        return uuid
 
 
 class IerSource(IceSource):
     """Data container for ice effective radius calculations."""
 
-    def convert_units(self):
+    def convert_units(self) -> None:
         """Convert um to m."""
-        for prod in ("ier", "ier_inc_rain"):
-            self.data[prod].data[:] /= 1e6
+        self.data["ier"].data[:] /= 1e6
 
-    def append_ier_error(self, ice_classification: IceClassification) -> None:
-        error = ma.copy(self.data[f"{self.product}_inc_rain"][:])
-        error[ice_classification.ice_above_rain] = ma.masked
+    def append_ier_error(self) -> None:
+        error = ma.copy(self.data[f"{self.product}"][:])
         error = error * np.sqrt(0.4**2 + 0.4**2)
         self.append_data(error, f"{self.product}_error")
 
 
 def _add_ier_comment(attributes: dict, ier: IerSource) -> dict:
-    freq = utils.get_frequency(ier.wl_band)
+    freq = round(ier.radar_frequency, 3)
     coeffs = ier.coefficients
-    factor = np.round((coeffs[0] / 0.93), 3)
+    factor = round(coeffs[0] / 0.93, 3)
     attributes["ier"] = attributes["ier"]._replace(
         comment=f"This variable was calculated from the {freq}-GHz radar\n"
         f"reflectivity factor after correction for gaseous attenuation,\n"
@@ -103,9 +109,7 @@ def _add_ier_comment(attributes: dict, ier: IerSource) -> dict:
         "data has diagnosed that the radar echo is due to ice, but note\n"
         "that in some cases supercooled drizzle will erroneously be identified\n"
         "as ice. Missing data indicates either that ice cloud was present but it was\n"
-        "only detected by the lidar so its ice water content could not be estimated,\n"
-        "or than there was rain below the ice associated with uncertain attenuation\n"
-        "of the reflectivities in the ice.\n"
+        "only detected by the lidar so its ice water content could not be estimated."
     )
     return attributes
 
@@ -120,55 +124,28 @@ COMMENTS = {
         "This variable describes whether a retrieval was performed\n"
         "for each pixel, and its associated quality."
     ),
-    "ier_inc_rain": (
-        "This variable is the same as ier but it also contains ier values\n"
-        "above rain. The ier values above rain have been severely affected\n"
-        "by attenuation and should be used when the effect of attenuation\n"
-        "is being studied."
-    ),
 }
 
-DEFINITIONS = {
-    "ier_retrieval_status": (
-        "\n"
-        "Value 0: No ice present.\n"
-        "Value 1: Reliable retrieval.\n"
-        "Value 2: Unreliable retrieval due to uncorrected attenuation from liquid\n"
-        "         water below the ice (no liquid water path measurement available).\n"
-        "Value 3: Retrieval performed but radar corrected for liquid attenuation\n"
-        "         using radiometer liquid water path which is not always accurate.\n"
-        "Value 4: Ice detected only by the lidar.\n"
-        "Value 5: Ice detected by radar but rain below so no retrieval performed\n"
-        "         due to very uncertain attenuation.\n"
-        "Value 6: Clear sky above rain wet-bulb temperature less than 0degC: if\n"
-        "         rain attenuation were strong then ice could be present but\n"
-        "         undetected."
-        "Value 7: Drizzle or rain that would have been classified as ice if\n"
-        "          the wet-bulb temperature were less than 0degC: may be ice\n"
-        "          if temperature is in error."
-    ),
-}
+DEFINITIONS = {"ier_retrieval_status": IWC_DEFINITION["iwc_retrieval_status"]}
 
 IER_ATTRIBUTES = {
     "ier": MetaData(
         long_name="Ice effective radius",
         units="m",
         ancillary_variables="ier_error",
-    ),
-    "ier_inc_rain": MetaData(
-        long_name="Ice effective radius including rain",
-        units="m",
-        comment=COMMENTS["ier_inc_rain"],
+        dimensions=("time", "height"),
     ),
     "ier_error": MetaData(
         long_name="Random error in ice effective radius",
         units="m",
         comment=COMMENTS["ier_error"],
+        dimensions=("time", "height"),
     ),
     "ier_retrieval_status": MetaData(
         long_name="Ice effective radius retrieval status",
         comment=COMMENTS["ier_retrieval_status"],
         definition=DEFINITIONS["ier_retrieval_status"],
         units="1",
+        dimensions=("time", "height"),
     ),
 }

cloudnetpy/products/iwc.py

@@ -1,15 +1,22 @@
 """Module for creating Cloudnet ice water content file using Z-T method."""
-import numpy as np
+
+from os import PathLike
+from uuid import UUID
+
+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
 
 
 def generate_iwc(
-    categorize_file: str, output_file: str, uuid: str | None = None
-) -> str:
+    categorize_file: str | PathLike,
+    output_file: str | PathLike,
+    uuid: str | UUID | None = None,
+) -> UUID:
     """Generates Cloudnet ice water content product.
 
     This function calculates ice water content using the so-called Z-T method.
@@ -36,11 +43,11 @@ def generate_iwc(
         J. Appl. Meteor. Climatol., 45, 301–317, https://doi.org/10.1175/JAM2340.1
 
     """
+    uuid = utils.get_uuid(uuid)
     product = "iwc"
     with IwcSource(categorize_file, product) as iwc_source:
         ice_classification = IceClassification(categorize_file)
-        iwc_source.append_main_variable_including_rain(ice_classification)
-        iwc_source.append_main_variable(ice_classification)
+        iwc_source.append_icy_data(ice_classification)
         iwc_source.append_bias()
         iwc_source.append_sensitivity()
         lwp_prior, bias = iwc_source.append_error(ice_classification)
@@ -50,8 +57,8 @@ def generate_iwc(
         attributes = _add_iwc_comment(attributes, iwc_source)
         attributes = _add_iwc_error_comment(attributes, lwp_prior, bias)
         output.update_attributes(iwc_source.data, attributes)
-        uuid = output.save_product_file(product, iwc_source, output_file, uuid)
-    return uuid
+        output.save_product_file(product, iwc_source, output_file, uuid)
+        return uuid
 
 
 class IwcSource(IceSource):
@@ -67,18 +74,20 @@ 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:
+    def append_error(
+        self, ice_classification: IceClassification
+    ) -> tuple[float, float]:
         """Estimates error of ice water content."""
 
-        def _calc_random_error() -> np.ndarray:
+        def _calc_random_error() -> npt.NDArray:
             scaled_temperature = self.coefficients.ZT * self.temperature
             scaled_temperature += self.coefficients.Z
             return self.getvar("Z_error") * scaled_temperature * 10
 
-        def _calc_error_in_uncorrected_ice() -> np.ndarray:
+        def _calc_error_in_uncorrected_ice() -> float:
             spec_liq_atten = 1.0 if self.wl_band == 0 else 4.5
             liq_atten_scaled = spec_liq_atten * self.coefficients.Z
-            return lwp_prior * liq_atten_scaled * 2 * 1e-3 * 10
+            return lwp_prior * G_TO_KG * liq_atten_scaled * 2 * 10
 
         lwp_prior = 250  # g m-2
         retrieval_uncertainty = 1.7  # dB
@@ -86,16 +95,19 @@ class IwcSource(IceSource):
         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
+            retrieval_uncertainty,
+            error_uncorrected,
+        )
+        iwc_error[~ice_classification.is_ice | ice_classification.uncorrected_ice] = (
+            ma.masked
         )
-        iwc_error[
-            (~ice_classification.is_ice | ice_classification.ice_above_rain)
-        ] = 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, uncertainty: float) -> dict:
+def _add_iwc_error_comment(
+    attributes: dict, lwp_prior: float, uncertainty: float
+) -> dict:
     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"
@@ -104,15 +116,15 @@ def _add_iwc_error_comment(attributes: dict, lwp_prior, uncertainty: float) -> d
         "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."
+        "path being uncorrected for.",
     )
     return attributes
 
 
 def _add_iwc_comment(attributes: dict, iwc: IwcSource) -> dict:
-    freq = utils.get_frequency(iwc.wl_band)
+    freq = round(iwc.radar_frequency, 3)
     coeffs = iwc.coefficients
-    factor = round((coeffs[0] / 0.93) * 1000) / 1000
+    factor = round(coeffs[0] / 0.93, 3)
     attributes["iwc"] = attributes["iwc"]._replace(
         comment=f"This variable was calculated from the {freq}-GHz radar reflectivity\n"
         "factor after correction for gaseous attenuation, and temperature taken from\n"
@@ -139,7 +151,7 @@ def _add_iwc_comment(attributes: dict, iwc: IwcSource) -> dict:
         "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."
+        "variable, and an increase in the value of the iwc_error variable.",
     )
     return attributes
 
@@ -158,32 +170,27 @@ COMMENTS = {
         "This variable describes whether a retrieval was performed\n"
         "for each pixel, and its associated quality."
     ),
-    "iwc_inc_rain": (
-        "This variable is the same as iwc but it also contains iwc values\n"
-        "above rain. The iwc values above rain have been severely affected\n"
-        "by attenuation and should be used when the effect of attenuation\n"
-        "is being studied."
-    ),
 }
 
 DEFINITIONS = {
-    "iwc_retrieval_status": (
-        "\n"
-        "Value 0: No ice present.\n"
-        "Value 1: Reliable retrieval.\n"
-        "Value 2: Unreliable retrieval due to uncorrected attenuation from liquid\n"
-        "         water below the ice (no liquid water path measurement available).\n"
-        "Value 3: Retrieval performed but radar corrected for liquid attenuation\n"
-        "         using radiometer liquid water path which is not always accurate.\n"
-        "Value 4: Ice detected only by the lidar.\n"
-        "Value 5: Ice detected by radar but rain below so no retrieval performed\n"
-        "         due to very uncertain attenuation.\n"
-        "Value 6: Clear sky above rain and wet-bulb temperature less than 0degC:\n"
-        "         if rain attenuation is strong, ice could be present but undetected.\n"
-        "Value 7: Drizzle or rain that would have been classified as ice if the\n"
-        "         wet-bulb temperature were less than 0degC: may be ice if\n"
-        "         temperature is in error."
-    )
+    "iwc_retrieval_status": utils.status_field_definition(
+        {
+            0: """No ice present.""",
+            1: """Reliable retrieval.""",
+            2: """Unreliable retrieval due to uncorrected liquid, rain or
+                  melting attenuation.""",
+            3: """Retrieval performed with radar corrected for liquid, rain and
+                  melting attenuation.""",
+            4: """Ice detected only by the lidar.""",
+            5: """Uncorrected rain attenuation (deprecated).""",
+            6: """Clear sky above rain and wet-bulb temperature less than 0degC:
+                  if rain attenuation is strong, ice could be present but
+                  undetected.""",
+            7: """Drizzle or rain that would have been classified as ice if the
+                  wet-bulb temperature were less than 0degC: may be ice if
+                  temperature is in error.""",
+        }
+    ),
 }
 
 IWC_ATTRIBUTES = {
@@ -191,30 +198,30 @@ IWC_ATTRIBUTES = {
         long_name="Ice water content",
         units="kg m-3",
         ancillary_variables="iwc_error iwc_sensitivity iwc_bias",
-    ),
-    "iwc_inc_rain": MetaData(
-        long_name="Ice water content including rain",
-        units="kg m-3",
-        comment=COMMENTS["iwc_inc_rain"],
+        dimensions=("time", "height"),
     ),
     "iwc_error": MetaData(
         long_name="Random error in ice water content",
         units="dB",
+        dimensions=("time", "height"),
     ),
     "iwc_bias": MetaData(
         long_name="Possible bias in ice water content",
         units="dB",
         comment=COMMENTS["iwc_bias"],
+        dimensions=None,
     ),
     "iwc_sensitivity": MetaData(
         long_name="Minimum detectable ice water content",
         units="kg m-3",
         comment=COMMENTS["iwc_sensitivity"],
+        dimensions=("height",),
     ),
     "iwc_retrieval_status": MetaData(
         long_name="Ice water content retrieval status",
         comment=COMMENTS["iwc_retrieval_status"],
         definition=DEFINITIONS["iwc_retrieval_status"],
         units="1",
+        dimensions=("time", "height"),
     ),
 }