direl-ts-tool-kit 0.2.2__tar.gz → 0.3.0__tar.gz

{direl_ts_tool_kit-0.2.2 → direl_ts_tool_kit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: direl-ts-tool-kit
-Version: 0.2.2
+Version: 0.3.0
 Summary: A toolbox for time series analysis and visualization.
 Home-page: https://gitlab.com/direl/direl_tool_kit
 Author: Diego Restrepo-Leal

{direl_ts_tool_kit-0.2.2 → direl_ts_tool_kit-0.3.0}/direl_ts_tool_kit/plot/plot_ts.py

@@ -2,7 +2,7 @@ from .plot_style import *
 
 
 def plot_time_series(
-    df1, variable, units="", color="BLUE_LINES", time_unit="Year", rot=90, method=True
+    df_ts, variable, units="", color="BLUE_LINES", time_unit="Year", rot=90, auto_format_label=True
 ):
     """
     Plots a time series with custom styling and dual-level grid visibility.
@@ -13,7 +13,7 @@ def plot_time_series(
 
     Parameters
     ----------
-    df1 : pd.DataFrame
+    df_ts : pd.DataFrame
         The DataFrame containing the time series data. Must have a DatetimeIndex.
     variable : str
         The name of the column to plot. The label is automatically formatted
@@ -29,7 +29,7 @@ def plot_time_series(
         Options include 'Year', 'Month', 'Weekday', or 'Day'. Defaults to "Year".
     rot : int, optional
         Rotation angle (in degrees) for the x-axis tick labels. Defaults to 90.
-    method : bool, optional
+    auto_format_label : bool, optional
         Used internally for label formatting logic. Defaults to True.
 
     Returns
@@ -54,7 +54,7 @@ def plot_time_series(
     """
 
     fig, ax = plt.subplots()
-    ax.plot(df1.index, df1[variable], linewidth=3, color=paper_colors[color])
+    ax.plot(df_ts.index, df_ts[variable], linewidth=3, color=paper_colors[color])
 
     if "-" in variable:
         variable = "-".join(
@@ -78,7 +78,7 @@ def plot_time_series(
                     for i, j in enumerate(variable.split())
                 ]
             )
-            if method
+            if auto_format_label
             else variable
         )
 

direl_ts_tool_kit-0.3.0/direl_ts_tool_kit/utilities/data_prep.py

