cloudnetpy 1.95.4__tar.gz → 1.95.5__tar.gz

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

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

{cloudnetpy-1.95.4 → cloudnetpy-1.95.5}/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.5}/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.5}/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.5}/cloudnetpy/instruments/kazr.py

@@ -27,7 +27,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 +67,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 +86,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 +112,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 +158,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 +178,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 +360,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 = round(float(bias), 2)
         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 +533,15 @@ 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),
 }

{cloudnetpy-1.95.4 → cloudnetpy-1.95.5}/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.5}/cloudnetpy/version.py

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

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

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