cloudnetpy 1.80.8__py3-none-any.whl → 1.81.0__py3-none-any.whl

cloudnetpy/products/lwc.py

@@ -2,7 +2,11 @@
 method.
 """
 
+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
@@ -15,10 +19,10 @@ from cloudnetpy.products.product_tools import CategorizeBits, get_is_rain
 
 
 def generate_lwc(
-    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 liquid water content product.
 
     This function calculates cloud liquid water content using the so-called
@@ -47,6 +51,7 @@ def generate_lwc(
         Bull. Amer. Meteor. Soc., 88, 883–898, https://doi.org/10.1175/BAMS-88-6-883
 
     """
+    uuid = utils.get_uuid(uuid)
     with LwcSource(categorize_file) as lwc_source:
         lwc = Lwc(lwc_source)
         clouds = CloudAdjustor(lwc_source, lwc)
@@ -55,7 +60,7 @@ def generate_lwc(
         date = lwc_source.get_date()
         attributes = output.add_time_attribute(LWC_ATTRIBUTES, date)
         output.update_attributes(lwc_source.data, attributes)
-        return output.save_product_file(
+        output.save_product_file(
             "lwc",
             lwc_source,
             output_file,
@@ -65,6 +70,7 @@ def generate_lwc(
                 "lwp_error",
             ),
         )
+        return uuid
 
 
 class LwcSource(DataSource):
@@ -87,7 +93,7 @@ class LwcSource(DataSource):
 
     """
 
-    def __init__(self, categorize_file: str):
+    def __init__(self, categorize_file: str | PathLike) -> None:
         super().__init__(categorize_file)
         if "lwp" not in self.dataset.variables:
             msg = "Liquid water path missing from the categorize file."
@@ -102,16 +108,18 @@ class LwcSource(DataSource):
 
     def append_results(
         self,
-        lwc: np.ndarray,
-        status: np.ndarray,
-        error: np.ndarray,
+        lwc: npt.NDArray,
+        status: npt.NDArray,
+        error: npt.NDArray,
     ) -> 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")
 
     @staticmethod
-    def _get_atmosphere(categorize_file: str) -> tuple[np.ndarray, np.ndarray]:
+    def _get_atmosphere(
+        categorize_file: str | PathLike,
+    ) -> tuple[npt.NDArray, npt.NDArray]:
         fields = ["temperature", "pressure"]
         atmosphere = p_tools.interpolate_model(categorize_file, fields)
         return atmosphere["temperature"], atmosphere["pressure"]
@@ -131,7 +139,7 @@ class Lwc:
 
     """
 
-    def __init__(self, lwc_source: LwcSource):
+    def __init__(self, lwc_source: LwcSource) -> None:
         self.lwc_source = lwc_source
         self.height = lwc_source.getvar("height")
         self.is_liquid = self._get_liquid()
@@ -139,11 +147,11 @@ class Lwc:
         self.lwc = self._adiabatic_lwc_to_lwc()
         self._mask_rain()
 
-    def _get_liquid(self) -> np.ndarray:
+    def _get_liquid(self) -> npt.NDArray:
         category_bits = self.lwc_source.categorize_bits.category_bits
         return category_bits.droplet
 
-    def _init_lwc_adiabatic(self) -> np.ndarray:
+    def _init_lwc_adiabatic(self) -> npt.NDArray:
         """Returns theoretical adiabatic lwc in liquid clouds (kg/m3)."""
         lwc_dz = atmos_utils.fill_clouds_with_lwc_dz(
             *self.lwc_source.atmosphere,
@@ -151,7 +159,7 @@ class Lwc:
         )
         return atmos_utils.calc_adiabatic_lwc(lwc_dz, self.height)
 
-    def _adiabatic_lwc_to_lwc(self) -> np.ndarray:
+    def _adiabatic_lwc_to_lwc(self) -> npt.NDArray:
         """Initialises liquid water content (kg/m3).
 
         Calculates LWC for ALL profiles (rain, lwp > theoretical, etc.),
@@ -184,7 +192,7 @@ class CloudAdjustor:
 
     """
 
-    def __init__(self, lwc_source: LwcSource, lwc: Lwc):
+    def __init__(self, lwc_source: LwcSource, lwc: Lwc) -> None:
         self.lwc_source = lwc_source
         self.lwc = lwc.lwc
         self.is_liquid = lwc.is_liquid
@@ -204,7 +212,7 @@ class CloudAdjustor:
         status[self.is_liquid] = 1
         return status
 
-    def _adjust_cloud_tops(self, adjustable_clouds: np.ndarray) -> None:
+    def _adjust_cloud_tops(self, adjustable_clouds: npt.NDArray) -> None:
         """Adjusts cloud top index so that measured lwc corresponds to theoretical
         value.
         """
@@ -213,7 +221,7 @@ class CloudAdjustor:
             self._update_status(time_index)
             self._adjust_lwc(time_index, base_index)
 
-    def _update_status(self, time_ind: np.ndarray) -> None:
+    def _update_status(self, time_ind: npt.NDArray) -> None:
         alt_indices = np.where(self.is_liquid[time_ind, :])[0]
         self.status[time_ind, alt_indices] = 2
 
@@ -237,7 +245,7 @@ class CloudAdjustor:
     def _out_of_bound(self, ind: int) -> bool:
         return ind >= self.lwc.shape[1] - 1
 
-    def _find_adjustable_clouds(self) -> np.ndarray:
+    def _find_adjustable_clouds(self) -> npt.NDArray:
         top_clouds = self._find_topmost_clouds()
         detection_type = self._find_echo_combinations_in_liquid()
         detection_type[~top_clouds] = 0
@@ -245,7 +253,7 @@ class CloudAdjustor:
         top_clouds[~lidar_only_clouds, :] = 0
         return self._remove_good_profiles(top_clouds)
 
-    def _find_topmost_clouds(self) -> np.ndarray:
+    def _find_topmost_clouds(self) -> npt.NDArray:
         top_clouds = np.copy(self.is_liquid)
         cloud_edges = top_clouds[:, :-1][:, ::-1] < top_clouds[:, 1:][:, ::-1]
         topmost_bases = self.is_liquid.shape[1] - 1 - np.argmax(cloud_edges, axis=1)
@@ -253,14 +261,14 @@ class CloudAdjustor:
             top_clouds[n, :base] = 0
         return top_clouds
 
-    def _find_echo_combinations_in_liquid(self) -> np.ndarray:
+    def _find_echo_combinations_in_liquid(self) -> npt.NDArray:
         """Classifies liquid clouds by detection type: 1=lidar, 2=radar, 3=both."""
         lidar_detected = (self.is_liquid & self.echo["lidar"]).astype(int)
         radar_detected = (self.is_liquid & self.echo["radar"]).astype(int) * 2
         return lidar_detected + radar_detected
 
     @staticmethod
-    def _find_lidar_only_clouds(detection: np.ndarray) -> np.ndarray:
+    def _find_lidar_only_clouds(detection: npt.NDArray) -> npt.NDArray:
         """Finds top clouds that contain only lidar-detected pixels.
 
         Args:
@@ -274,14 +282,14 @@ class CloudAdjustor:
         sum_of_detection_type = ma.sum(detection, axis=1)
         return sum_of_cloud_pixels / sum_of_detection_type == 1
 
-    def _remove_good_profiles(self, top_clouds: np.ndarray) -> np.ndarray:
+    def _remove_good_profiles(self, top_clouds: npt.NDArray) -> npt.NDArray:
         no_rain = ~self.lwc_source.is_rain.astype(bool)
         lwp_difference = self._find_lwp_difference()
         dubious_profiles = (lwp_difference < 0) & no_rain
         top_clouds[~dubious_profiles, :] = 0
         return top_clouds
 
-    def _find_lwp_difference(self) -> np.ndarray:
+    def _find_lwp_difference(self) -> npt.NDArray:
         """Returns difference of theoretical LWP and measured LWP (g/m2).
 
         In theory, this difference should be always positive. Negative values
@@ -313,13 +321,13 @@ class LwcError:
 
     """
 
-    def __init__(self, lwc_source: LwcSource, lwc: Lwc):
+    def __init__(self, lwc_source: LwcSource, lwc: Lwc) -> None:
         self.lwc = lwc.lwc
         self.lwc_source = lwc_source
         self.error = self._calculate_lwc_error()
         self._mask_rain()
 
-    def _calculate_lwc_error(self) -> np.ndarray:
+    def _calculate_lwc_error(self) -> npt.NDArray:
         lwc_relative_error = self._calc_lwc_relative_error()
         lwp_relative_error = self._calc_lwp_relative_error()
         combined_error = self._calc_combined_error(
@@ -328,34 +336,36 @@ class LwcError:
         )
         return self._fill_error_array(combined_error)
 
-    def _calc_lwc_relative_error(self) -> np.ndarray:
+    def _calc_lwc_relative_error(self) -> npt.NDArray:
         lwc_gradient = self._calc_lwc_gradient()
         error = lwc_gradient / self.lwc / 2
         return self._limit_error(error, 5)
 
-    def _calc_lwc_gradient(self) -> np.ndarray:
+    def _calc_lwc_gradient(self) -> npt.NDArray:
         if not isinstance(self.lwc, ma.MaskedArray):
             self.lwc = ma.masked_array(self.lwc)
         gradient_elements = np.gradient(self.lwc.filled(0))
         return utils.l2norm(*gradient_elements)
 
-    def _calc_lwp_relative_error(self) -> np.ndarray:
+    def _calc_lwp_relative_error(self) -> npt.NDArray:
         err = self.lwc_source.lwp_error
         value = self.lwc_source.lwp
         error = np.divide(err, value, out=np.zeros_like(err), where=value != 0)
         return self._limit_error(error, 10)
 
     @staticmethod
-    def _limit_error(error: np.ndarray, max_value: float) -> np.ndarray:
+    def _limit_error(error: npt.NDArray, max_value: float) -> npt.NDArray:
         error[error > max_value] = max_value
         return error
 
     @staticmethod
-    def _calc_combined_error(error_2d: np.ndarray, error_1d: np.ndarray) -> np.ndarray:
+    def _calc_combined_error(
+        error_2d: npt.NDArray, error_1d: npt.NDArray
+    ) -> npt.NDArray:
         error_1d_transposed = utils.transpose(error_1d)
         return utils.l2norm(error_2d, error_1d_transposed)
 
-    def _fill_error_array(self, error_in: np.ndarray) -> ma.MaskedArray:
+    def _fill_error_array(self, error_in: npt.NDArray) -> ma.MaskedArray:
         lwc_error = ma.masked_all(self.lwc.shape)
         ind = ma.where(self.lwc)
         lwc_error[ind] = error_in[ind]

cloudnetpy/products/mwr_tools.py

@@ -1,6 +1,8 @@
 import os
 import tempfile
+from os import PathLike
 from typing import TYPE_CHECKING, Literal
+from uuid import UUID
 
 import netCDF4
 import numpy as np
@@ -19,8 +21,10 @@ if TYPE_CHECKING:
 
 
 def generate_mwr_single(
-    mwr_l1c_file: str, output_file: str, uuid: str | None = None
-) -> str:
+    mwr_l1c_file: str | PathLike,
+    output_file: str | PathLike,
+    uuid: str | UUID | None = None,
+) -> UUID:
     """Generates MWR single-pointing product including liquid water path, integrated
     water vapor, etc. from zenith measurements.
 
@@ -39,8 +43,10 @@ def generate_mwr_single(
 
 
 def generate_mwr_lhumpro(
-    mwr_l1c_file: str, output_file: str, uuid: str | None = None
-) -> str:
+    mwr_l1c_file: str | PathLike,
+    output_file: str | PathLike,
+    uuid: str | UUID | None = None,
+) -> UUID:
     """Generates LHUMPRO single-pointing product including liquid water path, integrated
     water vapor, etc. from zenith measurements.
 
@@ -59,8 +65,10 @@ def generate_mwr_lhumpro(
 
 
 def generate_mwr_multi(
-    mwr_l1c_file: str, output_file: str, uuid: str | None = None
-) -> str:
+    mwr_l1c_file: str | PathLike,
+    output_file: str | PathLike,
+    uuid: str | UUID | None = None,
+) -> UUID:
     """Generates MWR multiple-pointing product, including relative humidity profiles,
     etc. from scanning measurements.
 
@@ -77,11 +85,12 @@ def generate_mwr_multi(
 
 
 def _generate_product(
-    mwr_l1c_file: str,
-    output_file: str,
-    uuid: str | None,
+    mwr_l1c_file: str | PathLike,
+    output_file: str | PathLike,
+    uuid: str | UUID | None,
     product: Literal["multi", "single", "lhumpro"],
-) -> str:
+) -> UUID:
+    uuid = utils.get_uuid(uuid)
     fun: Callable
     if product == "multi":
         fun = gen_multi
@@ -115,28 +124,28 @@ def _generate_product(
 
 class Mwr:
     def __init__(
-        self, nc_l1c: netCDF4.Dataset, nc_l2: netCDF4.Dataset, uuid: str | None
-    ):
+        self, nc_l1c: netCDF4.Dataset, nc_l2: netCDF4.Dataset, uuid: UUID
+    ) -> None:
         self.nc_l1c = nc_l1c
         self.nc_l2 = nc_l2
-        self.uuid = uuid if uuid is not None else utils.get_uuid()
+        self.uuid = uuid
 
-    def harmonize(self, product: Literal["multi", "single"]) -> str:
+    def harmonize(self, product: Literal["multi", "single"]) -> UUID:
         self._truncate_global_attributes()
         self._copy_global_attributes()
         self._fix_variable_attributes()
         self._write_missing_global_attributes(product)
         return self.uuid
 
-    def _truncate_global_attributes(self):
+    def _truncate_global_attributes(self) -> None:
         for attr in self.nc_l2.ncattrs():
             delattr(self.nc_l2, attr)
 
-    def _copy_global_attributes(self):
+    def _copy_global_attributes(self) -> None:
         keys = ("year", "month", "day", "location", "source")
         output.copy_global(self.nc_l1c, self.nc_l2, keys)
 
-    def _fix_variable_attributes(self):
+    def _fix_variable_attributes(self) -> None:
         output.replace_attribute_with_standard_value(
             self.nc_l2,
             (
@@ -151,7 +160,9 @@ class Mwr:
             ("units", "long_name", "standard_name"),
         )
 
-    def _write_missing_global_attributes(self, product: Literal["multi", "single"]):
+    def _write_missing_global_attributes(
+        self, product: Literal["multi", "single"]
+    ) -> None:
         output.add_standard_global_attributes(self.nc_l2, self.uuid)
         product_type = "multiple-pointing" if product == "multi" else "single-pointing"
         self.nc_l2.title = f"MWR {product_type} from {self.nc_l1c.location}"
@@ -166,7 +177,7 @@ class Mwr:
         self.nc_l2.instrument_pid = self.nc_l1c.instrument_pid
 
 
-def _read_mwrpy_coeffs(mwr_l1c_file, folder: str) -> list:
+def _read_mwrpy_coeffs(mwr_l1c_file: str | PathLike, folder: str) -> list[str]:
     with netCDF4.Dataset(mwr_l1c_file) as nc:
         links = nc.mwrpy_coefficients.split(", ")
     coeffs = []

cloudnetpy/products/product_tools.py

@@ -1,10 +1,12 @@
 """General helper classes and functions for all products."""
 
 from dataclasses import dataclass
+from os import PathLike
 from typing import NamedTuple
 
 import netCDF4
 import numpy as np
+import numpy.typing as npt
 from numpy import ma
 from numpy.typing import NDArray
 
@@ -48,7 +50,7 @@ class QualityBits:
 
 
 class CategorizeBits:
-    def __init__(self, categorize_file: str):
+    def __init__(self, categorize_file: str | PathLike) -> None:
         self._categorize_file = categorize_file
         self.category_bits = self._read_category_bits()
         self.quality_bits = self._read_quality_bits()
@@ -94,7 +96,7 @@ class ProductClassification(CategorizeBits):
 
     """
 
-    def __init__(self, categorize_file: str):
+    def __init__(self, categorize_file: str | PathLike) -> None:
         super().__init__(categorize_file)
         self.is_rain = get_is_rain(categorize_file)
 
@@ -104,7 +106,7 @@ class IceClassification(ProductClassification):
     Child of ProductClassification().
     """
 
-    def __init__(self, categorize_file: str):
+    def __init__(self, categorize_file: str | PathLike) -> None:
         super().__init__(categorize_file)
         self._is_attenuated = self._find_attenuated()
         self._is_corrected = self._find_corrected()
@@ -115,28 +117,28 @@ class IceClassification(ProductClassification):
         self.ice_above_rain = self._find_ice_above_rain()
         self.clear_above_rain = self._find_clear_above_rain()
 
-    def _find_clear_above_rain(self) -> np.ndarray:
+    def _find_clear_above_rain(self) -> npt.NDArray:
         return (
             utils.transpose(self.is_rain) * ~self.is_ice
             & self.category_bits.freezing
             & ~self.category_bits.melting
         )
 
-    def _find_attenuated(self) -> np.ndarray:
+    def _find_attenuated(self) -> npt.NDArray:
         return (
             self.quality_bits.attenuated_liquid
             | self.quality_bits.attenuated_rain
             | self.quality_bits.attenuated_melting
         )
 
-    def _find_corrected(self) -> np.ndarray:
+    def _find_corrected(self) -> npt.NDArray:
         return (
             self.quality_bits.corrected_liquid
             | self.quality_bits.corrected_rain
             | self.quality_bits.corrected_melting
         )
 
-    def _find_ice(self) -> np.ndarray:
+    def _find_ice(self) -> npt.NDArray:
         return (
             self.category_bits.falling
             & self.category_bits.freezing
@@ -144,7 +146,7 @@ class IceClassification(ProductClassification):
             & ~self.category_bits.insect
         )
 
-    def _find_would_be_ice(self) -> np.ndarray:
+    def _find_would_be_ice(self) -> npt.NDArray:
         warm_falling = (
             self.category_bits.falling
             & ~self.category_bits.freezing
@@ -152,10 +154,10 @@ class IceClassification(ProductClassification):
         )
         return warm_falling | self.category_bits.melting
 
-    def _find_corrected_ice(self) -> np.ndarray:
+    def _find_corrected_ice(self) -> npt.NDArray:
         return self.is_ice & self._is_attenuated & self._is_corrected
 
-    def _find_uncorrected_ice(self) -> np.ndarray:
+    def _find_uncorrected_ice(self) -> npt.NDArray:
         uncorrected_melting = (
             self.quality_bits.attenuated_melting & ~self.quality_bits.corrected_melting
         )
@@ -171,7 +173,7 @@ class IceClassification(ProductClassification):
             & (uncorrected_melting | uncorrected_rain | uncorrected_liquid)
         )
 
-    def _find_ice_above_rain(self) -> np.ndarray:
+    def _find_ice_above_rain(self) -> npt.NDArray:
         is_rain = utils.transpose(self.is_rain)
         return (self.is_ice * is_rain) == 1
 
@@ -179,7 +181,7 @@ class IceClassification(ProductClassification):
 class IceSource(DataSource):
     """Base class for different ice products."""
 
-    def __init__(self, categorize_file: str, product: str):
+    def __init__(self, categorize_file: str | PathLike, product: str) -> None:
         super().__init__(categorize_file)
         self.radar_frequency = float(self.getvar("radar_frequency"))
         self.wl_band = utils.get_wl_band(self.radar_frequency)
@@ -230,7 +232,7 @@ class IceSource(DataSource):
             return IceCoefficients(0.669, 0.000580, -0.00706, 0.0923, -0.992)
         raise ValueError(msg)
 
-    def _convert_z(self, z_variable: str = "Z") -> np.ndarray:
+    def _convert_z(self, z_variable: str = "Z") -> npt.NDArray:
         """Calculates temperature weighted z, i.e. ice effective radius [m]."""
         if self.product not in ("iwc", "ier"):
             msg = f"Invalid product: {self.product}"
@@ -264,7 +266,7 @@ class IceSource(DataSource):
         return float(utils.lin2db(k2))
 
 
-def get_is_rain(filename: str) -> np.ndarray:
+def get_is_rain(filename: str | PathLike) -> npt.NDArray:
     # TODO: Check that this is correct
     with netCDF4.Dataset(filename) as nc:
         for name in ["rain_detected", "rainfall_rate", "rain_rate"]:
@@ -277,12 +279,14 @@ def get_is_rain(filename: str) -> np.ndarray:
     raise ValueError(msg)
 
 
-def read_nc_field(nc_file: str, name: str) -> ma.MaskedArray:
+def read_nc_field(nc_file: str | PathLike, name: str) -> ma.MaskedArray:
     with netCDF4.Dataset(nc_file) as nc:
         return nc.variables[name][:]
 
 
-def interpolate_model(cat_file: str, names: str | list) -> dict[str, np.ndarray]:
+def interpolate_model(
+    cat_file: str | PathLike, names: str | list
+) -> dict[str, npt.NDArray]:
     """Interpolates 2D model field into dense Cloudnet grid.
 
     Args:
@@ -295,7 +299,7 @@ def interpolate_model(cat_file: str, names: str | list) -> dict[str, np.ndarray]
 
     """
 
-    def _interp_field(var_name: str) -> np.ndarray:
+    def _interp_field(var_name: str) -> npt.NDArray:
         values = _read_nc_fields(
             cat_file,
             ["model_time", "model_height", var_name, "time", "height"],
@@ -306,12 +310,12 @@ def interpolate_model(cat_file: str, names: str | list) -> dict[str, np.ndarray]
     return {name: _interp_field(name) for name in names}
 
 
-def _read_nc_fields(nc_file: str, names: list[str]) -> list[ma.MaskedArray]:
+def _read_nc_fields(nc_file: str | PathLike, names: list[str]) -> list[ma.MaskedArray]:
     with netCDF4.Dataset(nc_file) as nc:
         return [nc.variables[name][:] for name in names]
 
 
-def _get_temperature(categorize_file: str) -> np.ndarray:
+def _get_temperature(categorize_file: str | PathLike) -> npt.NDArray:
     """Returns interpolated temperatures in Celsius."""
     atmosphere = interpolate_model(categorize_file, "temperature")
     return atmos_utils.k2c(atmosphere["temperature"])