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

cloudnetpy/categorize/classify.py

@@ -1,17 +1,27 @@
-"""Module containing low-level functions to classify gridded
-radar / lidar measurements.
-"""
 import numpy as np
-import skimage
+import numpy.typing as npt
 from numpy import ma
 
-import cloudnetpy.categorize.atmos
 from cloudnetpy import utils
-from cloudnetpy.categorize import droplet, falling, freezing, insects, melting
-from cloudnetpy.categorize.containers import ClassData, ClassificationResult
-
-
-def classify_measurements(data: dict) -> ClassificationResult:
+from cloudnetpy.categorize import (
+    atmos_utils,
+    droplet,
+    falling,
+    freezing,
+    insects,
+    melting,
+)
+from cloudnetpy.categorize.attenuations import RadarAttenuation
+from cloudnetpy.categorize.containers import (
+    ClassData,
+    ClassificationResult,
+    Observations,
+)
+from cloudnetpy.constants import T0
+from cloudnetpy.products.product_tools import CategoryBits, QualityBits
+
+
+def classify_measurements(data: Observations) -> ClassificationResult:
     """Classifies radar/lidar observations.
 
     This function classifies atmospheric scatterers from the input data.
@@ -19,8 +29,7 @@ def classify_measurements(data: dict) -> ClassificationResult:
     time / height grid before calling this function.
 
     Args:
-        data: Containing :class:`Radar`, :class:`Lidar`, :class:`Model`
-            and :class:`Mwr` instances.
+        data: A :class:`Observations` instance.
 
     Returns:
         A :class:`ClassificationResult` instance.
@@ -36,132 +45,142 @@ def classify_measurements(data: dict) -> ClassificationResult:
         Especially methods classifying insects, melting layer and liquid droplets.
 
     """
+    bits = CategoryBits(
+        droplet=np.array([], dtype=bool),
+        falling=np.array([], dtype=bool),
+        freezing=np.array([], dtype=bool),
+        melting=np.array([], dtype=bool),
+        aerosol=np.array([], dtype=bool),
+        insect=np.array([], dtype=bool),
+    )
+
     obs = ClassData(data)
-    bits: list[np.ndarray] = [np.array([])] * 6
-    bits[3] = melting.find_melting_layer(obs)
-    bits[2] = freezing.find_freezing_region(obs, bits[3])
+
+    bits.melting = melting.find_melting_layer(obs)
+    bits.freezing = freezing.find_freezing_region(obs, bits.melting)
     liquid_from_lidar = droplet.find_liquid(obs)
     if obs.lv0_files is not None and len(obs.lv0_files) > 0:
-        import voodoonet  # pylint: disable=import-outside-toplevel
-
-        target_time = voodoonet.utils.decimal_hour2unix(obs.date, obs.time)
-        liquid_prob = voodoonet.infer(obs.lv0_files, target_time=target_time)
+        if "rpg-fmcw-94" not in obs.radar_type.lower():
+            msg = "VoodooNet is only implemented for RPG-FMCW-94 radar."
+            raise NotImplementedError(msg)
+        import voodoonet  # noqa: PLC0415
+
+        options = voodoonet.VoodooOptions(progress_bar=False)
+        dumb_date = obs.date.isoformat().split("-")
+        target_time = voodoonet.utils.decimal_hour2unix(dumb_date, obs.time)
+        liquid_prob = voodoonet.infer(
+            list(obs.lv0_files), target_time=target_time, options=options
+        )
         liquid_from_radar = liquid_prob > 0.55
         liquid_from_radar = _remove_false_radar_liquid(
-            liquid_from_radar, liquid_from_lidar
+            liquid_from_radar,
+            liquid_from_lidar,
         )
-        bits[0] = liquid_from_radar | liquid_from_lidar
+        liquid_from_radar[~bits.freezing] = 0
+        is_liquid = liquid_from_radar | liquid_from_lidar
     else:
-        bits[0] = droplet.correct_liquid_top(obs, liquid_from_lidar, bits[2], limit=500)
+        is_liquid = liquid_from_lidar
         liquid_prob = None
