direl-ts-tool-kit 0.9.0__py3-none-any.whl → 0.10.0__py3-none-any.whl

direl_ts_tool_kit/plot/plot_ts.py

@@ -123,6 +123,137 @@ def plot_time_series(
     return fig
 
 
+def plot_forecast(
+    df_hist,
+    df_ts,
+    variable,
+    units="",
+    color_hist="BLUE_LINES",
+    color_forecast="RED_LINES",
+    time_unit="Year",
+    rot=90,
+    auto_format_label=True,
+):
+    """
+    Plots historical data alongside a forecast with a shaded confidence interval.
+
+    This function combines a historical time series with a forecast period,
+    automatically formatting axes, labels, and applying professional styling.
+    It expects the forecast DataFrame to include lower and upper bound columns
+    named '{variable}_lower' and '{variable}_upper'.
+
+    Parameters
+    ----------
+    df_hist : pd.DataFrame
+        The DataFrame containing historical data. Must have a DatetimeIndex.
+    df_ts : pd.DataFrame
+        The DataFrame containing the forecast data and confidence intervals.
+        Must have a DatetimeIndex.
+    variable : str
+        The name of the column to plot in both DataFrames.
+    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 for the forecast 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: 'Year', 'Month', 'Weekday', 'Day' or 'Hour'. Defaults to "Year".
+    rot : int, optional
+        Rotation angle for the x-axis tick labels. Defaults to 90.
+    auto_format_label : bool, optional
+        If True, automatically formats the Y-axis label into Title Case.
+        Defaults to True.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+        The generated matplotlib figure object.
+
+    Notes
+    -----
+    The confidence interval is shaded using 'GRAY_BARS' from the paper_colors
+    palette with a transparency of 0.3.
+    """
+
+    fig, ax = plt.subplots()
+
+    ax.plot(
+        df_hist.index,
+        df_hist[variable],
+        linewidth=2,
+        color=paper_colors[color_hist],
+        label="Historical",
+    )
+
+    ax.plot(
+        df_ts.index,
+        df_ts[variable],
+        linewidth=3,
+        color=paper_colors[color_forecast],
+        label="Forecast",
+    )
+
+    ax.fill_between(
+        df_ts.index,
+        df_ts[variable + "_lower"],
+        df_ts[variable + "_upper"],
+        color=paper_colors["GRAY_BARS"],
+        alpha=0.3,
+        edgecolor="none",
+        label="Confidence Interval",
+    )
+
+    temp_variable = variable
+    if auto_format_label:
+        if "-" in temp_variable:
+            temp_variable = "-".join(
+                [
+                    j.title() if i == 0 else j.lower()
+                    for i, j in enumerate(temp_variable.split("-"))
+                ]
+            )
+        elif "_" in temp_variable:
+            temp_variable = " ".join(
+                [
+                    j.title() if i == 0 else j.lower()
+                    for i, j in enumerate(temp_variable.split("_"))
+                ]
+            )
+        else:
+            temp_variable = " ".join(
+                [
+                    j.title() if i == 0 else j.lower()
+                    for i, j in enumerate(temp_variable.split())
+                ]
+            )
+
+    ax.set(xlabel=f"{time_unit}", ylabel=f"{temp_variable} {units}")
+    ax.ticklabel_format(style="sci", axis="y", scilimits=(0, 0))
+
+    locators = {
+        "Year": (mdates.YearLocator(), mdates.MonthLocator()),
+        "Month": (mdates.MonthLocator(), mdates.WeekdayLocator()),
+        "Weekday": (mdates.WeekdayLocator(), mdates.DayLocator()),
+        "Day": (mdates.DayLocator(), mdates.HourLocator()),
+        "Hour": (mdates.HourLocator(), mdates.MinuteLocator()),
+    }
+
+    if time_unit in locators:
+        major, minor = locators[time_unit]
+        ax.xaxis.set_major_locator(major)
+        ax.xaxis.set_minor_locator(minor)
+
+    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="--")
+    ax.legend(loc="center left", bbox_to_anchor=(1, 0.5))
+
+    return fig
+
+
 def plot_interpolation_analysis(
     df_original,
     variable,

{direl_ts_tool_kit-0.9.0.dist-info → direl_ts_tool_kit-0.10.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: direl-ts-tool-kit
-Version: 0.9.0
+Version: 0.10.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.10.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=5YxoLXlYvzleTnBEGPwCmHQIJ0S96KPJspq_n-qMvpw,1069
+direl_ts_tool_kit/plot/plot_ts.py,sha256=OuHgFlNyjW6BEleIKbv2LIt5MDlzfu5kM8gee4z_24U,23571
+direl_ts_tool_kit/utilities/__init__.py,sha256=jMtxYZUtwlhgI99sxe_8MMzsDnxtbTP7Ivh9tUOeIwQ,25
+direl_ts_tool_kit/utilities/data_prep.py,sha256=k3eOwQEEd5mxy2DtT_Gdo7BhkzEmSQqvMJ89y8mH5CQ,6024
+direl_ts_tool_kit-0.10.0.dist-info/licenses/LICENCE,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+direl_ts_tool_kit-0.10.0.dist-info/METADATA,sha256=dpNkbfrs3SKr-GKnR7Tur0Rk0cZqvCOKESQdQDoJpn8,5774
+direl_ts_tool_kit-0.10.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+direl_ts_tool_kit-0.10.0.dist-info/top_level.txt,sha256=vMCRudnGnsdRg_6fUftnG8PF2Y1m0bjBDMf3pCAp6bc,18
+direl_ts_tool_kit-0.10.0.dist-info/RECORD,,

direl_ts_tool_kit-0.9.0.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=5YxoLXlYvzleTnBEGPwCmHQIJ0S96KPJspq_n-qMvpw,1069
-direl_ts_tool_kit/plot/plot_ts.py,sha256=jAb_EruXvj0FIhvdm4BSqnGXY8dBAoPPusLE15owrwQ,19443
-direl_ts_tool_kit/utilities/__init__.py,sha256=jMtxYZUtwlhgI99sxe_8MMzsDnxtbTP7Ivh9tUOeIwQ,25
-direl_ts_tool_kit/utilities/data_prep.py,sha256=k3eOwQEEd5mxy2DtT_Gdo7BhkzEmSQqvMJ89y8mH5CQ,6024
-direl_ts_tool_kit-0.9.0.dist-info/licenses/LICENCE,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-direl_ts_tool_kit-0.9.0.dist-info/METADATA,sha256=yGjaOHA9e78QX2x1YbEnDWeqMl-Cf2_Z9z7czZaLt20,5773
-direl_ts_tool_kit-0.9.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-direl_ts_tool_kit-0.9.0.dist-info/top_level.txt,sha256=vMCRudnGnsdRg_6fUftnG8PF2Y1m0bjBDMf3pCAp6bc,18
-direl_ts_tool_kit-0.9.0.dist-info/RECORD,,