direl-ts-tool-kit 0.2.2__py3-none-any.whl → 0.3.0__py3-none-any.whl

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/utilities/data_prep.py

@@ -21,9 +21,6 @@ def parse_datetime_index(df_raw, date_column="date"):
     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])
@@ -32,4 +29,90 @@ def parse_datetime_index(df_raw, date_column="date"):
     df_ts.drop(columns=[date_column], inplace=True)
     df_ts.set_index(date_parsed, inplace=True)
 
-    return df_ts, original_dates
+    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.dist-info → direl_ts_tool_kit-0.3.0.dist-info}/METADATA

@@ -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.3.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+direl_ts_tool_kit/__init__.py,sha256=W99Wd3BeEFKOxT51TApURElbDJvqIjD8u_-qDoCYSJ0,94
+direl_ts_tool_kit/plot/__init__.py,sha256=CMwyv-kiE74nwr3MJPL7gWIJmcfZ8UQCRu7mBGGQ4rI,49
+direl_ts_tool_kit/plot/plot_style.py,sha256=vhzcDa3LzgkHuy-GnliofGZ8TDntkm3_1C5kgl2Gx3E,1010
+direl_ts_tool_kit/plot/plot_ts.py,sha256=UUeNk-4rk7rNhiXtVaHSBXw-P34ssh8wUJ2o3Jbj5Gk,4855
+direl_ts_tool_kit/utilities/__init__.py,sha256=jMtxYZUtwlhgI99sxe_8MMzsDnxtbTP7Ivh9tUOeIwQ,25
+direl_ts_tool_kit/utilities/data_prep.py,sha256=807c21Rk5Q0To6fDfoWgGghU9KQMLXelTOx5OE-YgIw,4375
+direl_ts_tool_kit-0.3.0.dist-info/licenses/LICENCE,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+direl_ts_tool_kit-0.3.0.dist-info/METADATA,sha256=6yKyemO_u8JoRX8ku3rE_CgZ244Jg8bm_KxkrLeuV2U,950
+direl_ts_tool_kit-0.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+direl_ts_tool_kit-0.3.0.dist-info/top_level.txt,sha256=vMCRudnGnsdRg_6fUftnG8PF2Y1m0bjBDMf3pCAp6bc,18
+direl_ts_tool_kit-0.3.0.dist-info/RECORD,,

direl_ts_tool_kit-0.2.2.dist-info/RECORD

@@ -1,11 +0,0 @@
-direl_ts_tool_kit/__init__.py,sha256=W99Wd3BeEFKOxT51TApURElbDJvqIjD8u_-qDoCYSJ0,94
-direl_ts_tool_kit/plot/__init__.py,sha256=CMwyv-kiE74nwr3MJPL7gWIJmcfZ8UQCRu7mBGGQ4rI,49
-direl_ts_tool_kit/plot/plot_style.py,sha256=vhzcDa3LzgkHuy-GnliofGZ8TDntkm3_1C5kgl2Gx3E,1010
-direl_ts_tool_kit/plot/plot_ts.py,sha256=uYkPWz-8aWIjZGW22n5uH19CYHv-bLGrZaHPW9f3-3I,4814
-direl_ts_tool_kit/utilities/__init__.py,sha256=jMtxYZUtwlhgI99sxe_8MMzsDnxtbTP7Ivh9tUOeIwQ,25
-direl_ts_tool_kit/utilities/data_prep.py,sha256=KqVICzfjvsQqbekYiL21MLdno6spjwzF2PXCv6D-kNc,1225
-direl_ts_tool_kit-0.2.2.dist-info/licenses/LICENCE,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-direl_ts_tool_kit-0.2.2.dist-info/METADATA,sha256=SwDvWNWSkGCfMnU6UlieG9lurQsvUZoeTxmFZjia-VA,950
-direl_ts_tool_kit-0.2.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-direl_ts_tool_kit-0.2.2.dist-info/top_level.txt,sha256=vMCRudnGnsdRg_6fUftnG8PF2Y1m0bjBDMf3pCAp6bc,18
-direl_ts_tool_kit-0.2.2.dist-info/RECORD,,