-    bits[5], insect_prob = insects.find_insects(obs, bits[3], bits[0])
-    bits[1] = falling.find_falling_hydrometeors(obs, bits[0], bits[5])
-    bits, filtered_ice = _filter_falling(bits)
+    bits.droplet = droplet.correct_liquid_top(obs, is_liquid, bits.freezing, limit=500)
+    bits.insect, insect_prob = insects.find_insects(obs, bits.melting, bits.droplet)
+    bits.falling = falling.find_falling_hydrometeors(obs, bits.droplet, bits.insect)
+    filtered_ice = _filter_falling(bits)
     for _ in range(5):
-        bits[3] = _fix_undetected_melting_layer(bits)
-        bits = _filter_insects(bits)
-    bits[4] = _find_aerosols(obs, bits[1], bits[0])
-    bits[4][filtered_ice] = False
+        _fix_undetected_melting_layer(bits)
+        _filter_insects(bits)
+    bits.aerosol = _find_aerosols(obs, bits)
+    bits.aerosol[filtered_ice] = False
+    _fix_super_cold_liquid(obs, bits)
+
     return ClassificationResult(
-        _bits_to_integer(bits),
-        obs.is_rain,
-        obs.is_clutter,
-        obs.rainfall_rate,
-        insect_prob,
-        liquid_prob,
+        category_bits=bits,
+        is_rain=obs.is_rain,
+        is_clutter=obs.is_clutter,
+        insect_prob=insect_prob,
+        liquid_prob=liquid_prob,
     )
 
 
-def _remove_false_radar_liquid(
-    liquid_from_radar: np.ndarray, liquid_from_lidar: np.ndarray
-) -> np.ndarray:
-    """Removes radar-liquid below lidar-detected liquid bases."""
-    lidar_liquid_bases = cloudnetpy.categorize.atmos.find_cloud_bases(liquid_from_lidar)
-    for prof, base in zip(*np.where(lidar_liquid_bases)):
-        liquid_from_radar[prof, 0:base] = 0
-    return liquid_from_radar
-
-
 def fetch_quality(
-    data: dict, classification: ClassificationResult, attenuations: dict
-) -> dict:
-    """Returns Cloudnet quality bits.
+    data: Observations,
+    classification: ClassificationResult,
+    attenuations: RadarAttenuation,
+) -> QualityBits:
+    return QualityBits(
+        radar=~data.radar.data["Z"][:].mask,
+        lidar=~data.lidar.data["beta"][:].mask,
+        clutter=classification.is_clutter,
+        molecular=np.zeros(data.radar.data["Z"][:].shape, dtype=bool),
+        attenuated_liquid=attenuations.liquid.attenuated,
+        corrected_liquid=attenuations.liquid.attenuated
+        & ~attenuations.liquid.uncorrected,
+        attenuated_rain=attenuations.rain.attenuated,
+        corrected_rain=attenuations.rain.attenuated & ~attenuations.rain.uncorrected,
+        attenuated_melting=attenuations.melting.attenuated,
+        corrected_melting=attenuations.melting.attenuated
+        & ~attenuations.melting.uncorrected,
+    )
 
-    Args:
-        data: Containing :class:`Radar` and :class:`Lidar` instances.
-        classification: A :class:`ClassificationResult` instance.
-        attenuations: Dictionary containing keys `liquid_corrected`,
-            `liquid_uncorrected`.
 
-    Returns:
-        Dictionary containing `quality_bits`, an integer array with the bits:
+def _fix_super_cold_liquid(obs: ClassData, bits: CategoryBits) -> None:
+    """Supercooled liquid droplets do not exist in atmosphere below around -38 C."""
+    t_limit = T0 - 38
+    super_cold_liquid = np.where((obs.tw < t_limit) & bits.droplet)
+    bits.droplet[super_cold_liquid] = False
+    bits.falling[super_cold_liquid] = True
 
-            - bit 0: Pixel contains radar data
-            - bit 1: Pixel contains lidar data
-            - bit 2: Pixel contaminated by radar clutter
-            - bit 3: Molecular scattering present (currently not implemented!)
-            - bit 4: Pixel was affected by liquid attenuation
-            - bit 5: Liquid attenuation was corrected
-            - bit 6: Data gap in radar or lidar data
 
-    """
-    bits: list[np.ndarray] = [np.ndarray([])] * 7
-    radar_echo = data["radar"].data["Z"][:]
-    bits[0] = ~radar_echo.mask
-    bits[1] = ~data["lidar"].data["beta"][:].mask
-    bits[2] = classification.is_clutter
-    bits[4] = attenuations["liquid_corrected"] | attenuations["liquid_uncorrected"]
-    bits[5] = attenuations["liquid_corrected"]
-    qbits = _bits_to_integer(bits)
-    return {"quality_bits": qbits}
+def _remove_false_radar_liquid(
+    liquid_from_radar: npt.NDArray,
+    liquid_from_lidar: npt.NDArray,
+) -> npt.NDArray[np.bool_]:
+    """Removes radar-liquid below lidar-detected liquid bases."""
+    lidar_liquid_bases = atmos_utils.find_cloud_bases(liquid_from_lidar)
+    for prof, base in zip(*np.where(lidar_liquid_bases), strict=True):
+        liquid_from_radar[prof, 0:base] = 0
+    return liquid_from_radar
 
 
 def _find_aerosols(
-    obs: ClassData, is_falling: np.ndarray, is_liquid: np.ndarray
-) -> np.ndarray:
+    obs: ClassData,
+    bits: CategoryBits,
+) -> npt.NDArray[np.bool_]:
     """Estimates aerosols from lidar backscattering.
 
     Aerosols are lidar signals that are: a) not falling, b) not liquid droplets.
 
     Args:
         obs: A :class:`ClassData` instance.
-        is_falling: 2-D boolean array of falling hydrometeors.
-        is_liquid: 2-D boolean array of liquid droplets.
+        bits: A :class:`CategoryBits instance.
 
     Returns:
         2-D boolean array containing aerosols.
 
     """
     is_beta = ~obs.beta.mask
