disdrodb 0.0.21__py3-none-any.whl → 0.1.1__py3-none-any.whl

disdrodb/l0/standards.py

@@ -18,8 +18,6 @@
 # -----------------------------------------------------------------------------.
 """Retrieve L0 sensor standards."""
 
-import datetime
-import importlib
 import logging
 
 import numpy as np
@@ -29,10 +27,34 @@ from disdrodb.api.configs import read_config_file
 
 logger = logging.getLogger(__name__)
 
-PRODUCT_VERSION = "V0"
-SOFTWARE_VERSION = "V" + importlib.metadata.version("disdrodb")
-CONVENTIONS = "CF-1.10, ACDD-1.3"
-EPOCH = "seconds since 1970-01-01 00:00:00"
+
+####-------------------------------------------------------------------------.
+#### Sensor variables
+
+
+def get_sensor_logged_variables(sensor_name: str) -> list:
+    """Get the sensor logged variables list.
+
+    Parameters
+    ----------
+    sensor_name : str
+         Name of the sensor.
+
+    Returns
+    -------
+    list
+        List of the variables logged by the sensor.
+    """
+    return list(get_data_format_dict(sensor_name).keys())
+
+
+def allowed_l0_variables(sensor_name: str) -> list:
+    """Get the list of allowed L0 variables for a given sensor."""
+    sensor_variables = list(get_l0a_dtype(sensor_name))
+    weather_variables = ["air_temperature", "relative_humidity", "wind_speed", "wind_direction"]
+    allowed_variables = [*sensor_variables, *weather_variables, "time", "latitude", "longitude", "altitude"]
+    allowed_variables = sorted(np.unique(allowed_variables).tolist())
+    return allowed_variables
 
 
 ####--------------------------------------------------------------------------.
@@ -59,27 +81,9 @@ def get_data_format_dict(sensor_name: str) -> dict:
     dict
         Data format of each sensor variable.
     """
-
     return read_config_file(sensor_name=sensor_name, product="L0A", filename="raw_data_format.yml")
 
 
-def get_sensor_logged_variables(sensor_name: str) -> list:
-    """Get the sensor logged variables list.
-
-    Parameters
-    ----------
-    sensor_name : str
-         Name of the sensor.
-
-    Returns
-    -------
-    list
-        List of the variables logged by the sensor.
-    """
-
-    return list(get_data_format_dict(sensor_name).keys())
-
-
 def get_data_range_dict(sensor_name: str) -> dict:
     """Get the variable data range.
 
@@ -94,10 +98,9 @@ def get_data_range_dict(sensor_name: str) -> dict:
         Dictionary with the expected data value range for each data field.
         It excludes variables without specified data_range key.
     """
-
     data_format_dict = get_data_format_dict(sensor_name)
     dict_data_range = {}
-    for k in data_format_dict.keys():
+    for k in data_format_dict:
         data_range = data_format_dict[k].get("data_range", None)
         if data_range is not None:
             dict_data_range[k] = data_range
@@ -118,10 +121,9 @@ def get_nan_flags_dict(sensor_name: str) -> dict:
         Dictionary with the expected nan_flags list for each data field.
         It excludes variables without specified nan_flags key.
     """
-
     data_format_dict = get_data_format_dict(sensor_name)
     dict_nan_flags = {}
-    for k in data_format_dict.keys():
+    for k in data_format_dict:
         nan_flags = data_format_dict[k].get("nan_flags", None)
         if nan_flags is not None:
             dict_nan_flags[k] = _ensure_list_value(nan_flags)
@@ -144,7 +146,7 @@ def get_valid_values_dict(sensor_name: str) -> dict:
     """
     data_format_dict = get_data_format_dict(sensor_name)
     dict_valid_values = {}
-    for k in data_format_dict.keys():
+    for k in data_format_dict:
         valid_values = data_format_dict[k].get("valid_values", None)
         if valid_values is not None:
             dict_valid_values[k] = _ensure_list_value(valid_values)
@@ -156,7 +158,7 @@ def get_valid_values_dict(sensor_name: str) -> dict:
 def get_field_ndigits_natural_dict(sensor_name: str) -> dict:
     """Get number of digits on the left side of the comma from the instrument default string standards.
 
-    Example: 123,45 -> 123 --> 3 natural digits
+    Example: 123,45 -> 123 --> 3 natural digits.
 
     Parameters
     ----------
