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

cloudnetpy/instruments/disdrometer/common.py

@@ -1,193 +1,66 @@
 """Module for reading / converting disdrometer data."""
-import logging
+
+from typing import Literal
 
 import numpy as np
-from numpy import ma
+import numpy.typing as npt
 
-from cloudnetpy import utils
 from cloudnetpy.cloudnetarray import CloudnetArray
-from cloudnetpy.exceptions import ValidTimeStampError
 from cloudnetpy.instruments.cloudnet_instrument import CloudnetInstrument
-from cloudnetpy.instruments.vaisala import values_to_dict
 from cloudnetpy.metadata import MetaData
 
-PARSIVEL = "OTT Parsivel-2"
-THIES = "Thies-LNM"
-
 
 class Disdrometer(CloudnetInstrument):
-    def __init__(self, filename: str, site_meta: dict, source: str):
-        super().__init__()
-        self.filename = filename
-        self.site_meta = site_meta
-        self.source = source
-        self.date: list[str] = []
-        self.sensor_id = None
-        self.n_diameter: int = 0
-        self.n_velocity: int = 0
-        self._file_data = self._read_file()
-
-    def convert_units(self):
-        mm_to_m = 1e3
-        mmh_to_ms = 3600 * mm_to_m
-        c_to_k = 273.15
-        self._convert_data(("rainfall_rate_1min_total",), mmh_to_ms)
-        self._convert_data(("rainfall_rate",), mmh_to_ms)
-        self._convert_data(("rainfall_rate_1min_solid",), mmh_to_ms)
-        self._convert_data(("diameter", "diameter_spread", "diameter_bnds"), mm_to_m)
-        self._convert_data(("V_sensor_supply",), 10)
-        self._convert_data(("I_mean_laser",), 100)
-        self._convert_data(("T_sensor",), c_to_k, method="add")
-        self._convert_data(("T_interior",), c_to_k, method="add")
-        self._convert_data(("T_ambient",), c_to_k, method="add")
-        self._convert_data(("T_laser_driver",), c_to_k, method="add")
-
-    def add_meta(self):
+    def add_meta(self) -> None:
         valid_keys = ("latitude", "longitude", "altitude")
         for key, value in self.site_meta.items():
-            key = key.lower()
-            if key in valid_keys:
-                self.data[key] = CloudnetArray(float(value), key)
-
-    def validate_date(self, expected_date: str) -> None:
-        valid_ind = []
-        for ind, row in enumerate(self._file_data["scalars"]):
-            if self.source == PARSIVEL:
-                raise NotImplementedError
-            date = _format_thies_date(row[3])
-            if date == expected_date:
-                valid_ind.append(ind)
-        if not valid_ind:
-            raise ValidTimeStampError
-        for key, value in self._file_data.items():
-            if value:
-                self._file_data[key] = [self._file_data[key][ind] for ind in valid_ind]
-        self.date = expected_date.split("-")
+            name = key.lower()
+            if name in valid_keys:
+                self.data[name] = CloudnetArray(float(value), name)
 
-    def sort_time(self) -> None:
-        time = self.data["time"][:]
-        ind = time.argsort()
-        for _, data in self.data.items():
-            if data.data.shape[0] == len(time):
-                data.data[:] = data.data[ind]
-
-    def _read_file(self) -> dict:
-        data: dict = {"scalars": [], "vectors": [], "spectra": []}
-        with open(self.filename, encoding="utf8", errors="ignore") as file:
-            for row in file:
-                if row == "\n":
-                    continue
-                if self.source == PARSIVEL:
-                    values = row.split(";")
-                    if "\n" in values:
-                        values.remove("\n")
-                    if len(values) != 1106:
-                        continue
-                    data["scalars"].append(values[:18])
-                    data["vectors"].append(values[18 : 18 + 64])
-                    data["spectra"].append(values[18 + 64 :])
-                else:
-                    values = row.split(";")
-                    data["scalars"].append(values[:79])
-                    data["spectra"].append(values[79:-2])
-        if len(data["scalars"]) == 0:
-            raise ValueError
-        return data
-
-    def _append_data(self, column_and_key: list) -> None:
-        indices, keys = zip(*column_and_key)
-        data = self._parse_useful_data(indices)
-        data_dict = values_to_dict(keys, data)
+    def _convert_data(
+        self,
+        keys: tuple[str, ...],
+        value: float,
+        method: Literal["divide", "add"] = "divide",
+    ) -> None:
         for key in keys:
