direl-ts-tool-kit 0.2.2__py3-none-any.whl → 0.3.2__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
         )
 
@@ -100,6 +100,10 @@ def plot_time_series(
     if time_unit == "Day":
         ax.xaxis.set_major_locator(mdates.DayLocator())
         ax.xaxis.set_minor_locator(mdates.HourLocator())
+        
+    if time_unit == "Hour":
+        ax.xaxis.set_major_locator(mdates.HourLocator())
+        ax.xaxis.set_minor_locator(mdates.MinuteLocator())
 
     ax.tick_params(axis="x", rotation=rot)
     ax.grid(which="both")

direl_ts_tool_kit/utilities/data_prep.py

@@ -1,12 +1,12 @@
 import pandas as pd
 
 
-def parse_datetime_index(df_raw, date_column="date"):
+def parse_datetime_index(df_raw, date_column="date", format=None):
     """
     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.
+    This function prepares raw data for time series analysis by ensuring the 
+    DataFrame is indexed by the correct datetime type.
 
     Parameters
     ----------
@@ -15,21 +15,111 @@ def parse_datetime_index(df_raw, date_column="date"):
     date_column : str, optional
         The name of the column in 'df_raw' that contains the date/time information.
         Defaults to "date".
+    format : str, optional
+        The explicit format string (e.g., '%Y%m%d', '%Y-%m-%d %H:%M:%S') 
+        to parse the dates, passed to `pd.to_datetime`. If None (default), 
+        Pandas attempts to infer the format automatically.
 
     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.
+        A copy of the original DataFrame with the specified date column removed 
+        and set as the DatetimeIndex. The returned DataFrame is ready for 
+        time series operations.
     """
+    if not format:
+        date_parsed = pd.to_datetime(df_raw[date_column])
+    else:
+        date_parsed = pd.to_datetime(df_raw[date_column], format=format)
 
-    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
+    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.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: direl-ts-tool-kit
-Version: 0.2.2
+Version: 0.3.2
 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.2.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=OPmdaXGUv_oNaXQ4epiPX1fKTtxyaWuoGfHPa5if96U,5008
+direl_ts_tool_kit/utilities/__init__.py,sha256=jMtxYZUtwlhgI99sxe_8MMzsDnxtbTP7Ivh9tUOeIwQ,25
+direl_ts_tool_kit/utilities/data_prep.py,sha256=IZJShsSGWxv6Q-rM7m69kGADNUhCzs-KfhphgqD29Ok,4703
+direl_ts_tool_kit-0.3.2.dist-info/licenses/LICENCE,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+direl_ts_tool_kit-0.3.2.dist-info/METADATA,sha256=n0O3607YFBQYXu6eu27dutF5o_T2xC11JyUucb8Oafs,950
+direl_ts_tool_kit-0.3.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+direl_ts_tool_kit-0.3.2.dist-info/top_level.txt,sha256=vMCRudnGnsdRg_6fUftnG8PF2Y1m0bjBDMf3pCAp6bc,18
+direl_ts_tool_kit-0.3.2.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,,