-    return is_beta & ~is_falling & ~is_liquid
+    return is_beta & ~bits.falling & ~bits.droplet
 
 
-def _fix_undetected_melting_layer(bits: list) -> np.ndarray:
-    melting_layer = bits[3]
-    drizzle_and_falling = _find_drizzle_and_falling(*bits[:3])
+def _fix_undetected_melting_layer(bits: CategoryBits) -> None:
+    drizzle_and_falling = _find_drizzle_and_falling(bits)
     transition = ma.diff(drizzle_and_falling, axis=1) == -1
-    melting_layer[:, 1:][transition] = True
-    return melting_layer
+    bits.melting[:, 1:][transition] = True
 
 
-def _find_drizzle_and_falling(
-    is_liquid: np.ndarray, is_falling: np.ndarray, is_freezing: np.ndarray
-) -> np.ndarray:
+def _find_drizzle_and_falling(bits: CategoryBits) -> npt.NDArray:
     """Classifies pixels as falling, drizzle and others.
 
     Args:
-        is_liquid: 2D boolean array denoting liquid layers.
-        is_falling: 2D boolean array denoting falling pixels.
-        is_freezing: 2D boolean array denoting subzero temperatures.
+        bits: A :class:`CategoryBits instance.
 
     Returns:
         2D array where values are 1 (falling, drizzle, supercooled liquids),
         2 (drizzle), and masked (all others).
 
     """
-    falling_dry = is_falling & ~is_liquid
-    supercooled_liquids = is_liquid & is_freezing
-    drizzle = falling_dry & ~is_freezing
+    falling_dry = bits.falling & ~bits.droplet
+    supercooled_liquids = bits.droplet & bits.freezing
+    drizzle = falling_dry & ~bits.freezing
     drizzle_and_falling = falling_dry.astype(int) + drizzle.astype(int)
     drizzle_and_falling = ma.copy(drizzle_and_falling)
     drizzle_and_falling[supercooled_liquids] = 1
