direl-ts-tool-kit 0.8.1__py3-none-any.whl → 0.9.1__py3-none-any.whl

direl_ts_tool_kit/plot/plot_ts.py

@@ -2,6 +2,7 @@ import numpy as np
 import pandas as pd
 from .plot_style import *
 from scipy.stats import pearsonr
+from scipy.signal import periodogram
 
 
 def plot_time_series(
@@ -12,6 +13,7 @@ def plot_time_series(
     time_unit="Year",
     rot=90,
     auto_format_label=True,
+    sci=False
 ):
     """
     Plots a time series with custom styling and dual-level grid visibility.
@@ -92,7 +94,9 @@ def plot_time_series(
         )
 
     ax.set(xlabel=f"{time_unit}", ylabel=f"{variable} {units}")
-    ax.ticklabel_format(style="sci", axis="y", scilimits=(0, 0))
+
+    if sci==True:
+        ax.ticklabel_format(style="sci", axis="y", scilimits=(0, 0))
 
     if time_unit == "Year":
         ax.xaxis.set_major_locator(mdates.YearLocator())
@@ -548,3 +552,78 @@ def plot_data_boxplot(
     ax.tick_params(axis="x")
 
     return fig
+
+
+def plot_periodogram(
+    ts,
+    detrend="linear",
+    ax=None,
+    fs=365.0,
+    color="BLUE_LINES",
+):
+    """
+    Plots the power spectrum (periodogram) of a time series to identify
+    dominant frequencies (periodicity).
+
+    Parameters
+    ----------
+    ts : pd.Series or np.ndarray
+        The time series data to analyze.
+    detrend : str, optional
+        Method to remove the linear trend ('linear' or 'constant'). Defaults to 'linear'.
+    ax : matplotlib.axes.Axes, optional
+        Existing Axes to draw the plot on. If None, a new figure and axes are created.
+    fs : float, optional
+        The sampling frequency of the time series (cycles per unit of time).
+        Default value 365.0 assumes daily data, leading to frequencies in cycles/year.
+    color : str, optional
+        Key corresponding to the line color in the global 'paper_colors' dictionary.
+        Defaults to "BLUE_LINES".
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+        The generated Matplotlib Figure object.
+
+    Notes
+    -----
+    The X-axis labels are hardcoded to common periodicities (Annual, Monthly, Weekly)
+    and assume a sampling frequency of 365.0 (daily data).
+    """
+
+    freqencies, spectrum = periodogram(
+        ts,
+        fs=fs,
+        detrend=detrend,
+        window="boxcar",
+        scaling="spectrum",
+    )
+
+    if ax is None:
+        fig, ax = plt.subplots()
+    else:
+        fig = ax.figure
+
+    ax.step(freqencies, spectrum, linewidth=3, color=paper_colors[color])
+    ax.set_xscale("log")
+    ax.set_xticks([1, 2, 4, 6, 12, 26, 52, 104])
+
+    ax.set_xticklabels(
+        [
+            "Annual (1)",
+            "Semiannual (2)",
+            "Quarterly (4)",
+            "Bimonthly (6)",
+            "Monthly (12)",
+            "Biweekly (26)",
+            "Weekly (52)",
+            "Semiweekly (104)",
+        ],
+        rotation=90,
+    )
+
+    ax.ticklabel_format(axis="y", style="sci", scilimits=(0, 0))
+    ax.set_ylabel("Variance")
+    ax.grid(alpha=0.8, linestyle="--")
+
+    return fig

{direl_ts_tool_kit-0.8.1.dist-info → direl_ts_tool_kit-0.9.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: direl-ts-tool-kit
-Version: 0.8.1
+Version: 0.9.1
 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,7 @@ 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)`
 
@@ -105,6 +106,7 @@ 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}.
 
+
 #### heat_map
 `heat_map(X, y, colors="Blues")`
 
@@ -113,6 +115,7 @@ Generates a correlation heatmap plot for a set of features and a target variable
 This function concatenates the feature DataFrame (X) and the target Series (y)
 to compute and visualize the full pairwise correlation matrix using Seaborn.
 
+
 #### pair_plot
 `pair_plot(X, y)`
 
@@ -143,6 +146,15 @@ DataFrame or for a single specified variable.
 The function applies consistent styling for the boxes, outliers, and median
 lines using predefined colors from 'paper_colors'.
 
+
+#### plot_periodogram
+
+`plot_periodogram(ts, detrend="linear", ax=None, fs=365.0, color="BLUE_LINES")`
+
+Plots the power spectrum (periodogram) of a time series to identify
+dominant frequencies (periodicity).
+
+
 # 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.8.1.dist-info → direl_ts_tool_kit-0.9.1.dist-info}/RECORD

@@ -1,11 +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=eyv7MLZNiZAPGHj7EJVwt1odsF9MOkBvbx731isB7Yc,17376
+direl_ts_tool_kit/plot/plot_ts.py,sha256=XQfz9deexMLvzhM6ABD_eGghVpaAD3Vy0aRzSEny1Yc,19480
 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.8.1.dist-info/licenses/LICENCE,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-direl_ts_tool_kit-0.8.1.dist-info/METADATA,sha256=7-kMy-6DeWVfQ-giWDCksXiEdcS5kmOL2P0CT80VoCY,5559
-direl_ts_tool_kit-0.8.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-direl_ts_tool_kit-0.8.1.dist-info/top_level.txt,sha256=vMCRudnGnsdRg_6fUftnG8PF2Y1m0bjBDMf3pCAp6bc,18
-direl_ts_tool_kit-0.8.1.dist-info/RECORD,,
+direl_ts_tool_kit-0.9.1.dist-info/licenses/LICENCE,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+direl_ts_tool_kit-0.9.1.dist-info/METADATA,sha256=J8WGPY3VWni35UwIz0xm50qDhnFKLHA3mO_4vVb-Qek,5773
+direl_ts_tool_kit-0.9.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+direl_ts_tool_kit-0.9.1.dist-info/top_level.txt,sha256=vMCRudnGnsdRg_6fUftnG8PF2Y1m0bjBDMf3pCAp6bc,18
+direl_ts_tool_kit-0.9.1.dist-info/RECORD,,

{direl_ts_tool_kit-0.8.1.dist-info → direl_ts_tool_kit-0.9.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any