cloudnetpy 1.96.0__tar.gz → 1.96.2__tar.gz

{cloudnetpy-1.96.0/cloudnetpy.egg-info → cloudnetpy-1.96.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloudnetpy
-Version: 1.96.0
+Version: 1.96.2
 Summary: Python package for Cloudnet processing
 Author: Simo Tukiainen
 License: MIT License
@@ -38,12 +38,12 @@ Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: atmoslib>=2.0.0
+Requires-Dist: atmoslib>=2.4.2
 Requires-Dist: ceilopyter>=0.2.0
 Requires-Dist: cloudnet-api-client
 Requires-Dist: doppy>=0.5.0
 Requires-Dist: matplotlib
-Requires-Dist: mwrpy>=1.3.5
+Requires-Dist: mwrpy>=1.7.0
 Requires-Dist: netCDF4
 Requires-Dist: requests
 Requires-Dist: rpgpy>=0.14.5

{cloudnetpy-1.96.0 → cloudnetpy-1.96.2}/cloudnetpy/categorize/attenuations/__init__.py

@@ -31,7 +31,7 @@ def calc_two_way_attenuation(
     """Calculates two-way attenuation (dB) for given specific attenuation
     (dB km-1) and height above ground level (m).
     """
-    path_lengths = path_lengths_from_ground(height_agl) * con.M_TO_KM  # km
+    path_lengths = path_lengths_from_ground(height_agl) * con.M_TO_KM
     one_way_attenuation = specific_attenuation * path_lengths
     accumulated_attenuation = ma.cumsum(one_way_attenuation, axis=1)
-    return accumulated_attenuation * con.TWO_WAY
+    return accumulated_attenuation * 2  # two way

{cloudnetpy-1.96.0 → cloudnetpy-1.96.2}/cloudnetpy/categorize/classify.py

@@ -1,5 +1,6 @@
 import numpy as np
 import numpy.typing as npt
+from atmoslib.constants import T0
 from numpy import ma
 from scipy import ndimage
 
@@ -18,7 +19,6 @@ from cloudnetpy.categorize.containers import (
     ClassificationResult,
     Observations,
 )
-from cloudnetpy.constants import T0
 from cloudnetpy.products.product_tools import CategoryBits, QualityBits
 
 

{cloudnetpy-1.96.0 → cloudnetpy-1.96.2}/cloudnetpy/categorize/containers.py

@@ -4,10 +4,11 @@ from os import PathLike
 
 import numpy as np
 import numpy.typing as npt
+from atmoslib.constants import T0
 from numpy import ma
 
 from cloudnetpy import utils
-from cloudnetpy.constants import MM_H_TO_M_S, T0
+from cloudnetpy.constants import MM_H_TO_M_S
 from cloudnetpy.products.product_tools import CategoryBits
 
 from .disdrometer import Disdrometer

{cloudnetpy-1.96.0 → cloudnetpy-1.96.2}/cloudnetpy/categorize/falling.py

@@ -2,11 +2,11 @@
 
 import numpy as np
 import numpy.typing as npt
+from atmoslib.constants import T0
 from numpy import ma
 
 from cloudnetpy.categorize import atmos_utils
 from cloudnetpy.categorize.containers import ClassData
-from cloudnetpy.constants import T0
 
 
 def find_falling_hydrometeors(

{cloudnetpy-1.96.0 → cloudnetpy-1.96.2}/cloudnetpy/categorize/freezing.py

@@ -4,12 +4,12 @@ import logging
 
 import numpy as np
 import numpy.typing as npt
+from atmoslib.constants import T0
 from numpy import ma
 from scipy.interpolate import interp1d
 
 from cloudnetpy import utils
 from cloudnetpy.categorize.containers import ClassData
-from cloudnetpy.constants import T0
 
 
 def find_freezing_region(obs: ClassData, melting_layer: npt.NDArray) -> npt.NDArray:

{cloudnetpy-1.96.0 → cloudnetpy-1.96.2}/cloudnetpy/categorize/melting.py

@@ -2,13 +2,13 @@
 
 import numpy as np
 import numpy.typing as npt
+from atmoslib.constants import T0
 from numpy import ma
 from scipy.ndimage import gaussian_filter
 
 from cloudnetpy import utils
 from cloudnetpy.categorize import droplet
 from cloudnetpy.categorize.containers import ClassData
-from cloudnetpy.constants import T0
 
 
 def find_melting_layer(obs: ClassData, *, smooth: bool = True) -> npt.NDArray:

{cloudnetpy-1.96.0 → cloudnetpy-1.96.2}/cloudnetpy/categorize/radar.py

@@ -7,11 +7,10 @@ from os import PathLike
 import numpy as np
 import numpy.typing as npt
 from numpy import ma
-from scipy import constants
 
 from cloudnetpy import utils
 from cloudnetpy.categorize.attenuations import RadarAttenuation
-from cloudnetpy.constants import GHZ_TO_HZ, SEC_IN_HOUR, SPEED_OF_LIGHT
+from cloudnetpy.constants import GHZ_TO_HZ, LN_TO_DB, SEC_IN_HOUR, SPEED_OF_LIGHT
 from cloudnetpy.datasource import DataSource
 
 
@@ -265,8 +264,7 @@ class Radar(DataSource):
             """
             noise_threshold = 3
             n_pulses = _number_of_independent_pulses()
-            ln_to_log10 = 10 / np.log(10)
-            z_precision = ma.divide(ln_to_log10, np.sqrt(n_pulses)) * (
+            z_precision = ma.divide(LN_TO_DB, np.sqrt(n_pulses)) * (
                 1 + (utils.db2lin(z_power_min - z_power) / noise_threshold)
             )
 
@@ -439,8 +437,7 @@ class Radar(DataSource):
 
 
 def _prf_to_folding_velocity(prf: npt.NDArray, radar_frequency: float) -> npt.NDArray:
-    ghz_to_hz = 1e9
     if len(prf) != 1:
         msg = "Unable to determine folding velocity"
         raise RuntimeError(msg)
-    return prf[0] * constants.c / (4 * radar_frequency * ghz_to_hz)
+    return prf[0] * SPEED_OF_LIGHT / (4 * radar_frequency * GHZ_TO_HZ)

{cloudnetpy-1.96.0 → cloudnetpy-1.96.2}/cloudnetpy/constants.py

@@ -1,24 +1,21 @@
 """Constants used in Cloudnet processing."""
 
+import math
 from typing import Final
 
-# Triple point of water
-T0: Final = 273.16
+T_FREEZING: Final = 273.15
+"""Freezing point of water at standard pressure (K), i.e. 0 degrees Celsius"""
 
-# Ratio of the molecular weight of water vapor to dry air
-MW_RATIO: Final = 0.62198
-
-# Specific gas constant for dry  air (J kg-1 K-1)
-RS: Final = 287.058
-
-# ice density kg m-3
 RHO_ICE: Final = 917
+"""Ice density (kg m-3)"""
+
+RHO_WATER: Final = 1000
+"""Liquid water density (kg m-3)"""
 
-# Standard atmospheric pressure at sea level Pa
-P0: Final = 1013_25
+SPEED_OF_LIGHT: Final = 299_792_458
+"""Speed of light in vacuum (m s-1)"""
 
-# other
-SPEED_OF_LIGHT: Final = 3.0e8
+# Unit conversions
 SEC_IN_MINUTE: Final = 60
 SEC_IN_HOUR: Final = 3600
 SEC_IN_DAY: Final = 86400
@@ -35,7 +32,10 @@ MM_H_TO_M_S: Final = 1 / M_S_TO_MM_H
 GHZ_TO_HZ: Final = 1e9
 HZ_TO_GHZ: Final = 1e-9
 HPA_TO_PA: Final = 100
-PA_TO_HPA: Final = 1 / HPA_TO_PA
 KM_H_TO_M_S: Final = 1000 / SEC_IN_HOUR
-TWO_WAY: Final = 2
-G: Final = 9.80665
+
+CM_TO_KG_M2: Final = 10
+"""Liquid water equivalent cm to kg m-2"""
+
+LN_TO_DB: Final = 10 / math.log(10)
+"""Natural logarithm of a power ratio to decibels"""

{cloudnetpy-1.96.0 → cloudnetpy-1.96.2}/cloudnetpy/disdronator/lpm.py

@@ -1,4 +1,5 @@
 import datetime
+import logging
 from collections import defaultdict
 from os import PathLike
 from typing import TypeAlias
@@ -109,9 +110,18 @@ def read_lpm(filename: str | PathLike) -> tuple[npt.NDArray, dict[int, npt.NDArr
 
 
 def read_lpm_l1(
-    time: npt.NDArray, l0: dict[int, npt.NDArray], au: int | None = None
+    time: npt.NDArray,
+    l0: dict[int, npt.NDArray],
+    au: int | None = None,
+    altitude: float | None = None,
 ) -> DisdroL1:
-    area_nom = 4600 * 1000 / au if au is not None else 4560
+    if au is None:
+        area_nom = 4560.0
+        logging.warning(
+            "No AU parameter given, assuming nominal sampling area: %d mm2", area_nom
+        )
+    else:
+        area_nom = 4600.0 * 1000.0 / au
     area_eff = area_nom * (1 - D / (2 * LASER_WIDTH))
     data_raw = np.stack([l0[i] for i in range(81, 521)], axis=1).reshape(
         (len(time), len(D), len(V))
@@ -128,6 +138,7 @@ def read_lpm_l1(
         area_nom=area_nom,
         area_eff=area_eff,
         data_raw=data_raw,
+        altitude=altitude,
     )
 
 

{cloudnetpy-1.96.0 → cloudnetpy-1.96.2}/cloudnetpy/disdronator/parsivel.py

@@ -9,6 +9,7 @@ import netCDF4
 import numpy as np
 import numpy.typing as npt
 
+from cloudnetpy.constants import M_S_TO_MM_H
 from cloudnetpy.disdronator.process import DisdroL1
 from cloudnetpy.disdronator.utils import convert_to_numpy
 
@@ -434,7 +435,7 @@ def _read_parsivel2nc(filename: str | PathLike) -> ParsivelOutput:
         time = cftime.num2pydate(nc["time"][:], units=nc["time"].units)
         data = {num: nc[key][:] for key, num in PARSIVEL2NC_KEYS.items()}
         # The data logger converts mm/h to m/s, so we need to revert this.
-        data[1] *= 3600 * 1000
+        data[1] *= M_S_TO_MM_H
         # The data logger attempts to convert temperature from °C to K, but this
         # is incorrectly done only for the first value.
         data[12][0] -= 273
@@ -522,7 +523,9 @@ def read_parsivel(
     return np.array(time), convert_to_numpy(data, {}, INT_KEYS, FLOAT_KEYS)
 
 
-def read_parsivel_l1(time: npt.NDArray, l0: dict[int, npt.NDArray]) -> DisdroL1:
+def read_parsivel_l1(
+    time: npt.NDArray, l0: dict[int, npt.NDArray], altitude: float | None = None
+) -> DisdroL1:
     if 93 not in l0:
         msg = "No raw data"
         raise ValueError(msg)
@@ -544,6 +547,7 @@ def read_parsivel_l1(time: npt.NDArray, l0: dict[int, npt.NDArray]) -> DisdroL1:
         area_nom=AREA_NOM,
         area_eff=AREA_EFF,
         data_raw=data_raw,
+        altitude=altitude,
     )
 
 

{cloudnetpy-1.96.0 → cloudnetpy-1.96.2}/cloudnetpy/disdronator/process.py

@@ -4,6 +4,7 @@ import numpy as np
 import numpy.typing as npt
 from numpy import ma
 
+from cloudnetpy import constants
 from cloudnetpy.disdronator.utils import make_rain_mask
 
 
@@ -20,6 +21,7 @@ class DisdroL1:
     area_nom: float
     area_eff: npt.NDArray | None
     data_raw: npt.NDArray
+    altitude: float | None
 
 
 @dataclass
@@ -43,6 +45,7 @@ class DisdroL2:
     radar_refl: npt.NDArray
     energy_flux: npt.NDArray
     visibility: npt.NDArray
+    altitude: float | None
 
 
 def process_l2(l1: DisdroL1) -> DisdroL2:
@@ -61,10 +64,9 @@ def process_l2(l1: DisdroL1) -> DisdroL2:
     area_mm2 = (
         l1.area_eff if l1.area_eff is not None else np.repeat(l1.area_nom, n_diameter)
     )
-    area_m2 = area_mm2 * 1e-6
-    diameter_m = l1.diameter / 1000
-    interval_h = interval / 3600
-    rho_w = 1e-6  # kg mm-3
+    area_m2 = area_mm2 * constants.MM2_TO_M2
+    diameter_m = l1.diameter * constants.MM_TO_M
+    interval_h = interval / constants.SEC_IN_HOUR
 
     if spec.ndim == 2:
         number_concentration = spec / (
@@ -79,10 +81,10 @@ def process_l2(l1: DisdroL1) -> DisdroL2:
         energy_flux = (
             np.pi
             / 12
-            * rho_w
+            * constants.RHO_WATER
             * np.sum(
                 spec
-                * l1.diameter**3
+                * diameter_m**3
                 * l1.velocity**2
                 / (area_m2 * interval_h[:, np.newaxis]),
                 axis=1,
@@ -112,7 +114,7 @@ def process_l2(l1: DisdroL1) -> DisdroL2:
         fall_velocity = ma.divide(
             np.sum(l1.velocity * spec, axis=2), np.sum(spec, axis=2)
         )
-        is_rain = make_rain_mask(l1.diameter, l1.velocity)
+        is_rain = make_rain_mask(l1.diameter, l1.velocity, altitude=l1.altitude)
         spec_rain = np.copy(spec)
         spec_rain[:, ~is_rain] = 0
         rain_amount = (
@@ -136,10 +138,10 @@ def process_l2(l1: DisdroL1) -> DisdroL2:
         energy_flux = (
             np.pi
             / 12
-            * rho_w
+            * constants.RHO_WATER
             * np.sum(
                 spec_rain
-                * l1.diameter[:, np.newaxis] ** 3
+                * diameter_m[:, np.newaxis] ** 3
                 * l1.velocity**2
                 / (area_m2[:, np.newaxis] * interval_h[:, np.newaxis, np.newaxis]),
                 axis=(1, 2),
@@ -190,4 +192,5 @@ def process_l2(l1: DisdroL1) -> DisdroL2:
         radar_refl=radar_refl_db,
         energy_flux=energy_flux,
         visibility=visibility,
+        altitude=l1.altitude,
     )

{cloudnetpy-1.96.0 → cloudnetpy-1.96.2}/cloudnetpy/disdronator/rd80.py

@@ -1,4 +1,5 @@
 import datetime
+import logging
 from os import PathLike
 
 import numpy as np
@@ -35,7 +36,14 @@ def read_rd80(filename: str | PathLike) -> tuple[npt.NDArray, dict[str, npt.NDAr
     return np.array(time), convert_to_numpy(data)
 
 
-def read_rd80_l1(time: npt.NDArray, l0: dict[str, npt.NDArray]) -> DisdroL1:
+def read_rd80_l1(
+    time: npt.NDArray, l0: dict[str, npt.NDArray], altitude: float | None = None
+) -> DisdroL1:
+    if altitude is not None:
+        logging.warning(
+            "Altitude given but the correction for non-sea-level "
+            "conditions is not implemented for RD-80."
+        )
     return DisdroL1(
         diameter=D,
         diameter_spread=D_SPREAD,
@@ -48,6 +56,7 @@ def read_rd80_l1(time: npt.NDArray, l0: dict[str, npt.NDArray]) -> DisdroL1:
         area_nom=AREA_NOM,
         area_eff=None,
         data_raw=l0["n"],
+        altitude=altitude,
     )
 
 

cloudnetpy-1.96.2/cloudnetpy/disdronator/utils.py

@@ -0,0 +1,69 @@
+import logging
+from collections.abc import Container
+
+import numpy as np
+import numpy.typing as npt
+from atmoslib import isa_air_density
+from atmoslib.constants import RHO_STD
+from numpy import ma
+
+
+def convert_to_numpy(
+    data: dict,
+    fill_values: dict | None = None,
+    int_keys: Container | None = None,
+    float_keys: Container | None = None,
+) -> dict:
+    output = {}
+    for key, value in data.items():
+        arr = np.array(value)
+        if fill_values is not None and key in fill_values:
+            arr = ma.masked_where(arr == fill_values[key], arr)
+        if int_keys is not None and key in int_keys:
+            new_arr = arr.astype(np.int32)
+            if not np.all(arr == new_arr):
+                msg = "Cannot convert non-integer float to integer"
+                raise ValueError(msg)
+            arr = new_arr
+        elif float_keys is not None and key in float_keys:
+            arr = arr.astype(np.float32)
+        output[key] = arr
+    return output
+
+
+def make_rain_mask(
+    diameter: npt.NDArray[np.floating],
+    velocity: npt.NDArray[np.floating],
+    threshold: float = 0.5,
+    altitude: float | None = None,
+) -> npt.NDArray[np.bool]:
+    """Make mask for rain bins based on theoretical diameter-velocity relation.
+
+    Args:
+        diameter: Diameter (mm)
+        velocity: Velocity (m s-1)
+        threshold: Maximum error to theoretical relation (1)
+        altitude: Site altitude for optional altitude correction (m)
+
+    References:
+        Atlas, D., Srivastava, R. C., & Sekhon, R. S. (1973). Doppler Radar
+        Characteristics of Precipitation at Vertical Incidence. Reviews of
+        Geophysics and Space Physics, 11(1), 1-35.
+        https://doi.org/10.1029/RG011i001p00001
+
+        Beard, K. V. (1985). Simple Altitude Adjustments to Raindrop Velocities
+        for Doppler Radar Analysis. Journal of Atmospheric and Oceanic
+        Technology, 2(4), 468-471.
+        https://doi.org/10.1175/1520-0426(1985)002%3C0468:SAATRV%3E2.0.CO;2
+    """
+    v = 9.65 - 10.3 * np.exp(-0.6 * diameter)  # Eq. 24, Atlas et al. (1973)
+    if altitude is None:
+        logging.warning(
+            "No altitude given, no correction applied for non-sea-level conditions."
+        )
+    else:
+        rho = isa_air_density(altitude)
+        m = 0.375 + 0.025 * diameter  # Eq. 3, Beard (1985)
+        v = (RHO_STD / rho) ** m * v  # Eq. 1, Beard (1985)
+    e = np.abs((velocity - v[:, np.newaxis]) / v[:, np.newaxis])
+    return e < threshold

{cloudnetpy-1.96.0 → cloudnetpy-1.96.2}/cloudnetpy/instruments/disdrometer.py

@@ -71,7 +71,7 @@ def parsivel2nc(
             field_separator=field_separator,
             decimal_separator=decimal_separator,
         ),
-        read_parsivel_l1,
+        functools.partial(read_parsivel_l1, altitude=site_meta.get("altitude")),
         ATTRIBUTES,
         disdrometer_file,
         output_file,
@@ -117,7 +117,7 @@ def thies2nc(
     return _process_disdrometer(
         Thies,
         read_lpm,
-        functools.partial(read_lpm_l1, au=au),
+        functools.partial(read_lpm_l1, au=au, altitude=site_meta.get("altitude")),
         ATTRIBUTES,
         disdrometer_file,
         output_file,
@@ -160,7 +160,7 @@ def rd802nc(
     return _process_disdrometer(
         Rd80,
         read_rd80,
-        read_rd80_l1,
+        functools.partial(read_rd80_l1, altitude=site_meta.get("altitude")),
         RD80_ATTRIBUTES,
         input_file,
         output_file,

{cloudnetpy-1.96.0 → cloudnetpy-1.96.2}/cloudnetpy/instruments/fd12p.py

@@ -9,6 +9,7 @@ import numpy as np
 from numpy import ma
 
 from cloudnetpy import output
+from cloudnetpy.constants import MM_H_TO_M_S, MM_TO_M
 from cloudnetpy.exceptions import ValidTimeStampError
 from cloudnetpy.instruments import instruments
 from cloudnetpy.instruments.cloudnet_instrument import CSVFile
@@ -122,11 +123,9 @@ class FD12P(CSVFile):
 
     def convert_units(self) -> None:
         precipitation_rate = self.data["precipitation_rate"][:]
-        self.data["precipitation_rate"].data = (
-            precipitation_rate / 3600 / 1000
-        )  # mm/h -> m/s
+        self.data["precipitation_rate"].data = precipitation_rate * MM_H_TO_M_S
         for key in ("precipitation_amount", "snowfall_amount"):
-            self.data[key].data = self.data[key][:] / 1000  # mm -> m
+            self.data[key].data = self.data[key][:] * MM_TO_M
 
     def screen_all_masked(self) -> None:
         is_valid = np.ones_like(self.data["time"][:], dtype=np.bool_)

{cloudnetpy-1.96.0 → cloudnetpy-1.96.2}/cloudnetpy/instruments/hatpro.py

@@ -69,8 +69,8 @@ def hatpro2l1c(
 
     try:
         hatpro_raw = lev1_to_nc(
-            "1C01",
-            str(mwr_dir),
+            data_type="1C01",
+            path_to_files=str(mwr_dir),
             instrument_type=instrument_type,
             output_file=str(output_file),
             lidar_path=lidar_file,