@@ -168,7 +170,6 @@ def get_field_ndigits_natural_dict(sensor_name: str) -> dict:
     dict
         Dictionary with the expected number of natural digits for each data field.
     """
-
     data_dict = get_data_format_dict(sensor_name)
     d = {k: v["n_naturals"] for k, v in data_dict.items()}
     return d
@@ -177,7 +178,8 @@ def get_field_ndigits_natural_dict(sensor_name: str) -> dict:
 def get_field_ndigits_decimals_dict(sensor_name: dict) -> dict:
     """Get number of digits on the right side of the comma from the instrument default string standards.
 
-    Example: 123,45 -> 45 --> 2 decimal digits
+    Example: 123,45 -> 45 --> 2 decimal digits.
+
     Parameters
     ----------
     sensor_name : dict
@@ -188,7 +190,6 @@ def get_field_ndigits_decimals_dict(sensor_name: dict) -> dict:
     dict
         Dictionary with the expected number of decimal digits for each data field.
     """
-
     data_dict = get_data_format_dict(sensor_name)
     d = {k: v["n_decimals"] for k, v in data_dict.items()}
     return d
@@ -204,12 +205,12 @@ def get_field_ndigits_dict(sensor_name: str) -> dict:
     ----------
     sensor_name : str
         Name of the sensor.
+
     Returns
     -------
     dict
         Dictionary with the expected number of digits for each data field.
     """
-
     data_dict = get_data_format_dict(sensor_name)
     d = {k: v["n_digits"] for k, v in data_dict.items()}
     return d
