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

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

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: direl-ts-tool-kit
-Version: 0.2.0
+Version: 0.3.0
 Summary: A toolbox for time series analysis and visualization.
 Home-page: https://gitlab.com/direl/direl_tool_kit
-Author: Tu Nombre Aquí
+Author: Diego Restrepo-Leal
 Author-email: diegorestrepoleal@gmail.com
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
@@ -17,6 +17,7 @@ License-File: LICENCE
 Requires-Dist: pandas>=1.0.0
 Requires-Dist: numpy>=1.18.0
 Requires-Dist: matplotlib>=3.0.0
+Requires-Dist: openpyxl
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier

{direl_ts_tool_kit-0.2.0 → direl_ts_tool_kit-0.3.0}/direl_ts_tool_kit/__init__.py

@@ -1,2 +1,3 @@
 from .plot.plot_style import *
 from .plot.plot_ts import *
+from .utilities.data_prep import *

{direl_ts_tool_kit-0.2.0 → 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
@@ -41,10 +41,20 @@ def plot_time_series(
     -----
     Major grid lines are displayed with a dashed line ('--'), and minor grid
     lines are displayed with a dotted line (':') for detailed temporal analysis.
+
+        Available Colors
+    ----------------
+    The 'color' parameter accepts any key from the 'paper_colors' dictionary.
+
+    Lines: 'BLUE_LINES', 'ORANGE_LINES', 'GREEN_LINES', 'RED_LINES',
+           'GRAY_LINES', 'PURPLE_LINES', 'MAROON_LINES', 'GOLD_LINES'.
+
+    Bars:  'BLUE_BARS', 'ORANGE_BARS', 'GREEN_BARS', 'RED_BARS',
+           'GRAY_BARS', 'PURPLE_BARS', 'MAROON_BARS', 'GOLD_BARS'.
     """
 
     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(
@@ -68,7 +78,7 @@ def plot_time_series(
                     for i, j in enumerate(variable.split())
                 ]
             )
-            if method
+            if auto_format_label
             else variable
         )
 
@@ -97,3 +107,43 @@ def plot_time_series(
     ax.grid(which="major", alpha=0.8, linestyle="--")
 
     return fig
+
+
+def save_figure(
+    fig,
+    file_name,
+    variable_name="",
+    path="./",
+):
+    """
+    Saves a Matplotlib figure in three common high-quality formats (PNG, PDF, SVG).
+
+    The function creates a consistent file name structure:
+    {path}/{file_name}_{variable_name}.{extension}.
+
+    Parameters
+    ----------
+    fig : matplotlib.figure.Figure
+        The Matplotlib figure object to be saved.
+    file_name : str
+        The primary name for the file (e.g., 'timeseries_report').
+    variable_name : str, optional
+        An optional secondary name, often the name of the plotted variable,
+        to be appended to the file name. Defaults to "".
+    path : str, optional
+        The directory path where the figure files will be saved.
+        Defaults to the current directory ('./').
+
+    Returns
+    -------
+    None
+    """
+
+    if variable_name:
+        base_name = f"{path}/{file_name}_{variable_name}"
+    else:
+        base_name = f"{path}/{file_name}"
+
+    fig.savefig(f"{base_name}.png")
+    fig.savefig(f"{base_name}.pdf")
+    fig.savefig(f"{base_name}.svg")

direl_ts_tool_kit-0.3.0/direl_ts_tool_kit/utilities/__init__.py

@@ -0,0 +1 @@
+from .data_prep import *

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.0 → direl_ts_tool_kit-0.3.0}/direl_ts_tool_kit.egg-info/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: direl-ts-tool-kit
-Version: 0.2.0
+Version: 0.3.0
 Summary: A toolbox for time series analysis and visualization.
 Home-page: https://gitlab.com/direl/direl_tool_kit
-Author: Tu Nombre Aquí
+Author: Diego Restrepo-Leal
 Author-email: diegorestrepoleal@gmail.com
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
@@ -17,6 +17,7 @@ License-File: LICENCE
 Requires-Dist: pandas>=1.0.0
 Requires-Dist: numpy>=1.18.0
 Requires-Dist: matplotlib>=3.0.0
+Requires-Dist: openpyxl
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier

{direl_ts_tool_kit-0.2.0 → direl_ts_tool_kit-0.3.0}/direl_ts_tool_kit.egg-info/SOURCES.txt

@@ -9,4 +9,6 @@ direl_ts_tool_kit.egg-info/requires.txt
 direl_ts_tool_kit.egg-info/top_level.txt
 direl_ts_tool_kit/plot/__init__.py
 direl_ts_tool_kit/plot/plot_style.py
-direl_ts_tool_kit/plot/plot_ts.py
+direl_ts_tool_kit/plot/plot_ts.py
+direl_ts_tool_kit/utilities/__init__.py
+direl_ts_tool_kit/utilities/data_prep.py

{direl_ts_tool_kit-0.2.0 → direl_ts_tool_kit-0.3.0}/direl_ts_tool_kit.egg-info/requires.txt

@@ -1,3 +1,4 @@
 pandas>=1.0.0
 numpy>=1.18.0
 matplotlib>=3.0.0
+openpyxl

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

@@ -2,11 +2,11 @@ from setuptools import setup, find_packages
 
 setup(
     name="direl-ts-tool-kit",
-    version="0.2.0",
+    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",
-    author="Tu Nombre Aquí",
+    author="Diego Restrepo-Leal",
     author_email="diegorestrepoleal@gmail.com",
     url="https://gitlab.com/direl/direl_tool_kit",
     packages=find_packages(),
@@ -14,6 +14,7 @@ setup(
         "pandas>=1.0.0",
         "numpy>=1.18.0",
         "matplotlib>=3.0.0",
+        "openpyxl",
     ],
     classifiers=[
         "Programming Language :: Python :: 3",