-            if key.startswith("_"):
+            if key not in self.data:
                 continue
-            invalid_value = -9999.0
-            float_array = ma.array([])
-            for value_str in data_dict[key]:
-                try:
-                    float_array = ma.append(float_array, float(value_str))
-                except ValueError:
-                    logging.warning(
-                        f"Invalid character: {value_str}, masking a data point"
-                    )
-                    float_array = ma.append(float_array, invalid_value)
-            float_array[float_array == invalid_value] = ma.masked
-            if key in (
-                "rainfall_rate",
-                "radar_reflectivity",
-                "T_sensor",
-                "I_heating",
-                "V_power_supply",
-                "T_interior",
-                "T_ambient",
-                "T_laser_driver",
-            ):
-                data_type = "f4"
+            variable = self.data[key]
+            if method == "divide":
+                variable.data = variable.data.astype("f4") / value
+                variable.data_type = "f4"
+            elif method == "add":
+                variable.data = variable.data.astype("f4") + value
+                variable.data_type = "f4"
             else:
-                data_type = "i4"
-            self.data[key] = CloudnetArray(float_array, key, data_type=data_type)
-        self.data["time"] = self._convert_time(data_dict)
-        if "_sensor_id" in data_dict:
-            self.sensor_id = data_dict["_sensor_id"][0]
-
-    def _parse_useful_data(self, indices: list) -> list:
-        data = []
-        for row in self._file_data["scalars"]:
-            useful_data = [row[ind] for ind in indices]
-            data.append(useful_data)
-        return data
-
-    def _convert_time(self, data: dict) -> CloudnetArray:
-        seconds = []
-        for timestamp in data["_time"]:
-            if self.source == PARSIVEL:
-                raise NotImplementedError
-            hour, minute, sec = timestamp.split(":")
-            seconds.append(int(hour) * 3600 + int(minute) * 60 + int(sec))
-        return CloudnetArray(utils.seconds2hours(np.array(seconds)), "time")
+                raise ValueError
 
-    def _convert_data(self, keys: tuple, value: float, method: str = "divide"):
-        for key in keys:
-            if key in self.data:
-                if method == "divide":
-                    self.data[key].data /= value
-                elif method == "add":
-                    self.data[key].data += value
-                else:
-                    raise ValueError
-
-    def _append_spectra(self):
-        array = ma.masked_all(
-            (len(self._file_data["scalars"]), self.n_diameter, self.n_velocity)
-        )
-        for time_ind, row in enumerate(self._file_data["spectra"]):
-            values = _parse_int(row)
-            array[time_ind, :, :] = np.reshape(
-                values, (self.n_diameter, self.n_velocity)
-            )
-        self.data["data_raw"] = CloudnetArray(
-            array, "data_raw", dimensions=("time", "diameter", "velocity")
-        )
-
-    @classmethod
     def store_vectors(
-        cls, data, n_values: list, spreads: list, name: str, start: float = 0.0
-    ):
-        mid, bounds, spread = cls._create_vectors(n_values, spreads, start)
-        data[name] = CloudnetArray(mid, name, dimensions=(name,))
+        self,
+        n_values: list,
+        spreads: list,
+        name: str,
+        start: float = 0.0,
+    ) -> None:
+        mid, bounds, spread = self._create_vectors(n_values, spreads, start)
+        self.data[name] = CloudnetArray(mid, name, dimensions=(name,))
         key = f"{name}_spread"
-        data[key] = CloudnetArray(spread, key, dimensions=(name,))
+        self.data[key] = CloudnetArray(spread, key, dimensions=(name,))
         key = f"{name}_bnds"