@@ -231,7 +232,6 @@ def get_field_nchar_dict(sensor_name: str) -> dict:
     dict
         Dictionary with the expected number of characters for each data field.
     """
-
     data_dict = get_data_format_dict(sensor_name)
     d = {k: v["n_characters"] for k, v in data_dict.items()}
     return d
@@ -258,156 +258,12 @@ def get_l0b_cf_attrs_dict(sensor_name: str) -> dict:
     return read_config_file(sensor_name=sensor_name, product="L0A", filename="l0b_cf_attrs.yml")
 
 
-####-------------------------------------------------------------------------.
-#### Coordinates attributes
-
-
-def get_coords_attrs_dict(ds):
-    """Return dictionary with DISDRODB coordinates attributes."""
-    attrs_dict = {}
-    # Define diameter attributes
-    attrs_dict["diameter_bin_center"] = {
-        "name": "diameter_bin_center",
-        "standard_name": "diameter_bin_center",
-        "long_name": "diameter_bin_center",
-        "units": "mm",
-        "description": "Bin center drop diameter value",
-    }
-    attrs_dict["diameter_bin_width"] = {
-        "name": "diameter_bin_width",
-        "standard_name": "diameter_bin_width",
-        "long_name": "diameter_bin_width",
-        "units": "mm",
-        "description": "Drop diameter bin width",
-    }
-    attrs_dict["diameter_bin_upper"] = {
-        "name": "diameter_bin_upper",
-        "standard_name": "diameter_bin_upper",
-        "long_name": "diameter_bin_upper",
-        "units": "mm",
-        "description": "Bin upper bound drop diameter value",
-    }
-    attrs_dict["velocity_bin_lower"] = {
-        "name": "velocity_bin_lower",
-        "standard_name": "velocity_bin_lower",
-        "long_name": "velocity_bin_lower",
-        "units": "mm",
-        "description": "Bin lower bound drop diameter value",
-    }
-    # Define velocity attributes
-    attrs_dict["velocity_bin_center"] = {
-        "name": "velocity_bin_center",
-        "standard_name": "velocity_bin_center",
-        "long_name": "velocity_bin_center",
-        "units": "m/s",
-        "description": "Bin center drop fall velocity value",
-    }
-    attrs_dict["velocity_bin_width"] = {
-        "name": "velocity_bin_width",
-        "standard_name": "velocity_bin_width",
-        "long_name": "velocity_bin_width",
-        "units": "m/s",
-        "description": "Drop fall velocity bin width",
-    }
-    attrs_dict["velocity_bin_upper"] = {
-        "name": "velocity_bin_upper",
-        "standard_name": "velocity_bin_upper",
-        "long_name": "velocity_bin_upper",
-        "units": "m/s",
-        "description": "Bin upper bound drop fall velocity value",
-    }
-    attrs_dict["velocity_bin_lower"] = {
-        "name": "velocity_bin_lower",
-        "standard_name": "velocity_bin_lower",
-        "long_name": "velocity_bin_lower",
-        "units": "m/s",
-        "description": "Bin lower bound drop fall velocity value",
-    }
-    # Define geolocation attributes
-    attrs_dict["latitude"] = {
-        "name": "latitude",
-        "standard_name": "latitude",
-        "long_name": "Latitude",
-        "units": "degrees_north",
-    }
-    attrs_dict["longitude"] = {
-        "name": "longitude",
-        "standard_name": "longitude",
-        "long_name": "Longitude",
-        "units": "degrees_east",
-    }
-    attrs_dict["altitude"] = {
-        "name": "altitude",
-        "standard_name": "altitude",
-        "long_name": "Altitude",
-        "units": "m",
-        "description": "Elevation above sea level",
-    }
-    # Define time attributes
-    attrs_dict["time"] = {
-        "name": "time",
-        "standard_name": "time",
-        "long_name": "time",
-        "description": "UTC Time",
-    }
-
-    return attrs_dict
-
-
-####-------------------------------------------------------------------------.
-#### DISDRODB attributes
-
-
-def set_disdrodb_attrs(ds, product: str):
-    """Add DISDRODB processing information to the netCDF global attributes.
-
-    It assumes stations metadata are already added the dataset.
-
-    Parameters
-    ----------
-    ds : xarray dataset
-        Dataset
-    product: str
-        DISDRODB product
-
-    Returns
-    -------
-    xarray dataset
-        Dataset
-    """
-    # Add dataset conventions
-    ds.attrs["Conventions"] = CONVENTIONS
-
-    # Add featureType
-    platform_type = ds.attrs["platform_type"]
-    if platform_type == "fixed":
-        ds.attrs["featureType"] = "timeSeries"
-    else:
-        ds.attrs["featureType"] = "trajectory"
-
-    # Add time_coverage_start and time_coverage_end
-    ds.attrs["time_coverage_start"] = str(ds["time"].data[0])
-    ds.attrs["time_coverage_end"] = str(ds["time"].data[-1])
-
-    # DISDRODDB attributes
-    # - Add DISDRODB processing info
-    now = datetime.datetime.utcnow()
-    current_time = now.strftime("%Y-%m-%d %H:%M:%S")
-    ds.attrs["disdrodb_processing_date"] = current_time
-    # - Add DISDRODB product and version
-    ds.attrs["disdrodb_product_version"] = PRODUCT_VERSION
-    ds.attrs["disdrodb_software_version"] = SOFTWARE_VERSION
-    ds.attrs["disdrodb_product"] = product
-
-    return ds
-
-
 ####-------------------------------------------------------------------------.
 #### Bin Coordinates Information
 
 
 def get_diameter_bins_dict(sensor_name: str) -> dict:
-    """Get dictionary with sensor_name diameter bins information.
+    """Get dictionary with ``sensor_name`` diameter bins information.
 
     Parameters
     ----------
@@ -417,7 +273,7 @@ def get_diameter_bins_dict(sensor_name: str) -> dict:
     Returns
     -------
     dict
-        sensor_name diameter bins information
+        Sensor diameter bins information.
     """
     d = read_config_file(sensor_name=sensor_name, product="L0A", filename="bins_diameter.yml")
     return d
@@ -429,12 +285,12 @@ def get_diameter_bin_center(sensor_name: str) -> list:
     Parameters
     ----------
     sensor_name : str
-        Name of the sensor
+        Name of the sensor.
 
     Returns
     -------
     list
-        Diameter bin center
+        Diameter bin center.
     """
     diameter_dict = get_diameter_bins_dict(sensor_name)
     diameter_bin_center = list(diameter_dict["center"].values())
@@ -447,12 +303,12 @@ def get_diameter_bin_lower(sensor_name: str) -> list:
     Parameters
     ----------
     sensor_name : str
-        Name of the sensor
+        Name of the sensor.
 
     Returns
     -------
     list
-        Diameter bin lower bound
+        Diameter bin lower bound.
     """
     diameter_dict = get_diameter_bins_dict(sensor_name)
     lower_bounds = [v[0] for v in diameter_dict["bounds"].values()]
@@ -465,12 +321,12 @@ def get_diameter_bin_upper(sensor_name: str) -> list:
     Parameters
     ----------
     sensor_name : str
-        Name of the sensor
+        Name of the sensor.
 
     Returns
     -------
     list
