disdrodb 0.2.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

disdrodb/l0/readers/LPM/GERMANY/DWD.py

@@ -1,7 +1,5 @@
-#!/usr/bin/env python3
-
 # -----------------------------------------------------------------------------.
-# Copyright (c) 2021-2023 DISDRODB developers
+# Copyright (c) 2021-2026 DISDRODB developers
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -17,13 +15,17 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 # -----------------------------------------------------------------------------.
 """DISDRODB reader for DWD stations."""
+
+import glob
 import os
+from pathlib import Path
 
 import numpy as np
 import pandas as pd
 
 from disdrodb.l0.l0_reader import is_documented_by, reader_generic_docstring
 from disdrodb.l0.l0a_processing import read_raw_text_file
+from disdrodb.utils.logger import log_error, log_warning
 
 # Assign column names
 COLUMNS = [
@@ -82,36 +84,114 @@ COLUMNS = [
     "number_particles_no_hydrometeor",
     "number_particles_no_hydrometeor_internal_data",
     "number_particles_unknown_classification",
-    "number_particles_unknown_classification_internal_data",
-    "number_particles_class_1",
-    "number_particles_class_1_internal_data",
-    "number_particles_class_2",
-    "number_particles_class_2_internal_data",
-    "number_particles_class_3",
-    "number_particles_class_3_internal_data",
-    "number_particles_class_4",
-    "number_particles_class_4_internal_data",
-    "number_particles_class_5",
-    "number_particles_class_5_internal_data",
-    "number_particles_class_6",
-    "number_particles_class_6_internal_data",
-    "number_particles_class_7",
-    "number_particles_class_7_internal_data",
-    "number_particles_class_8",
-    "number_particles_class_8_internal_data",
+    "total_gross_volume_unknown_classification",
+    "number_particles_hail",
+    "total_gross_volume_hail",
+    "number_particles_solid_precipitation",
+    "total_gross_volume_solid_precipitation",
+    "number_particles_large_pellet",
+    "total_gross_volume_large_pellet",
+    "number_particles_small_pellet",
+    "total_gross_volume_small_pellet",
+    "number_particles_snowgrain",
+    "total_gross_volume_snowgrain",
+    "number_particles_rain",
+    "total_gross_volume_rain",
+    "number_particles_small_rain",
+    "total_gross_volume_small_rain",
+    "number_particles_drizzle",
+    "total_gross_volume_drizzle",
     "number_particles_class_9",
     "number_particles_class_9_internal_data",
     "raw_drop_number",
 ]
 
+####------------------------------------------------------------------------.
+#### SYNOP utilities
+
+
+def _reindex_to_custom_frequency(df, freq="1min"):
+    # Interpolate to 1 min
+    t_start = df.index.min()
+    t_end = df.index.max()
+    timesteps = pd.date_range(
+        start=t_start,
+        end=t_end,
+        freq=freq,
+    )
+    return df.reindex(timesteps)
+
+
+def interpolate_wind_direction(wind_direction, limit=None):
+    """Interpolate NaN values in a 1-min wind direction series.
+
+    Use circular (vector) interpolation.
+
+    Parameters
+    ----------
+    wind_direction : pandas.Series
+        Wind direction in degrees with DateTimeIndex.
+    limit : int or None
+        Max number of consecutive NaNs to fill.
+
+    Returns
+    -------
+    pandas.Series
+        Wind direction with NaNs interpolated.
+    """
+    wind_direction = wind_direction.copy()
+    wind_direction.index = pd.to_datetime(wind_direction.index)
+
+    # Convert to radians
+    theta = np.deg2rad(wind_direction)
+
+    # Vector components
+    u = np.cos(theta)
+    v = np.sin(theta)
+
+    df_vec = pd.DataFrame({"u": u, "v": v}, index=wind_direction.index)
+
+    # Interpolate ONLY NaNs
+    df_vec_i = df_vec.interpolate(
+        method="time",
+        limit=limit,
+    )
+
+    # Back to degrees
+    dir_i = np.rad2deg(np.arctan2(df_vec_i["v"], df_vec_i["u"]))
+    dir_i = (dir_i + 360) % 360
 
-def read_synop_file(filepath, logger):
+    dir_i = (dir_i / 10).round() * 10
+    return pd.Series(dir_i, index=wind_direction.index, name=wind_direction.name)
+
+
+def retrieve_synop_filepaths(df, filepath):
+    """Retrieve SYNOP files relevant for a LPM file."""
+    # Retrieve relevant info to list required synop files
+    filename = os.path.basename(filepath)
+    station_id = filename.split("_")[1]
+    date = df["time"].dt.date.iloc[0]
+    synop_base_dir = Path(filepath).parents[3] / "SYNOP"
+    synop_filepaths = []
+    for d in [date, date + pd.Timedelta(days=1)]:
+        y = d.strftime("%Y")
+        m = d.strftime("%m")
+        ymd = d.strftime("%Y%m%d")
+        fname_pattern = f"synop10min_{station_id}_{ymd}*1.0days.dat"
+        glob_pattern = os.path.join(synop_base_dir, y, m, fname_pattern)
+        files = glob.glob(glob_pattern)
+        if len(files) >= 1:
+            synop_filepaths.append(*files)
+    return synop_filepaths
+
+
+def read_synop_file(filepath, logger=None):
     """Read SYNOP 10 min file."""
     ##------------------------------------------------------------------------.
     #### Define column names
     column_names = [
         "time",
-        "temperature_2m",
+        "air_temperature",
         "relative_humidity",
         "precipitation_accumulated_10min",
         "total_cloud_cover",
@@ -169,6 +249,99 @@ def read_synop_file(filepath, logger):
     return df
 
 
+def _add_nan_synop_variables(df, logger, msg):
+    """Guarantee SYNOP columns on LPM df output."""
+    # Define SYNOP vars to be always present
+    synop_vars = [
+        "air_temperature",
+        "relative_humidity",
+        "wind_speed",
+        "wind_direction",
+    ]
+    # Add SYNOP vars columns
+    log_warning(logger=logger, msg=msg)
+    for v in synop_vars:
+        df[v] = np.nan
+    return df
+
+
+def add_synop_information(df, filepath, logger):
+    """Add SYNOP (10-min) meteorological data to an LPM (1-min) dataframe.
+
+    LPM files contains timesteps: 00:00-23.59
+    SYNOP files contains timesteps: 00:00-23.50
+
+    To interpolate SYNOP data between 00:00-23.59 we need also next-day SYNOP file
+
+    Always returns a dataframe with SYNOP columns present.
+    """
+    # Drop duplicate timesteps from input LPM dataframe
+    df = df.drop_duplicates(subset="time", keep="first").sort_values("time")
+
+    # Retrieve date
+    date = df["time"].iloc[0].date()
+
+    # --------------------------------------------------------------------
+    # Retrieve required SYNOP files
+    synop_filepaths = retrieve_synop_filepaths(df=df, filepath=filepath)
+
+    # If no SYNOP files available
+    if not synop_filepaths:
+        msg = f"No SYNOP files available for {date}"
+        return _add_nan_synop_variables(df, logger=logger, msg=msg)
+
+    # Read relevant SYNOP files
+    synop_dfs = []
+    for f in synop_filepaths:
+        try:
+            synop_dfs.append(read_synop_file(f))
+        except Exception as e:
+            log_error(logger=logger, msg=f"Failed to read SYNOP file {f}. Error: {e!s}")
+
+    if not synop_dfs:
+        msg = f"No valid SYNOP data could be read for {date}"
+        return _add_nan_synop_variables(df, logger=logger, msg=msg)
+
+    # Concatenate SYNOP files into unique dataframe
+    df_synop_10min = pd.concat(synop_dfs, ignore_index=True)
+
+    # --------------------------------------------------------------------
+    # Subset SYNOP file
+    tmin = df["time"].min() - pd.Timedelta(minutes=10)
+    tmax = df["time"].max() + pd.Timedelta(minutes=10)
+    df_synop_10min = df_synop_10min[(df_synop_10min["time"] >= tmin) & (df_synop_10min["time"] <= tmax)]
+    if df_synop_10min.empty:
+        msg = f"No SYNOP data available for {date}"
+        return _add_nan_synop_variables(df, logger=logger, msg=msg)
+
+    # Drop time duplicates if present
+    df_synop_10min = df_synop_10min.drop_duplicates(subset="time", keep="first")
+    df_synop_10min = df_synop_10min.drop(columns=["total_cloud_cover", "precipitation_accumulated_10min"])
+    # Reindex SYNOP 10 min file to 1 min
+    df_synop_10min = df_synop_10min.set_index("time")  # set time column as index
+    df_synop_10min = df_synop_10min.astype(float)  # cast column to float
+    df_synop_1min = _reindex_to_custom_frequency(df_synop_10min, freq="1min")
+    # Interpolate variables
+    df_synop_1min["wind_direction"] = interpolate_wind_direction(df_synop_1min["wind_direction"], limit=9)
+    variables = ["air_temperature", "relative_humidity", "wind_speed"]
+    df_synop_1min[variables] = df_synop_1min[variables].interpolate(method="time", limit=9)
+    df_synop_1min = df_synop_1min.reset_index().rename(columns={"index": "time"})
+    # Merge data
+    df_synop_1min = df_synop_1min.drop_duplicates(subset="time", keep="first").sort_values("time")
+    df_merged = pd.merge_asof(
+        df,
+        df_synop_1min,
+        on="time",
+        direction="nearest",  # or "backward" / "forward"
+        tolerance=pd.Timedelta("0min"),
+    )
+    return df_merged
+
+
+####-------------------------------------------------------------------------.
+#### LPM parsers
+
+
 def parse_format_v1(df):
     """Parse DWD format v1."""
     raise NotImplementedError
@@ -246,23 +419,23 @@ def parse_format_v2(df):
         "number_particles_no_hydrometeor",
         "number_particles_no_hydrometeor_internal_data",
         "number_particles_unknown_classification",
-        "number_particles_unknown_classification_internal_data",
-        "number_particles_class_1",
-        "number_particles_class_1_internal_data",
-        "number_particles_class_2",
-        "number_particles_class_2_internal_data",
-        "number_particles_class_3",
-        "number_particles_class_3_internal_data",
-        "number_particles_class_4",
-        "number_particles_class_4_internal_data",
-        "number_particles_class_5",
-        "number_particles_class_5_internal_data",
-        "number_particles_class_6",
-        "number_particles_class_6_internal_data",
-        "number_particles_class_7",
-        "number_particles_class_7_internal_data",
-        "number_particles_class_8",
-        "number_particles_class_8_internal_data",
+        "total_gross_volume_unknown_classification",
+        "number_particles_hail",
+        "total_gross_volume_hail",
+        "number_particles_solid_precipitation",
+        "total_gross_volume_solid_precipitation",
+        "number_particles_large_pellet",
+        "total_gross_volume_large_pellet",
+        "number_particles_small_pellet",
+        "total_gross_volume_small_pellet",
+        "number_particles_snowgrain",
+        "total_gross_volume_snowgrain",
+        "number_particles_rain",
+        "total_gross_volume_rain",
+        "number_particles_small_rain",
+        "total_gross_volume_small_rain",
+        "number_particles_drizzle",
+        "total_gross_volume_drizzle",
         "number_particles_class_9",
         "number_particles_class_9_internal_data",
         "raw_drop_number",
@@ -366,23 +539,23 @@ def parse_format_v3(df):
         # "number_particles_no_hydrometeor",
         # "number_particles_no_hydrometeor_internal_data",
         # "number_particles_unknown_classification",
-        # "number_particles_unknown_classification_internal_data",
-        # "number_particles_class_1",
-        # "number_particles_class_1_internal_data",
-        # "number_particles_class_2",
-        # "number_particles_class_2_internal_data",
-        # "number_particles_class_3",
-        # "number_particles_class_3_internal_data",
-        # "number_particles_class_4",
-        # "number_particles_class_4_internal_data",
-        # "number_particles_class_5",
-        # "number_particles_class_5_internal_data",
-        # "number_particles_class_6",
-        # "number_particles_class_6_internal_data",
-        # "number_particles_class_7",
-        # "number_particles_class_7_internal_data",
-        # "number_particles_class_8",
-        # "number_particles_class_8_internal_data",
+        # "total_gross_volume_unknown_classification",
+        # "number_particles_hail",
+        # "total_gross_volume_hail",
+        # "number_particles_solid_precipitation",
+        # "total_gross_volume_solid_precipitation",
+        # "number_particles_large_pellet",
+        # "total_gross_volume_large_pellet",
+        # "number_particles_small_pellet",
+        # "total_gross_volume_small_pellet",
+        # "number_particles_snowgrain",
+        # "total_gross_volume_snowgrain",
+        # "number_particles_rain",
+        # "total_gross_volume_rain",
+        # "number_particles_small_rain",
+        # "total_gross_volume_small_rain",
+        # "number_particles_drizzle",
+        # "total_gross_volume_drizzle",
         # "number_particles_class_9",
         # "number_particles_class_9_internal_data",
         "raw_drop_number",
@@ -433,7 +606,7 @@ def reader(
 ):
     """Reader."""
     ##------------------------------------------------------------------------.
-    #### - Define raw data headers
+    #### Define raw data headers
     column_names = ["TO_PARSE"]
 
     ##------------------------------------------------------------------------.
@@ -481,11 +654,19 @@ def reader(
     )
     ##------------------------------------------------------------------------.
     #### Adapt the dataframe to adhere to DISDRODB L0 standards
+    # Read LPM raw data
     filename = os.path.basename(filepath)
     if filename.startswith("3_"):
-        return parse_format_v3(df)
-    if filename.startswith("2_"):
-        return parse_format_v2(df)
-    if filename.startswith("1_"):
-        return parse_format_v1(df)
-    raise ValueError(f"Not implemented parser for DWD {filepath} data format.")
+        df = parse_format_v3(df)
+    elif filename.startswith("2_"):
+        df = parse_format_v2(df)
+    elif filename.startswith("1_"):
+        df = parse_format_v1(df)
+    else:
+        raise ValueError(f"Not implemented parser for DWD {filepath} data format.")
+
+    # Add SYNOP data if available
+    df = add_synop_information(df=df, filepath=filepath, logger=logger)
+
+    # Return dataframe
+    return df

disdrodb/l0/readers/LPM/ITALY/GID_LPM.py

@@ -1,7 +1,5 @@
-#!/usr/bin/env python3
-
 # -----------------------------------------------------------------------------.
-# Copyright (c) 2021-2023 DISDRODB developers
+# Copyright (c) 2021-2026 DISDRODB developers
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -17,10 +15,15 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 # -----------------------------------------------------------------------------.
 """DISDRODB reader for GID LPM sensors not measuring wind."""
+
+import os
+
+import numpy as np
 import pandas as pd
 
 from disdrodb.l0.l0_reader import is_documented_by, reader_generic_docstring
 from disdrodb.l0.l0a_processing import read_raw_text_file
+from disdrodb.utils.logger import log_warning
 
 
 @is_documented_by(reader_generic_docstring)
@@ -50,6 +53,9 @@ def reader(
     # - Number of rows to be skipped at the beginning of the file
     reader_kwargs["skiprows"] = None
 
+    # - Define encoding
+    reader_kwargs["encoding"] = "latin"
+
     # - Define behaviour when encountering bad lines
     reader_kwargs["on_bad_lines"] = "skip"
 
@@ -155,23 +161,23 @@ def reader(
         "number_particles_no_hydrometeor",
         "number_particles_no_hydrometeor_internal_data",
         "number_particles_unknown_classification",
-        "number_particles_unknown_classification_internal_data",
-        "number_particles_class_1",
-        "number_particles_class_1_internal_data",
-        "number_particles_class_2",
-        "number_particles_class_2_internal_data",
-        "number_particles_class_3",
-        "number_particles_class_3_internal_data",
-        "number_particles_class_4",
-        "number_particles_class_4_internal_data",
-        "number_particles_class_5",
-        "number_particles_class_5_internal_data",
-        "number_particles_class_6",
-        "number_particles_class_6_internal_data",
-        "number_particles_class_7",
-        "number_particles_class_7_internal_data",
-        "number_particles_class_8",
-        "number_particles_class_8_internal_data",
+        "total_gross_volume_unknown_classification",
+        "number_particles_hail",
+        "total_gross_volume_hail",
+        "number_particles_solid_precipitation",
+        "total_gross_volume_solid_precipitation",
+        "number_particles_large_pellet",
+        "total_gross_volume_large_pellet",
+        "number_particles_small_pellet",
+        "total_gross_volume_small_pellet",
+        "number_particles_snowgrain",
+        "total_gross_volume_snowgrain",
+        "number_particles_rain",
+        "total_gross_volume_rain",
+        "number_particles_small_rain",
+        "total_gross_volume_small_rain",
+        "number_particles_drizzle",
+        "total_gross_volume_drizzle",
         "number_particles_class_9",
         "number_particles_class_9_internal_data",
         "raw_drop_number",
@@ -181,9 +187,45 @@ def reader(
     # Remove checksum from raw_drop_number
     df["raw_drop_number"] = df["raw_drop_number"].str.strip(";").str.rsplit(";", n=1, expand=True)[0]
 
-    # Define datetime "time" column
-    df["time"] = df["sensor_date"] + "-" + df["sensor_time"]
-    df["time"] = pd.to_datetime(df["time"], format="%d.%m.%y-%H:%M:%S", errors="coerce")
+    # Identify rows with bad sensor date (compared to file name)
+    filename = os.path.basename(filepath)
+    file_date_str = filename[0:8]
+    idx_bad_date = df["sensor_date"] != pd.to_datetime(file_date_str, format="%Y%m%d").strftime("%d.%m.%y")
+
+    # If all rows have bad sensor_date, use the one of the file name
+    if idx_bad_date.all():
+        # -  Infer and define "time" column
+        start_time_str = filename[0:10]
+        start_time = pd.to_datetime(start_time_str, format="%Y%m%d%H")
+
+        # - Define timedelta based on sensor_time
+        # --> Add +24h to subsequent times when time resets
+        dt = pd.to_timedelta(df["sensor_time"]).to_numpy().astype("m8[s]")
+        rollover_indices = np.where(np.diff(dt) < np.timedelta64(0, "s"))[0]
+        if rollover_indices.size > 0:
+            for idx in rollover_indices:
+                dt[idx + 1 :] += np.timedelta64(24, "h")
+        dt = dt - dt[0]
+
+        # - Define approximate time
+        df["time"] = start_time + dt
+
+        # - Keep rows where time increment is between 00 and 59 minutes
+        valid_rows = dt <= np.timedelta64(3540, "s")
+        df = df[valid_rows]
+
+    # If only some rows have bad sensor date, just drop such bad rows
+    else:
+        if idx_bad_date.any():
+            # Remove rows with bad dates
+            bad_dates = df[idx_bad_date]["sensor_date"].unique().tolist()
+            df = df[~idx_bad_date]
+            msg = f"{filepath} contain rows with the following unexpected sensor_date values {bad_dates}"
+            log_warning(msg=msg, logger=logger)
+
+        # Define datetime "time" column
+        df["time"] = df["sensor_date"] + "-" + df["sensor_time"]
+        df["time"] = pd.to_datetime(df["time"], format="%d.%m.%y-%H:%M:%S", errors="coerce")
 
     # Drop row if start_identifier different than 00
     df = df[df["start_identifier"].astype(str) == "00"]