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

disdrodb/l0/configs/ODM470/l0b_encodings.yml

@@ -0,0 +1,106 @@
+precipitation_rate:
+  dtype: float32
+  zlib: true
+  complevel: 3
+  shuffle: true
+  fletcher32: false
+  contiguous: false
+  chunksizes: 43200
+precip_flag:
+  dtype: int8
+  zlib: true
+  complevel: 3
+  shuffle: true
+  fletcher32: false
+  contiguous: false
+  chunksizes: 43200
+  _FillValue: 127
+reference_voltage:
+  dtype: float32
+  zlib: true
+  complevel: 3
+  shuffle: true
+  fletcher32: false
+  contiguous: false
+  chunksizes: 43200
+weather_code_synop_4677:
+  dtype: uint8
+  zlib: true
+  complevel: 3
+  shuffle: true
+  fletcher32: false
+  contiguous: false
+  chunksizes: 5000
+  _FillValue: 255
+relative_wind_speed:
+  dtype: uint16
+  scale_factor: 0.1
+  add_offset: -99.9
+  zlib: true
+  complevel: 3
+  shuffle: true
+  fletcher32: false
+  contiguous: false
+  _FillValue: 65535
+  chunksizes: 43200
+relative_wind_direction:
+  dtype: uint16
+  zlib: true
+  complevel: 3
+  shuffle: true
+  fletcher32: false
+  contiguous: false
+  _FillValue: 65535
+  chunksizes: 43200
+raw_drop_number:
+  dtype: uint16
+  zlib: true
+  complevel: 3
+  shuffle: true
+  fletcher32: false
+  contiguous: false
+  _FillValue: 65535
+  chunksizes:
+    - 43200
+    - 128
+air_temperature:
+  dtype: uint16
+  scale_factor: 0.1
+  add_offset: -99.9
+  zlib: true
+  complevel: 3
+  shuffle: true
+  fletcher32: false
+  contiguous: false
+  _FillValue: 65535
+  chunksizes: 43200
+relative_humidity:
+  dtype: uint16
+  scale_factor: 0.01
+  zlib: true
+  complevel: 3
+  shuffle: true
+  fletcher32: false
+  contiguous: false
+  _FillValue: 65535
+  chunksizes: 43200
+wind_speed:
+  dtype: uint16
+  scale_factor: 0.1
+  add_offset: -99.9
+  zlib: true
+  complevel: 3
+  shuffle: true
+  fletcher32: false
+  contiguous: false
+  _FillValue: 65535
+  chunksizes: 43200
+wind_direction:
+  dtype: uint16
+  zlib: true
+  complevel: 3
+  shuffle: true
+  fletcher32: false
+  contiguous: false
+  _FillValue: 65535
+  chunksizes: 43200

disdrodb/l0/configs/ODM470/raw_data_format.yml

@@ -0,0 +1,111 @@
+precipitation_rate:
+  n_digits: 6
+  n_characters: 7
+  n_decimals: 3
+  n_naturals: 3
+  data_range:
+    - 0.0
+    - 999.999
+  nan_flags: null
+  field_number: "1"
+reference_voltage:
+  n_digits: 6
+  n_characters: 7
+  n_decimals: 3
+  n_naturals: 3
+  data_range:
+    - 0.0
+    - 5.5
+  nan_flags: null
+  field_number: "2"
+relative_wind_speed:
+  n_digits: 6
+  n_characters: 7
+  n_decimals: 3
+  n_naturals: 3
+  data_range:
+    - 0.0
+    - 100
+  nan_flags: null
+  field_number: "3"
+relative_wind_direction:
+  n_digits: 6
+  n_characters: 7
+  n_decimals: 3
+  n_naturals: 3
+  data_range:
+    - 0.0
+    - 360
+  nan_flags: null
+  field_number: "4"
+precip_flag:
+  n_digits: 1
+  n_characters: 1
+  n_decimals: 0
+  n_naturals: 0
+  data_range:
+    - -1
+    - 5
+  nan_flags: null
+  field_number: "5"
+weather_code_synop_4677:
+  n_digits: 2
+  n_characters: 2
+  n_decimals: 0
+  n_naturals: 2
+  data_range:
+    - 0
+    - 90
+  nan_flags: null
+  field_number: "6"
+raw_drop_number:
+  n_digits: 1317
+  n_characters: 1756
+  n_decimals: 1317
+  n_naturals: 0
+  data_range: null
+  nan_flags: null
+  dimension_order:
+    - diameter_bin_center
+  n_values: 128
+  field_number: "81"
+air_temperature:
+  n_digits: 4
+  n_characters: 5
+  n_decimals: 1
+  n_naturals: 2
+  data_range:
+    - -40
+    - 70
+  nan_flags: 99999
+  field_number: "521"
+relative_humidity:
+  n_digits: 5
+  n_characters: 5
+  n_decimals: 0
+  n_naturals: 5
+  data_range:
+    - 0
+    - 99999
+  nan_flags: 99999
+  field_number: "522"
+wind_speed:
+  n_digits: 3
+  n_characters: 4
+  n_decimals: 1
+  n_naturals: 2
+  data_range:
+    - 0
+    - 60
+  nan_flags: null
+  field_number: "523"
+wind_direction:
+  n_digits: 3
+  n_characters: 3
+  n_decimals: 0
+  n_naturals: 3
+  data_range:
+    - 0
+    - 360
+  nan_flags: 999
+  field_number: "524"

disdrodb/l0/configs/PARSIVEL/l0b_cf_attrs.yml

