direl-ts-tool-kit 0.5.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

direl_ts_tool_kit/plot/plot_style.py

@@ -1,6 +1,8 @@
 import seaborn as sns
 import matplotlib.pyplot as plt
 import matplotlib.dates as mdates
+from matplotlib.lines import Line2D
+
 
 plt.style.use("fast")
 

direl_ts_tool_kit/plot/plot_ts.py

@@ -1,3 +1,4 @@
+import numpy as np
 import pandas as pd
 from .plot_style import *
 from scipy.stats import pearsonr
@@ -121,6 +122,159 @@ def plot_time_series(
     return fig
 
 
+def plot_interpolation_analysis(
+    df_original,
+    variable,
+    units="",
+    method="polynomial",
+    order=2,
+    imputation_se=None,
+    time_unit="Year",
+    rot=90,
+):
+    """
+    Performs interpolation on missing data (NaNs) in a specified column and
+    plots the result, highlighting the imputed points with confidence intervals
+    if the Imputation Standard Error (SE) is provided.
+
+    Parameters
+    ----------
+    df_original : pd.DataFrame
+        The DataFrame containing the original time series data.
+    variable : str
+        The name of the column to interpolate and plot (e.g., 'LPUE').
+    units : str, optional
+        Units to display next to the variable name on the y-axis. Defaults to "".
+    method : str, optional
+        The interpolation method (e.g., 'linear', 'polynomial', 'spline').
+        Defaults to 'polynomial'.
+    order : int, optional
+        The order of the interpolation (required for 'polynomial' or 'spline').
+        Defaults to 2.
+    imputation_se : pd.Series, float, or None, optional
+        The Standard Error (SE) of the imputation. This must be a single value
+        or a Series aligned with the DataFrame's index. If None, confidence
+        intervals will NOT be plotted. Defaults to None.
+    time_unit : str, optional
+        The time granularity for x-axis tick locators. Defaults to "Year".
+    rot : int, optional
+        Rotation angle (in degrees) for the x-axis tick labels. Defaults to 90.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+        The generated Matplotlib figure object with the plot.
+    """
+
+    imputed_mask = df_original[variable].isnull()
+    df_interpolated = df_original.copy()
+    df_interpolated[variable] = df_interpolated[variable].interpolate(
+        method=method, order=order
+    )
+
+    color1 = paper_colors["RED_LINES"]
+    color2 = paper_colors["GREEN_LINES"]
+
+    col = np.where(imputed_mask, color1, color2)
+
+    fig, ax = plt.subplots()
+
+    if imputation_se is not None:
+        df_imputed_only = df_interpolated.copy()
+        df_imputed_only.loc[~imputed_mask, variable] = np.nan
+
+        Z_80 = 1.282
+        Z_95 = 1.96
+
+        error_80 = Z_80 * imputation_se
+        error_95 = Z_95 * imputation_se
+
+        ax.fill_between(
+            df_imputed_only.index,
+            df_imputed_only[variable] - error_95,
+            df_imputed_only[variable] + error_95,
+            color=paper_colors["GRAY_BARS"],
+            alpha=0.2,
+            edgecolor="none",
+            label="95% confidence interval",
+        )
+
+        ax.fill_between(
+            df_imputed_only.index,
+            df_imputed_only[variable] - error_80,
+            df_imputed_only[variable] + error_80,
+            color=paper_colors["GRAY_BARS"],
+            alpha=0.4,
+            edgecolor="none",
+            label="80% confidence interval",
+        )
+
+    ax.plot(
+        df_interpolated[variable],
+        linestyle="-.",
+        linewidth=1,
+        color=paper_colors["BLUE_LINES"],
+    )
+
+    ax.scatter(
+        df_interpolated.index,
+        df_interpolated[variable],
+        color=col,
+        s=10,
+        linewidth=4,
+    )
+
+    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())
+
+    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")
+    ax.grid(which="minor", alpha=0.6, linestyle=":")
+    ax.grid(which="major", alpha=0.8, linestyle="--")
+
+    legend_elements = [
+        Line2D(
+            [0],
+            [0],
+            marker="o",
+            color=color2,
+            label="Current data",
+            linestyle="none",
+        ),
+        Line2D(
+            [0],
+            [0],
+            marker="o",
+            color=color1,
+            label="Imputed data",
+            linestyle="none",
+        ),
+    ]
+    ax.legend(handles=legend_elements, loc="upper right")
+
+    return fig
+
+
 def save_figure(
     fig,
     file_name,
@@ -258,3 +412,62 @@ def pair_plot(X, y):
     fig = svm.fig
 
     return fig
+
+
+def plot_histogram(df, variable, units="", density=True, color="BLUE_BARS", bins=30):
+    """
+    Generates a histogram plot for a specified numerical variable.
+
+    The plot visualizes the distribution of the data, with the Y-axis dynamically
+    labeled as 'Density' or 'Count' based on the `density` parameter.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        The DataFrame containing the data to be plotted.
+    variable : str
+        The name of the column in 'df' whose distribution will be plotted.
+    units : str, optional
+        Units to display next to the variable name on the X-axis. Defaults to "".
+    density : bool, optional
+        If True (default), the Y-axis is scaled to a Probability Density,
+        meaning the area under the bars sums to 1. If False, the Y-axis
+        displays the raw count of observations per bin.
+    color : str, optional
+        Key corresponding to the bar color in the global 'paper_colors' dictionary
+        (e.g., "BLUE_BARS"). Defaults to "BLUE_LINES".
+    bins : int or sequence, optional
+        The number of equal-width bins in the range to divide the data.
+        Can be an integer (default is 30) or a sequence specifying the bin edges.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+        The generated Matplotlib Figure object containing the histogram.
+
+    Notes
+    -----
+    The plot applies a fixed style (alpha=0.7, white edge-color) and grid
+    for visual consistency.
+    """
+    fig, ax = plt.subplots()
+
+    ax.hist(
+        df[variable],
+        bins=bins,
+        density=density,
+        alpha=0.7,
+        color=paper_colors[color],
+        edgecolor="white",
+    )
+
+    ax.set_xlabel(f"{variable} {units}")
+
+    if density:
+        ax.set_ylabel("Density")
+    else:
+        ax.set_ylabel("Count")
+
+    ax.grid(alpha=0.8, linestyle="--")
+
+    return fig

{direl_ts_tool_kit-0.5.0.dist-info → direl_ts_tool_kit-0.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: direl-ts-tool-kit
-Version: 0.5.0
+Version: 0.7.0
 Summary: A toolbox for time series analysis and visualization.
 Home-page: https://gitlab.com/direl/direl_tool_kit
 Author: Diego Restrepo-Leal
@@ -89,6 +89,14 @@ 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.
 
+#### plot_interpolation_analysis
+`plot_interpolation_analysis(df_original, variable, units="", method="polynomial", order=2, imputation_se=None, time_unit="Year", rot=90)`
+
+Performs interpolation on missing data (NaNs) in a specified column and
+plots the result, highlighting the imputed points with confidence intervals
+if the Imputation Standard Error (SE) is provided.
+
+
 #### save_figure
 `save_figure(fig, file_name, variable_name="", path="./")`
 
@@ -117,6 +125,14 @@ It focuses on the lower triangular part (corner=True) and includes a
 regression line for trend visualization.
 
 
+#### plot_histogram
+`plot_histogram(df, variable, units="", density=True, color="BLUE_BARS", bins=30)`
+
+Generates a histogram plot for a specified numerical variable.
+
+The plot visualizes the distribution of the data, with the Y-axis dynamically
+labeled as 'Density' or 'Count' based on the `density` parameter.
+
 # Examples
 - [Example 1](https://gitlab.com/direl/direl_tool_kit/-/blob/main/example/example_01.md?ref_type=heads)
 - [Example 2](https://gitlab.com/direl/direl_tool_kit/-/blob/main/example/example_02.md?ref_type=heads)

direl_ts_tool_kit-0.7.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=E8oswirgUyzojKRvUA39MiZqplCFMMmIJtYBDOOM4JM,14839
+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.7.0.dist-info/licenses/LICENCE,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+direl_ts_tool_kit-0.7.0.dist-info/METADATA,sha256=UTxeb67A2nbjkUDpPd2tAP_7GgEc4KRmaawwDz2fzG4,5196
+direl_ts_tool_kit-0.7.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+direl_ts_tool_kit-0.7.0.dist-info/top_level.txt,sha256=vMCRudnGnsdRg_6fUftnG8PF2Y1m0bjBDMf3pCAp6bc,18
+direl_ts_tool_kit-0.7.0.dist-info/RECORD,,

direl_ts_tool_kit-0.5.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=WVcxr5LK0ht8RmFscUri7HcCB5Vd50UItocYNnlj3sA,1032
-direl_ts_tool_kit/plot/plot_ts.py,sha256=PbqclUAVTbYa7YTf59Q75XW1qqaW_I7qPuuTXMQmmxI,8340
-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.5.0.dist-info/licenses/LICENCE,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-direl_ts_tool_kit-0.5.0.dist-info/METADATA,sha256=ctS91dCUFsS4i4HI80XFjhHVEaySpNVQw79wyvh_ipM,4509
-direl_ts_tool_kit-0.5.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-direl_ts_tool_kit-0.5.0.dist-info/top_level.txt,sha256=vMCRudnGnsdRg_6fUftnG8PF2Y1m0bjBDMf3pCAp6bc,18
-direl_ts_tool_kit-0.5.0.dist-info/RECORD,,