disdrodb 0.2.0__py3-none-any.whl → 0.3.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,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

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,14 @@
 # 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)
@@ -31,7 +33,7 @@ def reader(
     """Reader."""
     ##------------------------------------------------------------------------.
     #### - Define raw data headers
-    column_names = ["TO_BE_SPLITTED"]
+    column_names = ["TO_PARSE"]
 
     ##------------------------------------------------------------------------.
     #### Define reader options
@@ -50,6 +52,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"
 
@@ -79,14 +84,22 @@ def reader(
 
     ##------------------------------------------------------------------------.
     #### Adapt the dataframe to adhere to DISDRODB L0 standards
-    # Count number of delimiters to identify valid rows
-    df = df[df["TO_BE_SPLITTED"].str.count(";") == 519]
+    # Raise error if empty file
+    if len(df) == 0:
+        raise ValueError(f"{filepath} is empty.")
+
+    # Select only rows with expected number of delimiters
+    df = df[df["TO_PARSE"].str.count(";").isin([519, 520])]
+
+    # Check there are still valid rows
+    if len(df) == 0:
+        raise ValueError(f"No valid rows in {filepath}.")
 
     # Split by ; delimiter (before raw drop number)
-    df = df["TO_BE_SPLITTED"].str.split(";", expand=True, n=79)
+    df = df["TO_PARSE"].str.split(";", expand=True, n=79)
 
     # Assign column names
-    column_names = [
+    names = [
         "start_identifier",
         "device_address",
         "sensor_serial_number",
@@ -168,14 +181,50 @@ def reader(
         "number_particles_class_9_internal_data",
         "raw_drop_number",
     ]
-    df.columns = column_names
+    df.columns = names
 
     # Remove checksum from raw_drop_number
-    df["raw_drop_number"] = df["raw_drop_number"].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")
+    df["raw_drop_number"] = df["raw_drop_number"].str.strip(";").str.rsplit(";", n=1, expand=True)[0]
+
+    # 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"]

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

@@ -0,0 +1,279 @@
+# -----------------------------------------------------------------------------.
+# 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
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+# -----------------------------------------------------------------------------.
+"""DISDRODB reader for GID LPM sensor TC-PI with incorrect reported time."""
+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
+
+
+def read_txt_file(file, filename, logger):
+    """Parse for TC-PI LPM file."""
+    #### - Define raw data headers
+    column_names = ["TO_PARSE"]
+
+    ##------------------------------------------------------------------------.
+    #### Define reader options
+    # - For more info: https://pandas.pydata.org/docs/reference/api/pandas.read_csv.html
+    reader_kwargs = {}
+
+    # - Define delimiter
+    reader_kwargs["delimiter"] = "\\n"
+
+    # - Avoid first column to become df index !!!
+    reader_kwargs["index_col"] = False
+
+    # Since column names are expected to be passed explicitly, header is set to None
+    reader_kwargs["header"] = None
+
+    # - Number of rows to be skipped at the beginning of the file
+    reader_kwargs["skiprows"] = 1
+
+    # - Define behaviour when encountering bad lines
+    reader_kwargs["on_bad_lines"] = "skip"
+
+    # - Define reader engine
+    #   - C engine is faster
+    #   - Python engine is more feature-complete
+    reader_kwargs["engine"] = "python"
+
+    # - Define on-the-fly decompression of on-disk data
+    #   - Available: gzip, bz2, zip
+    reader_kwargs["compression"] = "infer"
+
+    # - Strings to recognize as NA/NaN and replace with standard NA flags
+    #   - Already included: '#N/A', '#N/A N/A', '#NA', '-1.#IND', '-1.#QNAN',
+    #                       '-NaN', '-nan', '1.#IND', '1.#QNAN', '<NA>', 'N/A',
+    #                       'NA', 'NULL', 'NaN', 'n/a', 'nan', 'null'
+    reader_kwargs["na_values"] = ["na", "", "error"]
+
+    ##------------------------------------------------------------------------.
+    #### Read the data
+    df = read_raw_text_file(
+        filepath=file,
+        column_names=column_names,
+        reader_kwargs=reader_kwargs,
+        logger=logger,
+    )
+
+    ##------------------------------------------------------------------------.
+    #### Adapt the dataframe to adhere to DISDRODB L0 standards
+    # Raise error if empty file
+    if len(df) == 0:
+        raise ValueError(f"{filename} is empty.")
+
+    # Select only rows with expected number of delimiters
+    df = df[df["TO_PARSE"].str.count(" ") == 526]
+
+    # Check there are still valid rows
+    if len(df) == 0:
+        raise ValueError(f"No valid rows in {filename}.")
+
+    # Split by ; delimiter (before raw drop number)
+    df = df["TO_PARSE"].str.split(" ", expand=True, n=82)
+
+    # Assign column names
+    names = [
+        "date",
+        "time",
+        "unknown",
+        "start_identifier",
+        "device_address",
+        "sensor_serial_number",
+        "sensor_date",
+        "sensor_time",
+        "weather_code_synop_4677_5min",
+        "weather_code_synop_4680_5min",
+        "weather_code_metar_4678_5min",
+        "precipitation_rate_5min",
+        "weather_code_synop_4677",
+        "weather_code_synop_4680",
+        "weather_code_metar_4678",
+        "precipitation_rate",
+        "rainfall_rate",
+        "snowfall_rate",
+        "precipitation_accumulated",
+        "mor_visibility",
+        "reflectivity",
+        "quality_index",
+        "max_hail_diameter",
+        "laser_status",
+        "static_signal_status",
+        "laser_temperature_analog_status",
+        "laser_temperature_digital_status",
+        "laser_current_analog_status",
+        "laser_current_digital_status",
+        "sensor_voltage_supply_status",
+        "current_heating_pane_transmitter_head_status",
+        "current_heating_pane_receiver_head_status",
+        "temperature_sensor_status",
+        "current_heating_voltage_supply_status",
+        "current_heating_house_status",
+        "current_heating_heads_status",
+        "current_heating_carriers_status",
+        "control_output_laser_power_status",
+        "reserved_status",
+        "temperature_interior",
+        "laser_temperature",
+        "laser_current_average",
+        "control_voltage",
+        "optical_control_voltage_output",
+        "sensor_voltage_supply",
+        "current_heating_pane_transmitter_head",
+        "current_heating_pane_receiver_head",
+        "temperature_ambient",
+        "current_heating_voltage_supply",
+        "current_heating_house",
+        "current_heating_heads",
+        "current_heating_carriers",
+        "number_particles",
+        "number_particles_internal_data",
+        "number_particles_min_speed",
+        "number_particles_min_speed_internal_data",
+        "number_particles_max_speed",
+        "number_particles_max_speed_internal_data",
+        "number_particles_min_diameter",
+        "number_particles_min_diameter_internal_data",
+        "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",
+        "number_particles_class_9",
+        "number_particles_class_9_internal_data",
+        "TO_BE_FURTHER_PROCESSED",
+    ]
+    df.columns = names
+
+    # Define datetime "time" column
+    df["time"] = df["date"] + " " + df["time"]
+    df["time"] = pd.to_datetime(df["time"], format="%Y-%m-%d %H:%M:%S", errors="coerce")
+
+    # Drop row if start_identifier different than 00
+    df = df[df["start_identifier"].astype(str) == "00"]
+
+    # Extract the last variables remained in raw_drop_number
+    df_parsed = df["TO_BE_FURTHER_PROCESSED"].str.rsplit(" ", n=5, expand=True)
+    df_parsed.columns = [
+        "raw_drop_number",
+        "air_temperature",
+        "relative_humidity",
+        "wind_speed",
+        "wind_direction",
+        "checksum",
+    ]
+
+    # Assign columns to the original dataframe
+    df[df_parsed.columns] = df_parsed
+
+    # Drop rows with invalid raw_drop_number
+    # --> 440 value # 22x20
+    df = df[df["raw_drop_number"].astype(str).str.len() == 1759]
+
+    # Drop columns not agreeing with DISDRODB L0 standards
+    columns_to_drop = [
+        "start_identifier",
+        "device_address",
+        "sensor_serial_number",
+        "sensor_date",
+        "sensor_time",
+        "date",
+        "unknown",
+        "TO_BE_FURTHER_PROCESSED",
+        "air_temperature",
+        "relative_humidity",
+        "wind_speed",
+        "wind_direction",
+        "checksum",
+    ]
+    df = df.drop(columns=columns_to_drop)
+    return df
+
+
+@is_documented_by(reader_generic_docstring)
+def reader(
+    filepath,
+    logger=None,
+):
+    """Reader."""
+    import zipfile
+
+    ##------------------------------------------------------------------------.
+    # filename = os.path.basename(filepath)
+    # return read_txt_file(file=filepath, filename=filename, logger=logger)
+
+    # ---------------------------------------------------------------------.
+    #### Iterate over all files (aka timesteps) in the daily zip archive
+    # - Each file contain a single timestep !
+    # list_df = []
+    # with tempfile.TemporaryDirectory() as temp_dir:
+    #     # Extract all files
+    #     unzip_file_on_terminal(filepath, temp_dir)
+
+    #     # Walk through extracted files
+    #     for root, _, files in os.walk(temp_dir):
+    #         for filename in sorted(files):
+    #             if filename.endswith(".txt"):
+    #                 full_path = os.path.join(root, filename)
+    #                 try:
+    #                     df = read_txt_file(file=full_path, filename=filename, logger=logger)
+    #                     if df is not None:
+    #                         list_df.append(df)
+    #                 except Exception as e:
+    #                     msg = f"An error occurred while reading {filename}: {e}"
+    #                     log_error(logger=logger, msg=msg, verbose=True)
+
+    list_df = []
+    with zipfile.ZipFile(filepath, "r") as zip_ref:
+        filenames = sorted(zip_ref.namelist())
+        for filename in filenames:
+            if filename.endswith(".txt"):
+                # Open file
+                with zip_ref.open(filename) as file:
+                    try:
+                        df = read_txt_file(file=file, filename=filename, logger=logger)
+                        if df is not None:
+                            list_df.append(df)
+                    except Exception as e:
+                        msg = f"An error occurred while reading {filename}. The error is: {e}"
+                        log_error(logger=logger, msg=msg, verbose=True)
+
+    # Check the zip file contains at least some non.empty files
+    if len(list_df) == 0:
+        raise ValueError(f"{filepath} contains only empty files!")
+
+    # Concatenate all dataframes into a single one
+    df = pd.concat(list_df)
+
+    # ---------------------------------------------------------------------.
+    return df