@@ -0,0 +1,118 @@
+import pandas as pd
+
+
+def parse_datetime_index(df_raw, date_column="date"):
+    """
+    Parses a specified column into datetime objects and sets it as the DataFrame index.
+
+    This function is crucial for preparing raw data (df_raw) for time series analysis
+    by ensuring the DataFrame is indexed by the correct datetime type.
+
+    Parameters
+    ----------
+    df_raw : pd.DataFrame
+        The raw DataFrame containing the data, including the column with date strings.
+    date_column : str, optional
+        The name of the column in 'df_raw' that contains the date/time information.
+        Defaults to "date".
+
+    Returns
+    -------
+    df_ts : pd.DataFrame
+        A copy of the original DataFrame with the specified date column removed
+        and set as the DatetimeIndex. Ready for time series plotting.
+    """
+
+    date_parsed = pd.to_datetime(df_raw[date_column])
+    df_ts = df_raw.copy()
+    original_dates = df_raw[date_column]
+    df_ts.drop(columns=[date_column], inplace=True)
+    df_ts.set_index(date_parsed, inplace=True)
+
+    return df_ts
+
+
+def generate_dates(df_ts, freq="MS"):
+    """
+    Generates a continuous DatetimeIndex covering the time span of the input DataFrame.
+
+    The function determines the start and end dates from the existing DataFrame index
+    and creates a new, regular date sequence based on the specified frequency.
+
+    Parameters
+    ----------
+    df_ts : pd.DataFrame
+        The time series DataFrame whose index determines the start and end of the
+        new date range.
+    freq : str, optional
+        The frequency of the generated dates (e.g., 'D' for daily, 'MS' for Month Start).
+        Defaults to "MS" (Month Start).
+
+    Returns
+    -------
+    pd.DatetimeIndex
+        A new DatetimeIndex spanning from the first index entry to the last index entry
+        of 'df_ts', using the specified frequency.
+
+    Notes
+    -----
+    The function relies on the index of 'df_ts' to find the boundaries. It explicitly
+    sorts the index first to ensure the earliest and latest dates are correctly identified,
+    regardless of the current DataFrame order.
+    """
+    df_ts.sort_index(inplace=True)
+    start_date = df_ts.index[0]
+    end_date = df_ts.index[-1]
+
+    dates = pd.date_range(start=start_date, end=end_date, freq=freq)
+
+    return dates
+
+
+def reindex_and_aggregate(df_ts, column_name, freq="MS"):
+    """
+    Re-indexes a time series DataFrame to a regular frequency, aggregates values,
+    and introduces NaN for missing time steps.
+
+    This function first identifies the time range from the original (potentially irregular)
+    index, aggregates data if necessary (e.g., if multiple entries exist per time step),
+    and then merges the data onto a complete date range, effectively filling gaps
+    with NaN values.
+
+    Parameters
+    ----------
+    df_ts : pd.DataFrame
+        The input DataFrame. It is assumed that the index contains the date information
+        (though the function currently resets and uses a 'date' column name internally
+        due to the line `groupby(["date"])`).
+    column_name : str
+        The name of the column containing the values to be aggregated and re-indexed.
+
+    Returns
+    -------
+    pd.DataFrame
+        A new DataFrame with a complete, regular DatetimeIndex (set by the
+        frequency used in generate_dates, typically 'MS'), and the aggregated
+        values, where missing time steps are represented by NaN.
+
+    Notes
+    -----
+    1. **Dependency:** This function relies on the external function `generate_dates()`
+       to create the target date sequence.
+    2. **Aggregation:** The use of `.groupby(["date"]).sum()` implies that if
+       multiple entries share the same date, their values will be summed.
+    3. **Index Handling:** For the merge operation to work, the original index
+       is temporarily converted to a column named 'date' (via `reset_index`
+       implicitly after the `groupby`).
+    """
+
+    date_aux = generate_dates(df_ts, freq="MS")
+    df_date = pd.DataFrame({"date_aux": date_aux})
+    df_ts = df_ts.groupby(["date"]).sum().reset_index()
+
+    result = pd.merge(df_ts, df_date, left_on="date", right_on="date_aux", how="outer")
+    df_ts_new = result[["date_aux", column_name]]
+    df_ts_new.set_index(df_ts_new["date_aux"], inplace=True)
+    df_ts_new.notnull().apply(pd.Series.value_counts)
+
+    return df_ts_new

{direl_ts_tool_kit-0.2.2 → direl_ts_tool_kit-0.3.0}/direl_ts_tool_kit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: direl-ts-tool-kit
-Version: 0.2.2
+Version: 0.3.0
 Summary: A toolbox for time series analysis and visualization.
 Home-page: https://gitlab.com/direl/direl_tool_kit
 Author: Diego Restrepo-Leal

{direl_ts_tool_kit-0.2.2 → direl_ts_tool_kit-0.3.0}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name="direl-ts-tool-kit",
-    version="0.2.2",
+    version="0.3.0",
     description="A toolbox for time series analysis and visualization.",
     long_description=open("README.md", encoding="utf-8").read(),
     long_description_content_type="text/markdown",

direl_ts_tool_kit-0.2.2/direl_ts_tool_kit/utilities/data_prep.py

@@ -1,35 +0,0 @@
-import pandas as pd
-
-
-def parse_datetime_index(df_raw, date_column="date"):
-    """
-    Parses a specified column into datetime objects and sets it as the DataFrame index.
-
-    This function is crucial for preparing raw data (df_raw) for time series analysis
-    by ensuring the DataFrame is indexed by the correct datetime type.
-
-    Parameters
-    ----------
-    df_raw : pd.DataFrame
-        The raw DataFrame containing the data, including the column with date strings.
-    date_column : str, optional
-        The name of the column in 'df_raw' that contains the date/time information.
-        Defaults to "date".
-
-    Returns
-    -------
-    df_ts : pd.DataFrame
-        A copy of the original DataFrame with the specified date column removed
-        and set as the DatetimeIndex. Ready for time series plotting.
-    original_dates : pd.Series
-        The original Series containing the date strings/objects, which was used
-        to create the new index.
-    """
-
-    date_parsed = pd.to_datetime(df_raw[date_column])
-    df_ts = df_raw.copy()
-    original_dates = df_raw[date_column]
-    df_ts.drop(columns=[date_column], inplace=True)
-    df_ts.set_index(date_parsed, inplace=True)
-
-    return df_ts, original_dates