-        Diameter bin upper bound
+        Diameter bin upper bound.
     """
     diameter_dict = get_diameter_bins_dict(sensor_name)
     upper_bounds = [v[1] for v in diameter_dict["bounds"].values()]
@@ -483,12 +339,12 @@ def get_diameter_bin_width(sensor_name: str) -> list:
     Parameters
     ----------
     sensor_name : str
-        Name of the sensor
+        Name of the sensor.
 
     Returns
     -------
     list
-        Diameter bin width
+        Diameter bin width.
     """
     diameter_dict = get_diameter_bins_dict(sensor_name)
     diameter_bin_width = list(diameter_dict["width"].values())
@@ -496,7 +352,7 @@ def get_diameter_bin_width(sensor_name: str) -> list:
 
 
 def get_velocity_bins_dict(sensor_name: str) -> dict:
-    """Get velocity with sensor_name diameter bins information.
+    """Get velocity with ``sensor_name`` diameter bins information.
 
     Parameters
     ----------
@@ -506,7 +362,7 @@ def get_velocity_bins_dict(sensor_name: str) -> dict:
     Returns
     -------
     dict
-        Sensor_name diameter bins information
+        Sensor velocity bins information.
     """
     d = read_config_file(sensor_name=sensor_name, product="L0A", filename="bins_velocity.yml")
     return d
@@ -518,12 +374,12 @@ def get_velocity_bin_center(sensor_name: str) -> list:
     Parameters
     ----------
     sensor_name : str
-        Name of the sensor
+        Name of the sensor.
 
     Returns
     -------
     list
-        Velocity bin center
+        Velocity bin center.
     """
     velocity_dict = get_velocity_bins_dict(sensor_name)
     if velocity_dict is not None:
@@ -539,7 +395,7 @@ def get_velocity_bin_lower(sensor_name: str) -> list:
     Parameters
     ----------
     sensor_name : str
-        Name of the sensor
+        Name of the sensor.
 
     Returns
     -------
@@ -560,14 +416,13 @@ def get_velocity_bin_upper(sensor_name: str) -> list:
     Parameters
     ----------
     sensor_name : str
-        Name of the sensor
+        Name of the sensor.
 
     Returns
     -------
     list
-        Velocity bin upper bound
+        Velocity bin upper bound.
     """
-
     velocity_dict = get_velocity_bins_dict(sensor_name)
     if velocity_dict is not None:
         upper_bounds = [v[1] for v in velocity_dict["bounds"].values()]
@@ -582,14 +437,13 @@ def get_velocity_bin_width(sensor_name: str) -> list:
     Parameters
     ----------
     sensor_name : str
-        Name of the sensor
+        Name of the sensor.
 
     Returns
     -------
     list
-        Velocity bin width
+        Velocity bin width.
     """
-
     velocity_dict = get_velocity_bins_dict(sensor_name)
     if velocity_dict is not None:
         velocity_bin_width = list(velocity_dict["width"].values())
@@ -609,10 +463,9 @@ def get_bin_coords_dict(sensor_name: str) -> dict:
     Returns
     -------
     dict
-        Dictionary with coordinate arrays.
+        Dictionary with coordinates arrays.
     """
-
-    check_sensor_name(sensor_name=sensor_name)
+    check_sensor_name(sensor_name)
     coords = {}
     # Retrieve diameter coords
     coords["diameter_bin_center"] = get_diameter_bin_center(sensor_name=sensor_name)
@@ -661,10 +514,7 @@ def get_n_velocity_bins(sensor_name):
     """Get the number of velocity bins."""
     # Retrieve number of bins
     velocity_dict = get_velocity_bins_dict(sensor_name)
-    if velocity_dict is None:
-        n_velocity_bins = 0
-    else:
-        n_velocity_bins = len(velocity_dict["center"])
+    n_velocity_bins = 0 if velocity_dict is None else len(velocity_dict["center"])
     return n_velocity_bins
 
 
@@ -683,16 +533,15 @@ def get_l0a_dtype(sensor_name: str) -> dict:
     Returns
     -------
     dict
-        L0A dtype
+        Dictionary with the L0A dtype.
     """
-
     # Note: This function could extract the info from l0a_encodings in future.
     d = read_config_file(sensor_name=sensor_name, product="L0A", filename="l0a_encodings.yml")
     return d
 
 
 def get_l0a_encodings_dict(sensor_name: str) -> dict:
-    """Get a dictionary containing the L0A encodings
+    """Get a dictionary containing the L0A encodings.
 
     Parameters
     ----------
@@ -702,9 +551,8 @@ def get_l0a_encodings_dict(sensor_name: str) -> dict:
     Returns
     -------
     dict
-        L0A encodings
+        L0A encodings.
     """
-
     # - l0a_encodings.yml currently specify only the dtype. This could be expanded in the future.
     d = read_config_file(sensor_name=sensor_name, product="L0A", filename="l0a_encodings.yml")
     return d
@@ -715,15 +563,17 @@ def _check_contiguous_chunksize_agrees(encoding_dict, var):
     contiguous = encoding_dict[var].get("contiguous", False)
     if isinstance(chunksizes, list) and len(chunksizes) >= 1 and contiguous:
         raise ValueError(
-            f"Invalid encodings for variable {var}. 'chunksizes' are specified but 'contiguous' is set to True !"
+            f"Invalid encodings for variable {var}. 'chunksizes' are specified but 'contiguous' is set to True !",
         )
 
 
 def _if_no_chunksizes_set_contiguous(encoding_dict, var):
-    if isinstance(encoding_dict[var].get("chunksizes", None), type(None)):
-        if not encoding_dict[var].get("contiguous", False):
-            encoding_dict[var]["contiguous"] = True
-            print(f"Set contiguous=True for variable {var} because chunksizes=None")
+    if isinstance(encoding_dict[var].get("chunksizes", None), type(None)) and not encoding_dict[var].get(
+        "contiguous",
+        False,
+    ):
+        encoding_dict[var]["contiguous"] = True
+        print(f"Set contiguous=True for variable {var} because chunksizes=None")
     return encoding_dict
 
 
@@ -746,7 +596,7 @@ def _ensure_valid_chunksizes(encoding_dict, var):
 
 
 def _ensure_valid_netcdf_encoding_dict(encoding_dict):
-    for var in encoding_dict.keys():
+    for var in encoding_dict:
         _check_contiguous_chunksize_agrees(encoding_dict, var)
         # Ensure valid arguments for contiguous (unchunked) arrays
         encoding_dict = _if_no_chunksizes_set_contiguous(encoding_dict, var)
@@ -774,20 +624,6 @@ def get_l0b_encodings_dict(sensor_name: str) -> dict:
     return encoding_dict
 
 
-def get_time_encoding() -> dict:
-    """Create time encoding
-
-    Returns
-    -------
-    dict
-        Time encoding
-    """
-    encoding = {}
-    encoding["units"] = EPOCH
-    encoding["calendar"] = "proleptic_gregorian"
-    return encoding
-
-
 ####-------------------------------------------------------------------------.
 #### L0B processing tools
 
@@ -822,21 +658,24 @@ def get_raw_array_dims_order(sensor_name: str) -> dict:
     The order of dimension specified for raw_drop_number controls the
     reshaping of the precipitation raw spectrum.
 
-    Examples:
-        OTT Parsivel spectrum [v1d1 ... v1d32, v2d1, ..., v2d32]
+    Examples
+    --------
+        OTT Parsivel spectrum [d1v1 ... d32v1, d1v2, ..., d32v2] (diameter increases first)
         --> dimension_order = ["velocity_bin_center", "diameter_bin_center"]
-        Thies LPM spectrum [v1d1 ... v20d1, v1d2, ..., v20d2]
+        Thies LPM spectrum [v1d1 ... v20d1, v1d2, ..., v20d2]  (velocity increases first)
+        --> dimension_order = ["diameter_bin_center", "velocity_bin_center"]
+        PWS 100 spectrum [d1v1 ... d1v34, d2v1, ..., d2v34] (velocity increases first)
         --> dimension_order = ["diameter_bin_center", "velocity_bin_center"]
 
     Parameters
     ----------
     sensor_name : str
-        Name of the sensor
+        Name of the sensor.
 
     Returns
     -------
     dict
-        Dimension order dictionary
+        Dimension order dictionary.
 
     """
     # Retrieve data format dictionary
@@ -906,7 +745,7 @@ def get_valid_dimension_names(sensor_name):
     list_dimensions = list(dims_dict.values())  # for each array variable
     list_dimensions = [item for sublist in list_dimensions for item in sublist]
     valid_dims = np.unique(list_dimensions).tolist()
-    dimensions = ["time"] + valid_dims
+    dimensions = ["time", *valid_dims]
     return dimensions