@@ -169,28 +188,10 @@ def _find_drizzle_and_falling(
     return drizzle_and_falling
 
 
-def _bits_to_integer(bits: list) -> np.ndarray:
-    """Creates array of integers from individual boolean arrays.
-
-    Args:
-        bits: List of bit fields (of similar sizes) to be saved in the resulting
-            array of integers. bits[0] is saved as bit 0, bits[1] as bit 1, etc.
-
-    Returns:
-        Array of integers containing the information of the individual boolean arrays.
-
-    """
-    int_array = np.zeros_like(bits[0], dtype=int)
-    for n, bit in enumerate(bits):
-        ind = np.where(bit)  # works also if bit is None
-        int_array[ind] = utils.setbit(int_array[ind].astype(int), n)
-    return int_array
-
-
-def _filter_insects(bits: list) -> list:
-    is_melting_layer = bits[3]
-    is_insects = bits[5]
-    is_falling = bits[1]
+def _filter_insects(bits: CategoryBits) -> None:
+    is_melting_layer = bits.melting
+    is_insects = bits.insect
+    is_falling = bits.falling
 
     # Remove above melting layer
     above_melting = utils.ffill(is_melting_layer)
@@ -201,7 +202,7 @@ def _filter_insects(bits: list) -> list:
     # remove around melting layer:
     original_insects = np.copy(is_insects)
     n_gates = 5
-    for x, y in zip(*np.where(is_melting_layer)):
+    for x, y in zip(*np.where(is_melting_layer), strict=True):
         try:
             # change insects to drizzle below melting layer pixel
             ind1 = np.arange(y - n_gates, y)
@@ -219,17 +220,18 @@ def _filter_insects(bits: list) -> list:
             is_insects[ind1[ind11], y - 1 : y + 2] = False
         except IndexError:
             continue
-    bits[1] = is_falling
-    bits[5] = is_insects
-    return bits
+    bits.falling = is_falling
+    bits.insect = is_insects
 
 
-def _filter_falling(bits: list) -> tuple:
+def _filter_falling(bits: CategoryBits) -> tuple:
     # filter falling ice speckle noise
-    is_freezing = bits[2]
-    is_falling = bits[1]
-    is_falling_filtered = skimage.morphology.remove_small_objects(
-        is_falling, 10, connectivity=1
+    is_freezing = bits.freezing
+    is_falling = bits.falling
+    is_falling_filtered = utils.remove_small_objects(
+        is_falling,
+        max_size=10,
+        connectivity=1,
     )
     is_filtered = is_falling & ~np.array(is_falling_filtered)
     ice_ind = np.where(is_freezing & is_filtered)
@@ -237,6 +239,6 @@ def _filter_falling(bits: list) -> tuple:
     # in warm these are (probably) insects
     insect_ind = np.where(~is_freezing & is_filtered)
     is_falling[insect_ind] = False
-    bits[1] = is_falling
-    bits[5][insect_ind] = True
-    return bits, ice_ind
+    bits.falling = is_falling
+    bits.insect[insect_ind] = True
+    return ice_ind

cloudnetpy/categorize/containers.py

@@ -1,23 +1,39 @@
-import logging
+from collections.abc import Sequence
 from dataclasses import dataclass
+from os import PathLike
 
 import numpy as np
-import skimage
+import numpy.typing as npt
 from numpy import ma
 
 from cloudnetpy import utils
+from cloudnetpy.constants import MM_H_TO_M_S, T0
+from cloudnetpy.products.product_tools import CategoryBits
+
+from .disdrometer import Disdrometer
+from .lidar import Lidar
+from .model import Model
+from .mwr import Mwr
+from .radar import Radar
 
 
 @dataclass
-class ClassificationResult:
-    """Result of classification"""
+class Observations:
+    radar: Radar
+    lidar: Lidar
+    model: Model
+    mwr: Mwr | None = None
+    disdrometer: Disdrometer | None = None
+    lv0_files: Sequence[str | PathLike] | None = None
 
-    category_bits: np.ndarray
-    is_rain: np.ndarray
-    is_clutter: np.ndarray
-    rainfall_rate: np.ndarray
-    insect_prob: np.ndarray
-    liquid_prob: np.ndarray | None
+
+@dataclass
+class ClassificationResult:
+    category_bits: CategoryBits
+    is_rain: npt.NDArray
+    is_clutter: npt.NDArray
+    insect_prob: npt.NDArray
+    liquid_prob: npt.NDArray | None
 
 
 class ClassData:
@@ -42,86 +58,100 @@ class ClassData:
         radar_type (str): Radar identifier.
         is_rain (ndarray): 2D boolean array denoting rain.
         is_clutter (ndarray): 2D boolean array denoting clutter.
-        rainfall_rate: 1D rain rate.
         altitude: site altitude.
 
     """
 
-    def __init__(self, data: dict):
-        self.z = data["radar"].data["Z"][:]
-        self.v = data["radar"].data["v"][:]
-        self.v_sigma = data["radar"].data["v_sigma"][:]
+    def __init__(self, data: Observations) -> None:
+        self.data = data
+        self.z = data.radar.data["Z"][:]
+        self.v = data.radar.data["v"][:]
+        self.v_sigma = data.radar.data["v_sigma"][:]
         for key in ("width", "ldr", "sldr"):
-            if key in data["radar"].data.keys():
-                setattr(self, key, data["radar"].data[key][:])
-        self.time = data["radar"].time
-        self.height = data["radar"].height
-        self.radar_type = data["radar"].type
-        self.tw = data["model"].data["Tw"][:]
-        self.model_type = data["model"].type
-        self.beta = data["lidar"].data["beta"][:]
-        self.lwp = data["mwr"].data["lwp"][:]
-        self.is_rain = _find_rain_from_radar_echo(self.z, self.time)
-        self.rainfall_rate = _find_rainfall_rate(self.is_rain, data["radar"])
+            if key in data.radar.data:
+                setattr(self, key, data.radar.data[key][:])
+        self.time = data.radar.time
+        self.height = data.radar.height
+        self.radar_type = data.radar.source_type
+        self.tw = data.model.data["Tw"][:]
+        self.model_type = data.model.source_type
+        self.beta = data.lidar.data["beta"][:]
+        self.lwp = (
+            data.mwr.data["lwp"][:]
+            if data.mwr is not None
+            else ma.masked_all(self.time.shape)
+        )
+        self.is_rain = self._find_profiles_with_rain()
         self.is_clutter = _find_clutter(self.v, self.is_rain)
-        self.altitude = data["radar"].altitude
-        self.lv0_files = data["lv0_files"]
-        self.date = data["radar"].get_date()
-
-
-def _find_rain_from_radar_echo(
-    z: np.ndarray, time: np.ndarray, time_buffer: int = 5
-) -> np.ndarray:
-    """Find profiles affected by rain.
-
-    Rain is present in such profiles where the radar echo in
-    the third range gate is > 0 dB. To make sure we do not include any
-    rainy profiles, we also flag a few profiles before and after
-    detections as raining.
-
-    Args:
-        z: Radar echo.
-        time: Time vector.
-        time_buffer: Time in minutes.
-
-    Returns:
-        1D Boolean array denoting profiles with rain.
-
-    """
-    is_rain = ma.array(z[:, 3] > 0, dtype=bool).filled(False)
-    is_rain = skimage.morphology.remove_small_objects(
-        is_rain, 2, connectivity=1
-    )  # Filter hot pixels
-    n_profiles = len(time)
-    n_steps = utils.n_elements(time, time_buffer, "time")
-    for ind in np.where(is_rain)[0]:
-        ind1 = max(0, ind - n_steps)
-        ind2 = min(ind + n_steps, n_profiles)
-        is_rain[ind1 : ind2 + 1] = True
-    return is_rain
-
-
-def _find_rainfall_rate(is_rain: np.ndarray, radar) -> np.ndarray:
-    rainfall_rate = ma.zeros(len(is_rain))
-    rainfall_rate[is_rain] = ma.masked
-    if "rainfall_rate" in radar.data:
-        radar_rainfall_rate = radar.data["rainfall_rate"].data
-        ind = np.where(~radar_rainfall_rate.mask)
-        rainfall_rate[ind] = radar_rainfall_rate[ind]
-    else:
-        logging.info("No measured rain rate available")
-    return rainfall_rate
+        self.altitude = data.radar.altitude
+        self.lv0_files = data.lv0_files
+        self.date = data.radar.get_date()
+
+    def _find_profiles_with_rain(self) -> npt.NDArray:
+        is_rain = self._find_rain_from_radar_echo()
+        rain_from_disdrometer = self._find_rain_from_disdrometer()
+        ind = ~rain_from_disdrometer.mask
+        is_rain[ind] = rain_from_disdrometer[ind]
+        # Filter out snowfall:
+        if (
+            self.data.disdrometer is not None
+            and "synop_WaWa" in self.data.disdrometer.data
+        ):
+            wawa = self.data.disdrometer.data["synop_WaWa"].data
+            liquid_rain_only = (wawa >= 57) & (wawa <= 68)
+        else:
+            mask = ma.getmaskarray(self.tw)
+            first_valid_ind = np.nonzero(np.all(~mask, axis=0))[0][0]
+            liquid_rain_only = self.tw[:, first_valid_ind] > T0 + 5
+        return is_rain & liquid_rain_only
+
+    def _find_rain_from_radar_echo(self) -> npt.NDArray:
+        first_gate_with_data = np.argmin(self.z.mask.all(axis=0))
+        gate_number = first_gate_with_data + 3
+        threshold = {"z": 3, "v": 0, "ldr": -15}
+        z = self.z[:, gate_number]
+        v = self.v[:, gate_number]
+        if hasattr(self, "ldr"):
+            ldr = self.ldr[:, gate_number]
+        elif hasattr(self, "sldr"):
+            ldr = self.sldr[:, gate_number]
+        else:
+            ldr = np.full(self.time.shape, threshold["ldr"] - 1)
+
+        return np.where(
+            (~ma.getmaskarray(z))
+            & (z > threshold["z"])
+            & (v < threshold["v"])
+            & (ldr < threshold["ldr"]),
+            1,
+            0,
+        )
+
+    def _find_rain_from_disdrometer(self) -> ma.MaskedArray:
+        if self.data.disdrometer is None:
+            return ma.masked_all(self.time.shape, dtype=int)
+        threshold_mm_h = 0.25  # Standard threshold for drizzle -> rain
+        threshold_particles = 30  # This is arbitrary and should be better tested
+        threshold_rate = threshold_mm_h * MM_H_TO_M_S
+        rainfall_rate = self.data.disdrometer.data["rainfall_rate"].data
+        n_particles = self.data.disdrometer.data["n_particles"].data
+        return ma.array(
+            (rainfall_rate > threshold_rate) & (n_particles > threshold_particles),
+            dtype=int,
+        )
 
 
 def _find_clutter(
     v: np.ma.MaskedArray,
-    is_rain: np.ndarray,
+    is_rain: npt.NDArray,
     n_gates: int = 10,
     v_lim: float = 0.05,
-) -> np.ndarray:
+) -> npt.NDArray:
     """Estimates clutter from doppler velocity.
 
     Args:
+        v: 2D radar velocity.
+        is_rain: 2D boolean array denoting rain.
         n_gates: Number of range gates from the ground where clutter is expected
             to be found. Default is 10.
         v_lim: Velocity threshold. Smaller values are classified as clutter.
@@ -132,6 +162,7 @@ def _find_clutter(
 
     """
     is_clutter = np.zeros(v.shape, dtype=bool)
-    tiny_velocity = (np.abs(v[:, :n_gates]) < v_lim).filled(False)
+    filled = False
+    tiny_velocity = (np.abs(v[:, :n_gates]) < v_lim).filled(filled)
     is_clutter[:, :n_gates] = tiny_velocity * utils.transpose(~is_rain)
     return is_clutter

cloudnetpy/categorize/disdrometer.py

@@ -0,0 +1,40 @@
+"""Mwr module, containing the :class:`Mwr` class."""
+
+from os import PathLike
+
+import numpy.typing as npt
+
+from cloudnetpy.datasource import DataSource
+from cloudnetpy.exceptions import DisdrometerDataError
+from cloudnetpy.utils import interpolate_1d
+
+
+class Disdrometer(DataSource):
+    """Disdrometer class, child of DataSource.
+
+    Args:
+    ----
+         full_path: Cloudnet Level 1b disdrometer file.
+
+    """
+
+    def __init__(self, full_path: str | PathLike) -> None:
+        super().__init__(full_path)
+        self._init_rainfall_rate()
+
+    def interpolate_to_grid(self, time_grid: npt.NDArray) -> None:
+        for key, array in self.data.items():
+            method = "nearest" if key == "synop_WaWa" else "linear"
+            self.data[key].data = interpolate_1d(
+                self.time, array.data, time_grid, max_time=1, method=method
+            )
+
+    def _init_rainfall_rate(self) -> None:
+        keys = ("rainfall_rate", "n_particles", "synop_WaWa")
+        for key in keys:
+            if key not in self.dataset.variables:
+                if key == "synop_WaWa":
+                    continue
+                msg = f"variable {key} is missing"
+                raise DisdrometerDataError(msg)
+            self.append_data(self.dataset.variables[key][:], key)