direl-ts-tool-kit 0.8.1__tar.gz → 0.9.1__tar.gz

{direl_ts_tool_kit-0.8.1 → direl_ts_tool_kit-0.9.1}/PKG-INFO

@@ -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 → direl_ts_tool_kit-0.9.1}/README.md

@@ -56,6 +56,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)`
 
@@ -72,6 +73,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")`
 
@@ -80,6 +82,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)`
 
@@ -110,6 +113,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 → direl_ts_tool_kit-0.9.1}/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 → direl_ts_tool_kit-0.9.1}/direl_ts_tool_kit.egg-info/PKG-INFO

@@ -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 → direl_ts_tool_kit-0.9.1}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name="direl-ts-tool-kit",
-    version="0.8.1",
+    version="0.9.1",
     description="A toolbox for time series analysis and visualization.",
     long_description=open("README.md", encoding="utf-8").read(),
     long_description_content_type="text/markdown",