pytrendy 1.1.11.dev2__tar.gz → 1.1.11.dev3__tar.gz

{pytrendy-1.1.11.dev2 → pytrendy-1.1.11.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytrendy
-Version: 1.1.11.dev2
+Version: 1.1.11.dev3
 Summary: Trend Detection in Python. Applicable for real-world industry use cases in time series.
 License: MIT License
          

{pytrendy-1.1.11.dev2 → pytrendy-1.1.11.dev3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pytrendy"
-version = "1.1.11.dev2"
+version = "1.1.11.dev3"
 description = "Trend Detection in Python. Applicable for real-world industry use cases in time series."
 authors = [
     { name = "Russell Sammut Bonnici", email = "r.sammutbonnici@gmail.com" },

{pytrendy-1.1.11.dev2 → pytrendy-1.1.11.dev3}/pytrendy/__init__.py

@@ -10,7 +10,7 @@ apply classification heuristics, and access structured results for downstream an
 
 This package is organized into the following modules:
 
-# 1. [detect_trends](detect_trends.html)
+# 1. [detect_trends](detect_trends)
 
 - Defines the primary pipeline function for executing PyTrendy's trend detection workflow.
 - This function coordinates signal preprocessing, segment extraction, boundary refinement, metric analysis, and optional visualization in a single call.
@@ -23,7 +23,7 @@ The `io` module provides essential interfaces for interacting with the input and
 It streamlines access to curated datasets, supports detailed visualization of trend segments, and offers structured result handling for downstream analysis.  
 Designed for both exploratory workflows and programmatic integration, this module enables users to efficiently load data, interpret results, and present findings.
 
-## 2.1 [data_loader](io/data_loader.html)
+## 2.1 [data_loader](io/data_loader)
 
 - Provides access to built-in datasets packaged with PyTrendy.
 - Enables quick loading of synthetic time series and classification references.
@@ -31,7 +31,7 @@ Designed for both exploratory workflows and programmatic integration, this modul
 - Delivers standardized input formats optimized for trend detection and segment analysis.
 
 
-## 2.2 [plot_pytrendy](io/plot_pytrendy.html)
+## 2.2 [plot_pytrendy](io/plot_pytrendy)
 
 - Generates annotated visualizations of trend segments over time series data.
 - Highlights matplotlib plots with Up, Down, Flat, and Noise regions using shaded overlays and metadata.
@@ -39,7 +39,7 @@ Designed for both exploratory workflows and programmatic integration, this modul
 - Makes the visualization ready for reporting, presentation, and analytical review.
 
 
-## 2.3 [results_pytrendy](io/results_pytrendy.html)
+## 2.3 [results_pytrendy](io/results_pytrendy)
 
 - Wraps detection output into a structured results object.
 - Implements the `PyTrendyResults` class for segment filtering, ranking, and summarization.
@@ -48,13 +48,13 @@ Designed for both exploratory workflows and programmatic integration, this modul
 
 
 
-# 3. [post_processing](post_processing.html)
+# 3. [post_processing](post_processing)
 
 The `post_processing` module provides utilities for refining, classifying, and analyzing trend segments.
 It transforms raw detections into interpretable, ranked structures by adjusting boundaries, labeling temporal behavior, and computing signal metrics.  
 This module ensures that the output is analytically robust and ready for downstream use.
 
-## 3.1 [segments_get](post_processing/segments_get.html)
+## 3.1 [segments_get](post_processing/segments_get)
 
 - Extracts continuous segments from the `trend_flag` column.
 - Applies minimum length constraints to filter out noise.
@@ -62,7 +62,7 @@ This module ensures that the output is analytically robust and ready for downstr
 - Serves as the first step in segment-level post-processing.
 
 
-## 3.2 [segments_refine](post_processing/segments_refine.html)
+## 3.2 [segments_refine](post_processing/segments_refine)
 
 - Adjusts segment boundaries based on local extrema and changepoint detection.
 - Classifies segments as 'gradual' or 'abrupt' using DTW alignment.
@@ -70,7 +70,7 @@ This module ensures that the output is analytically robust and ready for downstr
 - Groups short consecutive segments and removes artifacts.
 
 
-## 3.3 [segments_analyse](post_processing/segments_analyse.html)
+## 3.3 [segments_analyse](post_processing/segments_analyse)
 
 - Computes metrics for each segment, comparing pretreatment vs post-treatment behavior.
 - Includes absolute and percent change, duration, and cumulative movement.
@@ -79,14 +79,14 @@ This module ensures that the output is analytically robust and ready for downstr
 
 
 
-# 4. [process_signals](process_signals.html)
+# 4. [process_signals](process_signals)
 
 - Implements core signal processing logic to identify meaningful regions within a time series.
 - By applying Savitzky-Golay smoothing and rolling statistical measures, this module flags flat, noisy, and directional trends.
 - These flags serve as the foundation for segment extraction and subsequent analysis within the PyTrendy pipeline.
 
 
-# 5. [simpledtw](simpledtw.html)
+# 5. [simpledtw](simpledtw)
 
 - Provides an efficient implementation of Dynamic Time Warping (DTW) for comparing time series segments.
 - This module is used internally to classify trends by aligning detected segments with reference signals and evaluating similarity based on alignment cost.

{pytrendy-1.1.11.dev2 → pytrendy-1.1.11.dev3}/pytrendy/detect_trends.py

@@ -8,7 +8,7 @@ from .post_processing.segments_analyse import analyse_segments
 from .io.plot_pytrendy import plot_pytrendy
 from .io.results_pytrendy import PyTrendyResults
 
-def detect_trends(df:pd.DataFrame, date_col:str, value_col: str, plot=True, method_params:dict=None) -> PyTrendyResults:
+def detect_trends(df: pd.DataFrame, date_col: str, value_col: str, plot=True, method_params: dict=None, debug: bool=False ) -> PyTrendyResults:
     """
     This is the main function that runs trend detection end-to-end.
     
@@ -41,7 +41,10 @@ def detect_trends(df:pd.DataFrame, date_col:str, value_col: str, plot=True, meth
 
             - **is_abrupt_padded** (`bool`): Whether to pad abrupt transitions between segments. Defaults to `False`.
             - **abrupt_padding** (`int`): Number of days to pad around abrupt transitions. Only referenced when `is_abrupt_padded` is `True`. Defaults to `28`.
-
+        debug (bool, optional):
+            If `True` will run in debug mode, outputting various additional plots and print statements. Only recommended for developers of pytrendy.
+            Defaults to `False`.
+            
     Returns:
         PyTrendyResults:
             An object encapsulating the detected segments and associated metadata.
@@ -62,7 +65,7 @@ def detect_trends(df:pd.DataFrame, date_col:str, value_col: str, plot=True, meth
     }
 
     # Core 5-step pipeline
-    df = process_signals(df, value_col)
+    df = process_signals(df, value_col, debug=debug)
     segments = get_segments(df)
     segments = refine_segments(df, value_col, segments, method_params)
     segments = analyse_segments(df, value_col, segments)

{pytrendy-1.1.11.dev2 → pytrendy-1.1.11.dev3}/pytrendy/io/__init__.py

@@ -8,7 +8,7 @@ larger workflows.
 
 # Included Modules
 
-## 1. [data_loader](data_loader.html)
+## 1. [data_loader](data_loader)
 Loads built-in datasets packaged with PyTrendy. These include:
 
 - `'series_synthetic'`: A synthetic time series with embedded uptrends, downtrends, and flat regions.
@@ -16,13 +16,13 @@ Loads built-in datasets packaged with PyTrendy. These include:
 
 Useful for testing, demos, and validating detection logic.
 
-## 2. [plot_pytrendy](plot_pytrendy.html)
+## 2. [plot_pytrendy](plot_pytrendy)
 
 - Generates annotated matplotlib plots of detected trend segments over the original signal.
 - Highlights Up, Down, Flat, and Noise regions with shaded overlays and ranks significant trends.
 - Supports visual debugging and presentation-ready output.
 
-## 3. [results_pytrendy](results_pytrendy.html)
+## 3. [results_pytrendy](results_pytrendy)
 Wraps the output of `detect_trends` into a structured `PyTrendyResults` object. It provides:
 
 - Summary statistics (counts, rankings, best segment)

{pytrendy-1.1.11.dev2 → pytrendy-1.1.11.dev3}/pytrendy/post_processing/__init__.py

@@ -9,7 +9,7 @@ boundary adjustments, classification heuristics, and quantitative analysis.
 
 # Included Modules
 
-## 1. [segments_get](segments_get.html)
+## 1. [segments_get](segments_get)
 Extracts contiguous segments from the `trend_flag` column produced by signal processing.
 
 Applies minimum length constraints to ensure meaningful segments are retained:
@@ -22,34 +22,34 @@ Applies minimum length constraints to ensure meaningful segments are retained:
 
 The segment refinement functionality is organized under the `segments_refine` package:
 
-### [segments_refine](segments_refine.html)
+### [segments_refine](segments_refine)
 Main orchestration module with `refine_segments()` function that coordinates the full post-processing pipeline.
 
 The `segments_refine` package contains focused sub-modules:
 
-### [segments_refine.update_neighbours](segments_refine/update_neighbours.html)
+### [segments_refine.update_neighbours](segments_refine/update_neighbours)
 Helper functions for adjusting segment boundaries when neighboring segments are updated:
 - `update_prev_segment`: Adjusts the end of the previous segment
 - `update_next_segment`: Adjusts the start of the next segment
 
-### [segments_refine.gradual_expand_contract](segments_refine/gradual_expand_contract.html)
+### [segments_refine.gradual_expand_contract](segments_refine/gradual_expand_contract)
 - `expand_contract_segments`: Adjusts boundaries based on local extrema (±7 days window)
 
-### [segments_refine.trend_classify](segments_refine/trend_classify.html)
+### [segments_refine.trend_classify](segments_refine/trend_classify)
 - `classify_trends`: Uses Dynamic Time Warping (DTW) to label segments as 'gradual' or 'abrupt'
 
-### [segments_refine.abrupt_shaving](segments_refine/abrupt_shaving.html)
+### [segments_refine.abrupt_shaving](segments_refine/abrupt_shaving)
 - `shave_abrupt_trends`: Detects changepoints in abrupt segments using z-score outliers
 
-### [segments_refine.segment_grouping](segments_refine/segment_grouping.html)
+### [segments_refine.segment_grouping](segments_refine/segment_grouping)
 - `group_segments`: Merges short, consecutive segments with the same direction
 
-### [segments_refine.artifact_cleanup](segments_refine/artifact_cleanup.html)
+### [segments_refine.artifact_cleanup](segments_refine/artifact_cleanup)
 - `clean_artifacts`: Removes invalid segments (inversions, overlaps)
 - `fill_in_flats`: Fills gaps between segments with flat regions
 
 
-## 3. [segments_analyse](segments_analyse.html)
+## 3. [segments_analyse](segments_analyse)
 Adds quantitative descriptors to each segment, comparing pretreatment vs post-treatment behavior.
 
 Metrics include:

{pytrendy-1.1.11.dev2 → pytrendy-1.1.11.dev3}/pytrendy/process_signals.py

@@ -3,9 +3,10 @@
 import pandas as pd
 import numpy as np
 from scipy.signal import savgol_filter
+from scipy.stats import iqr
 from .post_processing.segments_refine.segment_grouping import GROUPING_DISTANCE
 
-def process_signals(df: pd.DataFrame, value_col: str) -> pd.DataFrame:
+def process_signals(df: pd.DataFrame, value_col: str, debug: bool=False) -> pd.DataFrame:
     """
     Applies signal processing techniques to classify regions of a time series.
 
@@ -31,6 +32,8 @@ def process_signals(df: pd.DataFrame, value_col: str) -> pd.DataFrame:
             Input time series data with a datetime index and signal column.
         value_col (str): 
             Name of the column containing the signal to process.
+        debug (bool, optional):
+            If `True` will run in debug mode, outputting various additional plots and print statements. Only recommended for developers of pytrendy. Defaults to `False`.
 
     Returns:
         `pd.DataFrame`: Modified DataFrame with additional columns.
@@ -43,7 +46,7 @@ def process_signals(df: pd.DataFrame, value_col: str) -> pd.DataFrame:
     WINDOW_NOISE = int(WINDOW_SMOOTH*0.5)
 
     THRESHOLD_NOISE = 2.5 # Sensitivity to detecting noise (recommended 0-10)
-    THRESHOLD_SMOOTH = 0.25 # Sensitivity to detecting trends (recommended 0-0.5)
+    THRESHOLD_SMOOTH = 0.001 # Sensitivity to detecting trends as fraction of iqr
 
     # 1. Noise detection via SNR. 
     # 1.1 Compute the SNR
@@ -173,38 +176,52 @@ def process_signals(df: pd.DataFrame, value_col: str) -> pd.DataFrame:
     df['trend_flag'] = 0
     df.loc[df['flat_flag'] == 1, 'trend_flag'] = -2
     df.loc[df['noise_flag'] == 1, 'trend_flag'] = -3
-    df['smoothed_deriv'] = savgol_filter(df[value_col], window_length=WINDOW_SMOOTH, polyorder=1, deriv=1)
-    df.loc[(df['smoothed_deriv'] >= THRESHOLD_SMOOTH) & (df['flat_flag'] == 0) & (df['noise_flag'] == 0), 'trend_flag'] = 1
-    df.loc[(df['smoothed_deriv'] < -THRESHOLD_SMOOTH) & (df['flat_flag'] == 0) & (df['noise_flag'] == 0), 'trend_flag'] = -1
-
-    # import matplotlib.pyplot as plt
-
-    # ax = df[[value_col, 'snr']].plot(figsize=(20,3), secondary_y='snr')
-    # ax.right_ax.axhline(y=0, color='gray', linestyle='--', linewidth=2)
-    # plt.show()
-
-    # ax = df[[value_col, 'noise_flag']].plot(figsize=(20,3), secondary_y='noise_flag')
-    # ax.right_ax.axhline(y=0, color='gray', linestyle='--', linewidth=2)
-    # plt.show()
-
-    # ax = df[[value_col, 'smoothed']].plot(figsize=(20,3), secondary_y='smoothed')
-    # ax.right_ax.axhline(y=0, color='gray', linestyle='--', linewidth=2)
-    # plt.show()
 
-    # ax = df[[value_col, 'smoothed_std']].plot(figsize=(20,3), secondary_y='smoothed_std')
-    # ax.right_ax.axhline(y=0, color='gray', linestyle='--', linewidth=2)
-    # plt.show()
-
-    # ax = df[[value_col, 'flat_flag']].plot(figsize=(20,3), secondary_y='flat_flag')
-    # ax.right_ax.axhline(y=0, color='gray', linestyle='--', linewidth=2)
-    # plt.show()
-
-    # ax = df[[value_col, 'smoothed_deriv']].plot(figsize=(20,3), secondary_y='smoothed_deriv')
-    # ax.right_ax.axhline(y=0, color='gray', linestyle='--', linewidth=2)
-    # plt.show()
-
-    # ax = df[[value_col, 'trend_flag']].plot(figsize=(20,3), secondary_y='trend_flag')
-    # ax.right_ax.axhline(y=0, color='gray', linestyle='--', linewidth=2)
-    # plt.show()
+    derivative_limit = abs(iqr(df[value_col])) * THRESHOLD_SMOOTH
+    df['smoothed_deriv'] = savgol_filter(df[value_col], window_length=WINDOW_SMOOTH, polyorder=1, deriv=1)
+    df.loc[(df['smoothed_deriv'] >= derivative_limit) & (df['flat_flag'] == 0) & (df['noise_flag'] == 0), 'trend_flag'] = 1
+    df.loc[(df['smoothed_deriv'] < -derivative_limit) & (df['flat_flag'] == 0) & (df['noise_flag'] == 0), 'trend_flag'] = -1
+
+    if debug:
+        import matplotlib.pyplot as plt
+
+        #df['smoothed_deriv'].hist()
+        #plt.show()
+
+        ax = df[[value_col, 'snr']].plot(figsize=(20,3), secondary_y='snr')
+        ax.right_ax.axhline(y=THRESHOLD_NOISE, color='gray', linestyle='--', linewidth=2)
+        plt.title("Signal-Noise Ratio (SNR)")
+        plt.show()
+
+        ax = df[[value_col, 'noise_flag']].plot(figsize=(20,3), secondary_y='noise_flag')
+        ax.right_ax.axhline(y=0, color='gray', linestyle='--', linewidth=2)
+        plt.title("Noise Flag")
+        plt.show()
+
+        ax = df[[value_col, 'smoothed']].plot(figsize=(20,3), secondary_y='smoothed')
+        ax.right_ax.axhline(y=0, color='gray', linestyle='--', linewidth=2)
+        plt.title("Smoothed")
+        plt.show()
+
+        ax = df[[value_col, 'smoothed_std']].plot(figsize=(20,3), secondary_y='smoothed_std')
+        ax.right_ax.axhline(y=0, color='gray', linestyle='--', linewidth=2)
+        plt.title("Smoothed Std")
+        plt.show()
+
+        ax = df[[value_col, 'flat_flag']].plot(figsize=(20,3), secondary_y='flat_flag')
+        ax.right_ax.axhline(y=0, color='gray', linestyle='--', linewidth=2)
+        plt.title("Flat Flag")
+        plt.show()
+
+        ax = df[[value_col, 'smoothed_deriv']].plot(figsize=(20,3), secondary_y='smoothed_deriv')
+        ax.right_ax.axhline(y=THRESHOLD_SMOOTH, color='gray', linestyle='--', linewidth=2)
+        ax.right_ax.axhline(y=-THRESHOLD_SMOOTH, color='gray', linestyle=':', linewidth=2)
+        plt.title("Smoothed Derivative")
+        plt.show()
+
+        ax = df[[value_col, 'trend_flag']].plot(figsize=(20,3), secondary_y='trend_flag')
+        ax.right_ax.axhline(y=0, color='gray', linestyle='--', linewidth=2)
+        plt.title("Trend Flag")
+        plt.show()
 
     return df