pytrendy 1.4.0.dev3__tar.gz → 1.4.0.dev4__tar.gz

{pytrendy-1.4.0.dev3 → pytrendy-1.4.0.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytrendy
-Version: 1.4.0.dev3
+Version: 1.4.0.dev4
 Summary: Trend Detection in Python. Applicable for real-world industry use cases in time series.
 License: MIT License
          
@@ -91,10 +91,13 @@ Most time series tools give you either a "trend component" (via decomposition) o
 
 ## Features
 
-![](https://raw.githubusercontent.com/RussellSB/pytrendy/refs/heads/develop/plots/Gradual-Cropped.gif)
-![](https://raw.githubusercontent.com/RussellSB/pytrendy/refs/heads/develop/plots/Abrupt-Cropped.gif)
-![](https://raw.githubusercontent.com/RussellSB/pytrendy/refs/heads/develop/plots/Noise-Spikes-Cropped.gif)
-![](https://raw.githubusercontent.com/RussellSB/pytrendy/refs/heads/develop/plots/Noise-Random-Cropped.gif)
+![](https://raw.githubusercontent.com/RussellSB/pytrendy/refs/heads/develop/plots/Gradual.gif)
+
+![](https://raw.githubusercontent.com/RussellSB/pytrendy/refs/heads/develop/plots/Abrupt.gif)
+
+![](https://raw.githubusercontent.com/RussellSB/pytrendy/refs/heads/develop/plots/Noise-Spikes.gif)
+
+![](https://raw.githubusercontent.com/RussellSB/pytrendy/refs/heads/develop/plots/Noise-Random.gif)
 
 ## Quickstart
 

{pytrendy-1.4.0.dev3 → pytrendy-1.4.0.dev4}/README.md

@@ -28,10 +28,13 @@ Most time series tools give you either a "trend component" (via decomposition) o
 
 ## Features
 
-![](https://raw.githubusercontent.com/RussellSB/pytrendy/refs/heads/develop/plots/Gradual-Cropped.gif)
-![](https://raw.githubusercontent.com/RussellSB/pytrendy/refs/heads/develop/plots/Abrupt-Cropped.gif)
-![](https://raw.githubusercontent.com/RussellSB/pytrendy/refs/heads/develop/plots/Noise-Spikes-Cropped.gif)
-![](https://raw.githubusercontent.com/RussellSB/pytrendy/refs/heads/develop/plots/Noise-Random-Cropped.gif)
+![](https://raw.githubusercontent.com/RussellSB/pytrendy/refs/heads/develop/plots/Gradual.gif)
+
+![](https://raw.githubusercontent.com/RussellSB/pytrendy/refs/heads/develop/plots/Abrupt.gif)
+
+![](https://raw.githubusercontent.com/RussellSB/pytrendy/refs/heads/develop/plots/Noise-Spikes.gif)
+
+![](https://raw.githubusercontent.com/RussellSB/pytrendy/refs/heads/develop/plots/Noise-Random.gif)
 
 ## Quickstart
 

{pytrendy-1.4.0.dev3 → pytrendy-1.4.0.dev4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pytrendy"
-version = "1.4.0.dev3"
+version = "1.4.0.dev4"
 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.4.0.dev3 → pytrendy-1.4.0.dev4}/pytrendy/detect_trends.py

@@ -41,6 +41,7 @@ def detect_trends(df: pd.DataFrame, date_col: str, value_col: str, plot=True, me
             Optional parameters to customize detection heuristics. Supported keys:
 
             - **abrupt_padding** (`int`): Number of days to pad around abrupt transitions. Defaults to `0`.
+            - **gradual_padding** (`int`): Number of days to pad after gradual trend ends. Defaults to `0`.
             - **avoid_noise** (`bool`): Whether to avoid noisy segments in trend detection. Defaults to `True`.
         plot_params (dict, optional):
             Optional dict to customise plot appearance. Only used when `plot` is `True`. Supported keys:
@@ -83,6 +84,7 @@ def detect_trends(df: pd.DataFrame, date_col: str, value_col: str, plot=True, me
     # Configures trend detection heuristics
     method_params = {
         'abrupt_padding': method_params.get('abrupt_padding', 0),
+        'gradual_padding': method_params.get('gradual_padding', 0),
         'avoid_noise': method_params.get('avoid_noise', True),
     }
 

{pytrendy-1.4.0.dev3 → pytrendy-1.4.0.dev4}/pytrendy/post_processing/segments_refine/__init__.py

@@ -30,6 +30,7 @@ def refine_segments(df: pd.DataFrame, value_col: str, segments: list[dict], meth
         method_params (dict): Optional parameters for abrupt padding and control. Supported keys:
 
             - **abrupt_padding** (`int`): Number of days to pad. Defaults to `0`.
+            - **gradual_padding** (`int`): Number of days to extend gradual segment ends forward. Defaults to `0`.
 
     Returns:
         list: Final refined segment list.
@@ -40,7 +41,7 @@ def refine_segments(df: pd.DataFrame, value_col: str, segments: list[dict], meth
     segments_refined = classify_trends(df, value_col, segments_refined)
     segments_refined = group_segments(segments_refined) # grouping 1st pass: sporadic flats & noises
 
-    segments_refined = expand_contract_segments(df, value_col, segments_refined) # for gradual
+    segments_refined = expand_contract_segments(df, value_col, segments_refined, method_params) # for gradual + gradual padding
     segments_refined = shave_abrupt_trends(df, value_col, segments_refined, method_params) # for abrupt
 
     segments_refined = clean_artifacts(df, value_col, segments_refined, method_params) # cleans overlaps etc from expand/contract

{pytrendy-1.4.0.dev3 → pytrendy-1.4.0.dev4}/pytrendy/post_processing/segments_refine/artifact_cleanup.py

@@ -259,7 +259,10 @@ def clean_artifacts(df: pd.DataFrame, value_col: str, segments_refined: list[dic
         is_flat = segment['direction'] == 'Flat'
         is_gradual = ('trend_class' in segment and segment['trend_class'] == 'gradual')
         is_abrupt = ('trend_class' in segment and segment['trend_class'] == 'abrupt')
-        is_padded = is_abrupt and ('padded' in segment) and (segment['padded'] == True)
+        # Covers both abrupt_padding and gradual_padding: padded segments must
+        # not be reclassified as Flat by the trend_too_flat / trend_too_small
+        # checks below, since the extension was intentional.
+        is_padded = ('padded' in segment) and (segment['padded'] == True)
         is_small = len(df_segment) <= 5
 
         # Edge case 1: Check SNR for trend but noise
@@ -316,7 +319,9 @@ def clean_artifacts(df: pd.DataFrame, value_col: str, segments_refined: list[dic
             segment['direction'] = 'Noise' 
             if 'trend_class' in segment: del segment['trend_class']
 
-        if trend_ends_too_close or trend_too_small or trend_too_flat:
+        # Padded segments are protected from flat reclassification — the extension
+        # into flat regions is intentional and the original trend still holds.
+        if trend_ends_too_close or trend_too_small or (trend_too_flat and not is_padded):
             segment['direction'] = 'Flat' 
             if 'trend_class' in segment: del segment['trend_class']
         

{pytrendy-1.4.0.dev3 → pytrendy-1.4.0.dev4}/pytrendy/post_processing/segments_refine/gradual_expand_contract.py

@@ -8,17 +8,21 @@ from copy import deepcopy
 from .update_neighbours import update_prev_segment, update_next_segment
 
 
-def expand_contract_segments(df: pd.DataFrame, value_col: str, segments: list[dict]) -> list[dict]:
+def expand_contract_segments(df: pd.DataFrame, value_col: str, segments: list[dict], method_params: dict) -> list[dict]:
     """
     Refines segment boundaries by expanding or contracting based on local extrema.
 
     Examines ±7 days around each segment's start and end to find stronger turning points.
     Skips segments classified as 'abrupt' to preserve their precision.
+    Optionally pads gradual segments into adjacent flat regions when ``gradual_padding > 0``.
 
     Args:
         df (pd.DataFrame): Time series DataFrame.
         value_col (str): Name of the signal column.
         segments (list): List of segment dictionaries.
+        method_params (dict): Detection parameters. Supported keys:
+
+            - **gradual_padding** (`int`): Days to extend gradual segment ends forward. Defaults to `0`.
 
     Returns:
         list: Refined segment list with updated boundaries.
@@ -114,4 +118,62 @@ def expand_contract_segments(df: pd.DataFrame, value_col: str, segments: list[di
             segments_refined[i]['end'] = new_end.strftime('%Y-%m-%d')
             update_next_segment(i, new_end, segments, segments_refined)
 
+    # Pad gradual segments into adjacent flat regions when gradual_padding is set.
+    # Mirrors the abrupt padding pattern: called from within the same module rather
+    # than exposed as a separate top-level step in segments_refine/__init__.py.
+    segments_refined = _pad_gradual_trends(df, segments_refined, method_params)
+
     return segments_refined
+
+
+def _pad_gradual_trends(df: pd.DataFrame, segments: list[dict], method_params: dict) -> list[dict]:
+    """
+    Extends gradual segment end dates by a specified number of days.
+
+    Extends the end date forward, truncating before any non-Flat segment that
+    would be overlapped, and clamping to the last index date. Sets a ``padded``
+    flag on modified segments.
+
+    Args:
+        df (pd.DataFrame): Time series DataFrame.
+        segments (list): List of segment dictionaries.
+        method_params (dict): Supported keys:
+
+            - **gradual_padding** (`int`): Number of days to pad. Defaults to ``0``.
+
+    Returns:
+        list: Segment list with padded gradual boundaries.
+    """
+
+    gradual_padding = method_params.get('gradual_padding', 0)
+    if gradual_padding <= 0:
+        return segments
+
+    segments_padded = deepcopy(segments)
+
+    meta_df = pd.DataFrame(segments)
+    meta_df['start'] = pd.to_datetime(meta_df['start'])
+    meta_df['end'] = pd.to_datetime(meta_df['end'])
+
+    for i, segment in enumerate(segments):
+
+        if segment['direction'] not in ['Up', 'Down'] or segment.get('trend_class') != 'gradual':
+            continue
+
+        gradual_end = pd.to_datetime(segment['end'])
+
+        new_end = gradual_end + pd.Timedelta(days=gradual_padding)
+        overlaps = meta_df.loc[(meta_df['start'] > gradual_end) & (meta_df['start'] <= new_end)]
+        overlaps_nonflats = overlaps[overlaps['direction'] != 'Flat']
+
+        if not overlaps_nonflats.empty:
+            first_notflat_overlap = overlaps_nonflats.iloc[0]
+            new_end = pd.to_datetime(first_notflat_overlap['start']) - pd.Timedelta(days=1)
+
+        new_end = min(new_end, df.index[-1])
+        segments_padded[i]['end'] = new_end.strftime('%Y-%m-%d')
+        update_next_segment(i, new_end, segments, segments_padded)
+
+        segments_padded[i]['padded'] = new_end != gradual_end
+
+    return segments_padded