@@ -121,7 +121,7 @@ reflectivity_16bit:
 raw_drop_concentration:
   description: Particle number concentrations per diameter class
   long_name: Raw drop concentration
-  units: 1/(m3*mm)
+  units: log10 1/(m3*mm)
 raw_drop_average_velocity:
   description: Average particle velocities for each diameter class
   long_name: Raw drop average velocity

disdrodb/l0/l0_reader.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

disdrodb/l0/l0a_processing.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

disdrodb/l0/l0b_nc_processing.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
@@ -50,7 +48,7 @@ def _check_dict_names_validity(dict_names, sensor_name):
     keys = np.array(list(dict_names.keys()))
     values = np.array(list(dict_names.values()))
     # Get invalid keys
-    invalid_keys = keys[np.isin(values, valid_names, invert=True)]
+    invalid_keys = keys[np.isin(values, valid_names, invert=True)].tolist()
     if len(invalid_keys) > 0:
         # Report invalid keys and raise error
         invalid_dict = {k: dict_names[k] for k in invalid_keys}

disdrodb/l0/l0b_processing.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

disdrodb/l0/l0c_processing.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
@@ -340,6 +338,20 @@ def get_problematic_timestep_indices(timesteps, sample_interval):
     return idx_previous_missing, idx_next_missing, idx_isolated_missing
 
 
+def nearest_expected_times(times, expected_times):
+    """Return index of nearest expected time."""
+    # both must be sorted ascending
+    idx = np.searchsorted(expected_times, times)
+    idx = np.clip(idx, 1, len(expected_times) - 1)
+
+    # Compare distance to the previous vs next expected time
+    prev = expected_times[idx - 1]
+    next_ = expected_times[idx]
+    choose_next = (times - prev) > (next_ - times)
+    nearest = np.where(choose_next, next_, prev)
+    return nearest
+
+
 def regularize_timesteps(ds, sample_interval, robust=False, add_quality_flag=True, logger=None, verbose=True):
     """Ensure timesteps match with the sample_interval.
 
@@ -364,13 +376,16 @@ def regularize_timesteps(ds, sample_interval, robust=False, add_quality_flag=Tru
     times = times.to_numpy(dtype="M8[s]")
     expected_times = expected_times.to_numpy(dtype="M8[s]")
 
+    # Vectorized mapping of observed times → nearest expected times
+    adjusted_times = nearest_expected_times(times, expected_times)
+
     # Map original times to the nearest expected times
-    # Calculate the difference between original times and expected times
-    time_deltas = np.abs(times - expected_times[:, None]).astype(int)
+    # # Calculate the difference between original times and expected times
+    # time_deltas = np.abs(times - expected_times[:, None]).astype(int)
 
-    # Find the index of the closest expected time for each original time
-    nearest_indices = np.argmin(time_deltas, axis=0)
-    adjusted_times = expected_times[nearest_indices]
+    # # Find the index of the closest expected time for each original time
+    # nearest_indices = np.argmin(time_deltas, axis=0)
+    # adjusted_times = expected_times[nearest_indices]
 
     # Check for duplicates in adjusted times
     unique_times, counts = np.unique(adjusted_times, return_counts=True)
@@ -466,10 +481,10 @@ def regularize_timesteps(ds, sample_interval, robust=False, add_quality_flag=Tru
         #     qc_flag[-1] = 0
 
         # Add time quality flag variable
-        ds["time_qc"] = xr.DataArray(qc_flag, dims="time")
+        ds["qc_time"] = xr.DataArray(qc_flag, dims="time")
 
-        # Add CF attributes for time_qc
-        ds["time_qc"].attrs = {
+        # Add CF attributes for qc_time
+        ds["qc_time"].attrs = {
             "long_name": "time quality flag",
             "standard_name": "status_flag",
             "units": "1",
@@ -587,6 +602,7 @@ def _finalize_l0c_dataset(ds, sample_interval, sensor_name, verbose=True, logger
     ds = add_sample_interval(ds, sample_interval=sample_interval)
 
     # Regularize timesteps (for trailing seconds)
+    # --> This remove time encoding
     ds = regularize_timesteps(
         ds,
         sample_interval=sample_interval,

disdrodb/l0/readers/LPM/ARM/ARM_LPM.py

@@ -1,6 +1,6 @@
 #!/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

disdrodb/l0/readers/LPM/AUSTRALIA/MELBOURNE_2007_LPM.py

@@ -1,6 +1,6 @@
 #!/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

disdrodb/l0/readers/LPM/BRAZIL/CHUVA_LPM.py

@@ -1,6 +1,6 @@
 #!/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

disdrodb/l0/readers/LPM/BRAZIL/GOAMAZON_LPM.py

@@ -1,6 +1,6 @@
 #!/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

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,16 @@
 # 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 = [
@@ -104,14 +105,90 @@ COLUMNS = [
     "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
+
+    dir_i = (dir_i / 10).round() * 10
+    return pd.Series(dir_i, index=wind_direction.index, name=wind_direction.name)
 
-def read_synop_file(filepath, logger):
+
+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)
+        synop_filepaths.append(*glob.glob(glob_pattern))
+    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 +246,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
@@ -433,7 +603,7 @@ def reader(
 ):
     """Reader."""
     ##------------------------------------------------------------------------.
-    #### - Define raw data headers
+    #### Define raw data headers
     column_names = ["TO_PARSE"]
 
     ##------------------------------------------------------------------------.
@@ -481,11 +651,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