cloudnetpy 1.95.4__tar.gz → 1.95.6__tar.gz

{cloudnetpy-1.95.4/cloudnetpy.egg-info → cloudnetpy-1.95.6}/PKG-INFO

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

{cloudnetpy-1.95.4 → cloudnetpy-1.95.6}/cloudnetpy/arm.py

@@ -61,15 +61,22 @@ class ArmInstrument(NamedTuple):
 
 
 # In order of preference within each product; the first with files is used.
+# Raw moments are preferred over ARM corrected products for consistency. The
+# b1-level KAZR moments are identical to the a1-level ones except for the
+# reflectivity calibration applied by ARM.
 ARM_INSTRUMENTS: Final = (
+    # KAZR2 calibrated moments (2020 onwards, hourly files, months of delay)
+    ArmInstrument("radar", "kazr", "kazrcfrgeqc.b1", kazr2nc, multi_file=True),
+    # KAZR2 calibrated moments at ENA
+    ArmInstrument("radar", "kazr", "kazr2cfrgeqc.b1", kazr2nc, multi_file=True),
     # KAZR2 (approx. 2019 onwards, hourly files)
     ArmInstrument("radar", "kazr", "kazrcfrge.a1", kazr2nc, multi_file=True),
     # KAZR2 at ENA (Dec 2019 onwards, hourly files)
     ArmInstrument("radar", "kazr", "kazr2cfrge.a1", kazr2nc, multi_file=True),
-    # KAZR corrected moments (approx. 2011-2019)
-    ArmInstrument("radar", "kazr", "kazrcorge.c1", kazr2nc, multi_file=True),
-    # KAZR moments (approx. 2011-2019, e.g. mobile facilities)
+    # KAZR moments (approx. 2011-2019, daily files)
     ArmInstrument("radar", "kazr", "kazrge.a1", kazr2nc, multi_file=True),
+    # KAZR corrected moments (approx. 2011-2012), fallback if raw missing
+    ArmInstrument("radar", "kazr", "kazrcorge.c1", kazr2nc, multi_file=True),
     # MMCR (before 2011)
     ArmInstrument("radar", "mmcr", "mmcrmom.b1", mmcr2nc, multi_file=False),
     ArmInstrument("lidar", "cl31", "ceil.b1", armceilo2nc, multi_file=False),

{cloudnetpy-1.95.4 → cloudnetpy-1.95.6}/cloudnetpy/categorize/categorize.py

@@ -212,6 +212,10 @@ def generate_categorize(
         attributes = output.add_time_attribute(CATEGORIZE_ATTRIBUTES, date)
         attributes = output.add_time_attribute(attributes, date, "model_time")
         attributes = output.add_source_attribute(attributes, data)
+        if "Z_offset" in cloudnet_arrays:
+            attributes["Z"] = attributes["Z"]._replace(
+                ancillary_variables=f"{attributes['Z'].ancillary_variables} Z_offset"
+            )
         output.update_attributes(cloudnet_arrays, attributes)
         _save_cat(output_file, data, cloudnet_arrays, uuid)
         return uuid
@@ -336,7 +340,7 @@ COMMENTS = {
         "and possibly liquid water, rain and melting layer (see quality_bits\n"
         "variable). Calibration convention: in the absence of attenuation, a cloud\n"
         "at 273 K containing one million 100-micron droplets per cubic metre will\n"
-        "have\n a reflectivity of 0 dBZ at all frequencies."
+        "have a reflectivity of 0 dBZ at all frequencies."
     ),
     "bias": (
         "This variable is an estimate of the one-standard-deviation\ncalibration error."
@@ -439,6 +443,12 @@ CATEGORIZE_ATTRIBUTES = {
     "nyquist_velocity": COMMON_ATTRIBUTES["nyquist_velocity"]._replace(
         dimensions=("time", "height")
     ),
+    "Z_offset": MetaData(
+        long_name="Radar reflectivity calibration offset",
+        units="dBZ",
+        comment="Calibration offset applied to the reflectivity in the radar file.",
+        dimensions=None,
+    ),
     # Lidar variables
     "beta": MetaData(
         long_name="Attenuated backscatter coefficient",

{cloudnetpy-1.95.4 → cloudnetpy-1.95.6}/cloudnetpy/categorize/classify.py

@@ -62,7 +62,9 @@ def classify_measurements(data: Observations) -> ClassificationResult:
 
     bits.melting = melting.find_melting_layer(obs)
     bits.freezing = freezing.find_freezing_region(obs, bits.melting)
-    liquid_from_lidar = droplet.find_liquid(obs)
+    # Vaisala CL51/CL61 have reliable near-range data, so allow lower liquid peaks
+    is_cl = any(model in obs.lidar_type.lower() for model in ("cl51", "cl61"))
+    liquid_from_lidar = droplet.find_liquid(obs, min_alt=70 if is_cl else 100)
     if obs.lv0_files is not None and len(obs.lv0_files) > 0:
         if "rpg-fmcw-94" not in obs.radar_type.lower():
             msg = "VoodooNet is only implemented for RPG-FMCW-94 radar."

{cloudnetpy-1.95.4 → cloudnetpy-1.95.6}/cloudnetpy/categorize/containers.py

@@ -56,6 +56,7 @@ class ClassData:
         height (ndarray): 1D height vector (m).
         model_type (str): Model identifier.
         radar_type (str): Radar identifier.
+        lidar_type (str): Lidar identifier.
         is_rain (ndarray): 2D boolean array denoting rain.
         is_clutter (ndarray): 2D boolean array denoting clutter.
         altitude: site altitude.
@@ -76,6 +77,7 @@ class ClassData:
         self.tw = data.model.data["Tw"][:]
         self.model_type = data.model.source_type
         self.beta = data.lidar.data["beta"][:]
+        self.lidar_type = data.lidar.source
         self.lwp = (
             data.mwr.data["lwp"][:]
             if data.mwr is not None

{cloudnetpy-1.95.4 → cloudnetpy-1.95.6}/cloudnetpy/categorize/radar.py

@@ -341,10 +341,19 @@ class Radar(DataSource):
     def _init_data(self) -> None:
         self.append_data(self.getvar("Zh"), "Z", units="dBZ")
         self.append_data(self.getvar("v"), "v_sigma")
-        for key in ("v", "ldr", "width", "sldr", "rainfall_rate", "nyquist_velocity"):
+        for key in (
+            "v",
+            "ldr",
+            "width",
+            "sldr",
+            "rainfall_rate",
+            "nyquist_velocity",
+        ):
             if key in self.dataset.variables:
                 data = self.dataset.variables[key]
                 self.append_data(data, key)
+        if "Zh_offset" in self.dataset.variables:
+            self.append_data(self.dataset.variables["Zh_offset"], "Z_offset")
 
     def _rebin_velocity(
         self,

{cloudnetpy-1.95.4 → cloudnetpy-1.95.6}/cloudnetpy/cli.py

@@ -437,6 +437,8 @@ def _process_instrument_product(
             input_files = input_folder
         case ("mrr", _id):
             fun = instruments.mrr2nc
+        case ("weather-radar", _id):
+            fun = instruments.wr2nc
         case ("weather-station", _id):
             fun = instruments.ws2nc
         case (invalid_product_id, invalid_instrument_id):
@@ -770,6 +772,10 @@ def _plot(
     options = PlotParameters()
     if args.max_y is not None:
         options.max_y = args.max_y
+    if args.start_time is not None:
+        options.start_time = args.start_time
+    if args.stop_time is not None:
+        options.stop_time = args.stop_time
     try:
         generate_figure(
             filepath,
@@ -949,6 +955,18 @@ def main() -> None:
         help="Maximum y-axis value (km) in 2D time/height plots (default: 12)",
         default=None,
     )
+    parser.add_argument(
+        "--start-time",
+        type=float,
+        help="Start time in fractional hours since midnight UTC (default: 0)",
+        default=None,
+    )
+    parser.add_argument(
+        "--stop-time",
+        type=float,
+        help="Stop time in fractional hours since midnight UTC (default: 24)",
+        default=None,
+    )
     parser.add_argument(
         "-o",
         "--options",

{cloudnetpy-1.95.4 → cloudnetpy-1.95.6}/cloudnetpy/instruments/arm_ceilo.py

@@ -112,6 +112,8 @@ class ArmCeilo(Ceilometer):
             self.data["time"] = np.array(nc["time"][:])
             calibration_factor = float(self.site_meta.get("calibration_factor", 1))
             backscatter = ma.masked_invalid(nc["backscatter"][:])
+            # Missing profiles are filled with int32 min without _FillValue
+            backscatter = ma.masked_less(backscatter, -1e6)
             self.data["beta_raw"] = backscatter * BACKSCATTER_SCALE * calibration_factor
             self.data["calibration_factor"] = calibration_factor
             self.data["zenith_angle"] = float(ma.median(nc["tilt_angle"][:]))

{cloudnetpy-1.95.4 → cloudnetpy-1.95.6}/cloudnetpy/instruments/kazr.py

@@ -12,6 +12,7 @@ from uuid import UUID
 
 import netCDF4
 import numpy as np
+import numpy.typing as npt
 from numpy import ma
 
 from cloudnetpy import output, utils
@@ -27,7 +28,7 @@ from cloudnetpy.instruments.dealias import (
 )
 from cloudnetpy.instruments.instruments import KAZR
 from cloudnetpy.instruments.nc_radar import estimate_snr_limit
-from cloudnetpy.metadata import COMMON_ATTRIBUTES
+from cloudnetpy.metadata import COMMON_ATTRIBUTES, MetaData
 
 # KAZR2 CF/Radial format (e.g. sgpkazrcfrgeC1.a1, hourly files)
 KEYMAP_CFR = {
@@ -67,15 +68,18 @@ def kazr2nc(
 ) -> UUID:
     """Converts ARM KAZR cloud radar data into Cloudnet Level 1b netCDF file.
 
-    Supports the KAZR2 CF/Radial moments (`kazrcfrge.a1`, hourly files), the
-    ARM corrected moments (`kazrcorge.c1`, daily files) and the original KAZR
-    moments (`kazrge.a1`, daily files). With the corrected moments, noise is
-    screened using the ARM significant detection mask and LDR is calculated
-    from the cross- and co-polar reflectivities. LDR is screened using the
-    cross-polar SNR and removed completely if the cross-polar channel is found
-    unreliable. Stationary clutter layers (zero velocity and spectral width)
-    are removed. Velocities of the non-corrected formats are dealiased using
-    velocity continuity.
+    Supports the KAZR2 CF/Radial moments (`kazrcfrge.a1` and the calibrated
+    `kazrcfrgeqc.b1`, hourly files), the ARM corrected moments (`kazrcorge.c1`,
+    daily files) and the original KAZR moments (`kazrge.a1`, daily files). The
+    reflectivity calibration offset applied by ARM in the calibrated files is
+    kept and recorded in `Zh_offset`. Uncalibrated files are calibrated with
+    `Zh_offset` from `site_meta` if given. With the corrected moments, noise is
+    screened using the ARM significant detection mask and
+    LDR is calculated from the cross- and co-polar reflectivities. LDR is
+    screened using the cross-polar SNR and removed completely if the
+    cross-polar channel is found unreliable. Stationary clutter layers (zero
+    velocity and spectral width) are removed. Velocities of the non-corrected
+    formats are dealiased using velocity continuity.
 
     Args:
         raw_files: Input file, a sequence of files, or a folder containing the
@@ -83,9 +87,11 @@ def kazr2nc(
         output_file: Output filename.
         site_meta: Dictionary containing information about the site. Required key
             value pair is `name`. Optional are `latitude`, `longitude` and
-            `altitude` (taken from the raw file if missing) and `snr_limit`
+            `altitude` (taken from the raw file if missing), `snr_limit`
             (fixed SNR threshold in dB; by default the threshold is estimated
-            from the noise in the top range gates).
+            from the noise in the top range gates) and `Zh_offset` (reflectivity
+            calibration offset in dB, used only if the file is not calibrated
+            by ARM).
         uuid: Set specific UUID for the file.
         date: Expected date as YYYY-MM-DD of all profiles in the file.
 
@@ -107,6 +113,7 @@ def kazr2nc(
     snr_limit = site_meta.get("snr_limit")
     kazr = Kazr(_get_files(raw_files), site_meta, date)
     kazr.read_files()
+    kazr.calibrate_reflectivity()
     kazr.sort_timestamps()
     kazr.remove_duplicate_timestamps()
     kazr.calc_ldr()
@@ -152,6 +159,7 @@ class Kazr(CloudnetInstrument):
         self.dealiased = False
         self.ldr_floor: float | None = None
         self.corrected = False  # ARM corrected (dealiased) moments
+        self.offset_applied: float | None = None  # Calibration offset by ARM
         self._raw: dict[str, list] = {}
 
     def read_files(self) -> None:
@@ -171,6 +179,20 @@ class Kazr(CloudnetInstrument):
             self.data[key] = CloudnetArray(ma.concatenate(arrays), key)
         self._screen_date()
 
+    def calibrate_reflectivity(self) -> None:
+        """Applies `Zh_offset` from site_meta unless already calibrated by ARM."""
+        zh_offset = self.site_meta.get("Zh_offset")
+        if self.offset_applied is not None:
+            if zh_offset is not None:
+                logging.info("File calibrated by ARM, ignoring Zh_offset")
+            zh_offset = self.offset_applied
+        elif zh_offset is None:
+            zh_offset = 0.0
+        else:
+            zh_offset = float(zh_offset)
+            self.data["Zh"].data[:] += zh_offset
+        self.append_data(np.array(zh_offset, dtype=np.float32), "Zh_offset")
+
     def screen_noise(self, snr_limit: float | None = None) -> None:
         """Masks noise using ARM detection mask if available, otherwise SNR.
 
@@ -339,6 +361,10 @@ class Kazr(CloudnetInstrument):
         else:
             msg = "Unknown KAZR file format"
             raise RadarDataError(msg)
+        zh_key = next(k for k, v in self.keymap.items() if v == "Zh")
+        bias = getattr(nc[zh_key], "applied_bias_correction", None)
+        if bias is not None:
+            self.offset_applied = _parse_bias(bias)
         self.serial_number = getattr(nc, "serial_number", None) or None
         self.append_data(np.array(nc["range"][:], dtype=float), "range")
         self.append_data(0.0, "zenith_angle")
@@ -508,6 +534,25 @@ def _get_files(raw_files: str | PathLike | Sequence[str | PathLike]) -> list[Pat
 
 ATTRIBUTES = {
     "correction_bits": CORRECTION_BITS_ATTRIBUTES,
+    "Zh_offset": MetaData(
+        long_name="Radar reflectivity calibration offset",
+        units="dBZ",
+        comment=(
+            "Calibration offset applied to the reflectivity, either by ARM "
+            "in the calibrated (b1) files or by Cloudnet in the other files."
+        ),
+        dimensions=None,
+    ),
     "zenith_angle": COMMON_ATTRIBUTES["zenith_angle"]._replace(dimensions=None),
     "nyquist_velocity": COMMON_ATTRIBUTES["nyquist_velocity"]._replace(dimensions=None),
 }
+
+
+def _parse_bias(bias: npt.ArrayLike) -> float | None:
+    """Parses ARM reflectivity bias attribute, which may be an empty array."""
+    values = np.atleast_1d(np.asarray(bias, dtype=float))
+    if len(values) == 0:
+        return None
+    if len(np.unique(values)) > 1:
+        logging.warning("Multiple bias corrections %s, using the first one", values)
+    return round(float(values[0]), 2)

{cloudnetpy-1.95.4 → cloudnetpy-1.95.6}/cloudnetpy/output.py

@@ -401,6 +401,7 @@ def add_source_attribute(attributes: dict, data: Observations) -> dict:
             "radar_frequency",
             "nyquist_velocity",
             "rainfall_rate",
+            "Z_offset",
         ),
         "lidar": ("beta", "lidar_wavelength"),
         "mwr": ("lwp",),

{cloudnetpy-1.95.4 → cloudnetpy-1.95.6}/cloudnetpy/plotting/plotting.py

@@ -54,6 +54,8 @@ class PlotParameters:
             plotted variable.
         minor_ticks: Whether to display minor ticks on the x-axis.
         plot_above_ground: Whether to plot above ground instead of above mean sea level.
+        start_time: Start time in fractional hours for time-axis limits.
+        stop_time: Stop time in fractional hours for time-axis limits.
 
     """
 
@@ -70,6 +72,8 @@ class PlotParameters:
     raise_on_empty: bool = False
     minor_ticks: bool = True
     plot_above_ground: bool = True
+    start_time: float | None = None
+    stop_time: float | None = None
 
 
 class Dimensions:
@@ -337,7 +341,11 @@ class SubPlot:
         if self.options.minor_ticks:
             self.ax.xaxis.set_minor_locator(AutoMinorLocator(4))
             self.ax.tick_params(which="minor", length=2.5)
-        self.ax.set_xlim(0, 24)
+        start_time = (
+            self.options.start_time if self.options.start_time is not None else 0
+        )
+        stop_time = self.options.stop_time if self.options.stop_time is not None else 24
+        self.ax.set_xlim(start_time, stop_time)
 
     def set_yax(
         self,

{cloudnetpy-1.95.4 → cloudnetpy-1.95.6}/cloudnetpy/version.py

@@ -1,4 +1,4 @@
 MAJOR = 1
 MINOR = 95
-PATCH = 4
+PATCH = 6
 __version__ = f"{MAJOR}.{MINOR}.{PATCH}"

{cloudnetpy-1.95.4 → cloudnetpy-1.95.6/cloudnetpy.egg-info}/PKG-INFO

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