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

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

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: direl-ts-tool-kit
-Version: 0.1.0
+Version: 0.2.2
 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.1.0 → direl_ts_tool_kit-0.2.2}/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.2/direl_ts_tool_kit/plot/__init__.py

@@ -0,0 +1,2 @@
+from .plot_style import *
+from .plot_ts import *

direl_ts_tool_kit-0.2.2/direl_ts_tool_kit/plot/plot_style.py

@@ -0,0 +1,48 @@
+import matplotlib.pyplot as plt
+import matplotlib.dates as mdates
+
+plt.style.use("fast")
+
+plt.rc("figure", autolayout=True, figsize=(12, 5))
+
+plt.rc(
+    "axes",
+    labelweight="bold",
+    labelsize=15,
+    titleweight="bold",
+    titlesize=14,
+    titlepad=10,
+    facecolor="white",
+)
+
+plt.rc("xtick", labelsize=15)
+plt.rc("ytick", labelsize=15)
+plt.rc("legend", fontsize=10)
+
+plot_params = {
+    "color": "0.75",
+    "style": ".-",
+    "markeredgecolor": "0.25",
+    "markerfacecolor": "0.25",
+    "legend": False,
+}
+
+
+paper_colors = {
+    "BLUE_LINES": "#396AB1",
+    "ORANGE_LINES": "#DA7C30",
+    "GREEN_LINES": "#3E9651",
+    "RED_LINES": "#CC2529",
+    "GRAY_LINES": "#535154",
+    "PURPLE_LINES": "#6B4C9A",
+    "MAROON_LINES": "#922428",
+    "GOLD_LINES": "#948B3D",
+    "BLUE_BARS": "#7293CB",
+    "ORANGE_BARS": "#E1974C",
+    "GREEN_BARS": "#84BA5B",
+    "RED_BARS": "#D35E60",
+    "GRAY_BARS": "#808585",
+    "PURPLE_BARS": "#90679D",
+    "MAROON_BARS": "#AB6857",
+    "GOLD_BARS": "#CCC210",
+}

direl_ts_tool_kit-0.2.2/direl_ts_tool_kit/plot/plot_ts.py

@@ -0,0 +1,149 @@
+from .plot_style import *
+
+
+def plot_time_series(
+    df1, variable, units="", color="BLUE_LINES", time_unit="Year", rot=90, method=True
+):
+    """
+    Plots a time series with custom styling and dual-level grid visibility.
+
+    This function automatically sets major and minor time-based locators
+    on the x-axis based on the specified time unit, and formats the y-axis
+    to use scientific notation.
+
+    Parameters
+    ----------
+    df1 : 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
+        (e.g., 'total_sales' becomes 'Total Sales').
+    units : str, optional
+        Units to display next to the variable name on the y-axis (e.g., 'USD').
+        Defaults to "".
+    color : str, optional
+        Key corresponding to the line color in the global 'paper_colors' dictionary.
+        Defaults to "BLUE_LINES".
+    time_unit : str, optional
+        The time granularity of the data to define x-axis tick locators.
+        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
+        Used internally for label formatting logic. Defaults to True.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+        The generated matplotlib figure object.
+
+    Notes
+    -----
+    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])
+
+    if "-" in variable:
+        variable = "-".join(
+            [
+                j.title() if i == 0 else j.lower()
+                for i, j in enumerate(variable.split("-"))
+            ]
+        )
+    elif "_" in variable:
+        variable = " ".join(
+            [
+                j.title() if i == 0 else j.lower()
+                for i, j in enumerate(variable.split("_"))
+            ]
+        )
+    else:
+        variable = (
+            " ".join(
+                [
+                    j.title() if i == 0 else j.lower()
+                    for i, j in enumerate(variable.split())
+                ]
+            )
+            if method
+            else variable
+        )
+
+    ax.set(xlabel=f"{time_unit}", ylabel=f"{variable} {units}")
+    ax.ticklabel_format(style="sci", axis="y", scilimits=(0, 0))
+
+    if time_unit == "Year":
+        ax.xaxis.set_major_locator(mdates.YearLocator())
+        ax.xaxis.set_minor_locator(mdates.MonthLocator())
+
+    if time_unit == "Month":
+        ax.xaxis.set_major_locator(mdates.MonthLocator())
+        ax.xaxis.set_minor_locator(mdates.WeekdayLocator())
+
+    if time_unit == "Weekday":
+        ax.xaxis.set_major_locator(mdates.WeekdayLocator())
+        ax.xaxis.set_minor_locator(mdates.DayLocator())
+
+    if time_unit == "Day":
+        ax.xaxis.set_major_locator(mdates.DayLocator())
+        ax.xaxis.set_minor_locator(mdates.HourLocator())
+
+    ax.tick_params(axis="x", rotation=rot)
+    ax.grid(which="both")
+    ax.grid(which="minor", alpha=0.6, linestyle=":")
+    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.2.2/direl_ts_tool_kit/utilities/__init__.py

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

direl_ts_tool_kit-0.2.2/direl_ts_tool_kit/utilities/data_prep.py

@@ -0,0 +1,35 @@
+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

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

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: direl-ts-tool-kit
-Version: 0.1.0
+Version: 0.2.2
 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.2/direl_ts_tool_kit.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENCE
+README.md
+setup.py
+direl_ts_tool_kit/__init__.py
+direl_ts_tool_kit.egg-info/PKG-INFO
+direl_ts_tool_kit.egg-info/SOURCES.txt
+direl_ts_tool_kit.egg-info/dependency_links.txt
+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/utilities/__init__.py
+direl_ts_tool_kit/utilities/data_prep.py

{direl_ts_tool_kit-0.1.0 → direl_ts_tool_kit-0.2.2}/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.1.0 → direl_ts_tool_kit-0.2.2}/setup.py

@@ -2,11 +2,11 @@ from setuptools import setup, find_packages
 
 setup(
     name="direl-ts-tool-kit",
-    version="0.1.0",
+    version="0.2.2",
     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",

direl_ts_tool_kit-0.1.0/direl_ts_tool_kit.egg-info/SOURCES.txt

@@ -1,9 +0,0 @@
-LICENCE
-README.md
-setup.py
-direl_ts_tool_kit/__init__.py
-direl_ts_tool_kit.egg-info/PKG-INFO
-direl_ts_tool_kit.egg-info/SOURCES.txt
-direl_ts_tool_kit.egg-info/dependency_links.txt
-direl_ts_tool_kit.egg-info/requires.txt
-direl_ts_tool_kit.egg-info/top_level.txt