-        data[key] = CloudnetArray(bounds, key, dimensions=(name, "nv"))
+        self.data[key] = CloudnetArray(bounds, key, dimensions=(name, "nv"))
 
-    @staticmethod
     def _create_vectors(
-        n_values: list[int], spreads: list[float], start: float
+        self,
+        n_values: list[int],
+        spreads: list[float],
+        start: float,
     ) -> tuple:
-        mid_value: np.ndarray = np.array([])
-        lower_limit: np.ndarray = np.array([])
-        upper_limit: np.ndarray = np.array([])
-        for spread, n in zip(spreads, n_values):
+        mid_value: npt.NDArray = np.array([])
+        lower_limit: npt.NDArray = np.array([])
+        upper_limit: npt.NDArray = np.array([])
+        for spread, n in zip(spreads, n_values, strict=True):
             lower = np.linspace(start, start + (n - 1) * spread, n)
             upper = lower + spread
             lower_limit = np.append(lower_limit, lower)
@@ -199,219 +72,249 @@ class Disdrometer(CloudnetInstrument):
         return mid_value, bounds, spread
 
 
-def _format_thies_date(date: str):
-    day, month, year = date.split(".")
-    year = f"20{year}"
-    return f"{year}-{month.zfill(2)}-{day.zfill(2)}"
-
-
-def _parse_int(row: np.ndarray) -> np.ndarray:
-    values = ma.masked_all((len(row),))
-    for ind, value in enumerate(row):
-        try:
-            value = int(value)
-            if value != 0:
-                values[ind] = value
-        except ValueError:
-            pass
-    return values
-
-
 ATTRIBUTES = {
     "velocity": MetaData(
         long_name="Center fall velocity of precipitation particles",
         units="m s-1",
         comment="Predefined velocity classes.",
+        dimensions=("velocity",),
     ),
     "velocity_spread": MetaData(
         long_name="Width of velocity interval",
         units="m s-1",
         comment="Bin size of each velocity interval.",
+        dimensions=("velocity",),
     ),
     "velocity_bnds": MetaData(
         long_name="Velocity bounds",
         units="m s-1",
         comment="Upper and lower bounds of velocity interval.",
+        dimensions=("velocity", "nv"),
     ),
     "diameter": MetaData(
         long_name="Center diameter of precipitation particles",
         units="m",
         comment="Predefined diameter classes.",
+        dimensions=("diameter",),
     ),
     "diameter_spread": MetaData(
         long_name="Width of diameter interval",
         units="m",
         comment="Bin size of each diameter interval.",
+        dimensions=("diameter",),
     ),
     "diameter_bnds": MetaData(
         long_name="Diameter bounds",
         units="m",
         comment="Upper and lower bounds of diameter interval.",
+        dimensions=("diameter", "nv"),
     ),
     "rainfall_rate_1min_total": MetaData(
-        long_name="Total precipitation rate",
-        units="m s-1",
+        long_name="Total precipitation rate", units="m s-1", dimensions=("time",)
     ),
     "rainfall_rate": MetaData(
-        long_name="Rainfall rate", units="m s-1", standard_name="rainfall_rate"
+        long_name="Rainfall rate",
+        units="m s-1",
+        standard_name="rainfall_rate",
+        dimensions=("time",),
     ),
     "rainfall_rate_1min_solid": MetaData(
-        long_name="Solid precipitation rate",
-        units="m s-1",
+        long_name="Solid precipitation rate", units="m s-1", dimensions=("time",)
     ),
     "snowfall_rate": MetaData(
         long_name="Snowfall rate",
         units="m s-1",
         comment="Snow depth intensity (volume equivalent)",
+        dimensions=("time",),
     ),
-    "synop_WaWa": MetaData(long_name="Synop code WaWa", units="1"),
-    "synop_WW": MetaData(long_name="Synop code WW", units="1"),
+    "synop_WaWa": MetaData(
+        long_name="Synop code WaWa", units="1", dimensions=("time",)
+    ),
+    "synop_WW": MetaData(long_name="Synop code WW", units="1", dimensions=("time",)),
     "radar_reflectivity": MetaData(
         long_name="Equivalent radar reflectivity factor",
         units="dBZ",
         standard_name="equivalent_reflectivity_factor",
+        dimensions=("time",),
     ),
     "visibility": MetaData(
-        long_name="Visibility range in precipitation after MOR",
+        long_name="Meteorological optical range (MOR) visibility",
         units="m",
         standard_name="visibility_in_air",
+        comment="Visibility estimation by the disdrometer is valid\n"
+        "only during precipitation events.",
+        dimensions=("time",),
+    ),
+    "interval": MetaData(
+        long_name="Length of measurement interval", units="s", dimensions=("time",)
+    ),
+    "sig_laser": MetaData(
+        long_name="Signal amplitude of the laser strip", units="1", dimensions=("time",)
     ),
-    "interval": MetaData(long_name="Length of measurement interval", units="s"),
-    "sig_laser": MetaData(long_name="Signal amplitude of the laser strip", units="1"),
     "n_particles": MetaData(
-        long_name="Number of particles in time interval", units="1"
+        long_name="Number of particles in time interval",
+        units="1",
+        dimensions=("time",),
     ),
     "T_sensor": MetaData(
-        long_name="Temperature in the sensor housing",
-        units="K",
-    ),
-    "I_heating": MetaData(
-        long_name="Heating current",
-        units="A",
+        long_name="Temperature in the sensor housing", units="K", dimensions=("time",)
     ),
+    "I_heating": MetaData(long_name="Heating current", units="A", dimensions=("time",)),
     "V_sensor_supply": MetaData(
-        long_name="Sensor supply voltage",
-        units="V",
+        long_name="Sensor supply voltage", units="V", dimensions=("time",)
     ),
     "V_power_supply": MetaData(
-        long_name="Power supply voltage",
-        units="V",
+        long_name="Power supply voltage", units="V", dimensions=("time",)
     ),
     "state_sensor": MetaData(
         long_name="State of the sensor",
         comment="0 = OK, 1 = Dirty, 2 = No measurement possible.",
         units="1",
+        dimensions=("time",),
     ),
-    "error_code": MetaData(long_name="Error code", units="1"),
+    "error_code": MetaData(long_name="Error code", units="1", dimensions=("time",)),
     "number_concentration": MetaData(
         long_name="Number of particles per diameter class",
-        comment="Unit is actually logarithmic log10(m-3 mm-1).",
         units="m-3 mm-1",
+        dimensions=("time", "diameter"),
     ),
     "fall_velocity": MetaData(
         long_name="Average velocity of each diameter class",
         units="m s-1",
+        dimensions=("time", "diameter"),
     ),
     "data_raw": MetaData(
         long_name="Raw data as a function of particle diameter and velocity",
         units="1",
+        dimensions=("time", "diameter", "velocity"),
     ),
     "kinetic_energy": MetaData(
-        long_name="Kinetic energy of the hydrometeors", units="J m-2 h-1"
+        long_name="Kinetic energy of the hydrometeors",
+        units="J m-2 h-1",
+        dimensions=("time",),
     ),
     # Thies-specific:
-    "T_ambient": MetaData(long_name="Ambient temperature", units="K"),
-    "T_interior": MetaData(long_name="Interior temperature", units="K"),
+    "T_ambient": MetaData(
+        long_name="Ambient temperature", units="K", dimensions=("time",)
+    ),
+    "T_interior": MetaData(
+        long_name="Interior temperature", units="K", dimensions=("time",)
+    ),
     "status_T_laser_analogue": MetaData(
         long_name="Status of laser temperature (analogue)",
         comment="0 = OK , 1 = Error",
         units="1",
+        dimensions=("time",),
     ),
     "status_T_laser_digital": MetaData(
         long_name="Status of laser temperature (digital)",
         comment="0 = OK , 1 = Error",
         units="1",
+        dimensions=("time",),
     ),
     "status_I_laser_analogue": MetaData(
         long_name="Status of laser current (analogue)",
         comment="0 = OK , 1 = Error",
         units="1",
+        dimensions=("time",),
     ),
     "status_I_laser_digital": MetaData(
         long_name="Status of laser current (digital)",
         comment="0 = OK , 1 = Error",
         units="1",
+        dimensions=("time",),
     ),
     "status_sensor_supply": MetaData(
         long_name="Status of sensor supply",
         comment="0 = OK , 1 = Error",
         units="1",
+        dimensions=("time",),
     ),
     "status_laser_heating": MetaData(
         long_name="Status of laser heating",
         comment="0 = OK , 1 = Error",
         units="1",
+        dimensions=("time",),
     ),
     "status_receiver_heating": MetaData(
         long_name="Status of receiver heating",
         comment="0 = OK , 1 = Error",
         units="1",
+        dimensions=("time",),
     ),
     "status_temperature_sensor": MetaData(
         long_name="Status of temperature sensor",
         comment="0 = OK , 1 = Error",
         units="1",
+        dimensions=("time",),
     ),
     "status_heating_supply": MetaData(
         long_name="Status of heating supply",
         comment="0 = OK , 1 = Error",
         units="1",
+        dimensions=("time",),
     ),
     "status_heating_housing": MetaData(
         long_name="Status of heating housing",
         comment="0 = OK , 1 = Error",
         units="1",
+        dimensions=("time",),
     ),
     "status_heating_heads": MetaData(
         long_name="Status of heating heads",
         comment="0 = OK , 1 = Error",
         units="1",
+        dimensions=("time",),
     ),
     "status_heating_carriers": MetaData(
         long_name="Status of heating carriers",
         comment="0 = OK , 1 = Error",
         units="1",
+        dimensions=("time",),
     ),
     "status_laser_power": MetaData(
         long_name="Status of laser power",
         comment="0 = OK , 1 = Error",
         units="1",
+        dimensions=("time",),
     ),
     "status_laser": MetaData(
-        long_name="Status of laser", comment="0 = OK/on , 1 = Off", units="1"
+        long_name="Status of laser",
+        comment="0 = OK/on , 1 = Off",
+        units="1",
+        dimensions=("time",),
+    ),
+    "measurement_quality": MetaData(
+        long_name="Measurement quality", units="%", dimensions=("time",)
+    ),
+    "maximum_hail_diameter": MetaData(
+        long_name="Maximum hail diameter", units="mm", dimensions=("time",)
     ),
-    "measurement_quality": MetaData(long_name="Measurement quality", units="%"),
-    "maximum_hail_diameter": MetaData(long_name="Maximum hail diameter", units="mm"),
     "static_signal": MetaData(
-        long_name="Static signal", comment="0 = OK, 1 = ERROR", units="1"
+        long_name="Static signal",
+        comment="0 = OK, 1 = ERROR",
+        units="1",
+        dimensions=("time",),
+    ),
+    "T_laser_driver": MetaData(
+        long_name="Temperature of laser driver", units="K", dimensions=("time",)
+    ),
+    "I_mean_laser": MetaData(
+        long_name="Mean value of laser current", units="mA", dimensions=("time",)
     ),
-    "T_laser_driver": MetaData(long_name="Temperature of laser driver", units="K"),
-    "I_mean_laser": MetaData(long_name="Mean value of laser current", units="mA"),
     "V_control": MetaData(
         long_name="Control voltage",
         units="mV",
         comment="Reference value: 4010+-5",
+        dimensions=("time",),
     ),
     "V_optical_output": MetaData(
-        long_name="Voltage of optical control output",
-        units="mV",
+        long_name="Voltage of optical control output", units="mV", dimensions=("time",)
     ),
     "I_heating_laser_head": MetaData(
-        long_name="Laser head heating current",
-        units="mA",
+        long_name="Laser head heating current", units="mA", dimensions=("time",)
     ),
     "I_heating_receiver_head": MetaData(
-        long_name="Receiver head heating current",
-        units="mA",
+        long_name="Receiver head heating current", units="mA", dimensions=("time",)
     ),
 }