pytrendy 1.4.0.dev1__tar.gz → 1.4.0.dev3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytrendy
-Version: 1.4.0.dev1
+Version: 1.4.0.dev3
 Summary: Trend Detection in Python. Applicable for real-world industry use cases in time series.
 License: MIT License
          
@@ -115,7 +115,7 @@ results.print_summary()
 Detected: 
 - 3 Uptrends. 
 - 3 Downtrends.
-- 3 Flats.
+- 2 Flats.
 - 0 Noise.
 
 The best detected trend is Down between dates 2025-05-09 - 2025-06-17
@@ -126,13 +126,12 @@ Full Results:
 time_index                                                                               
 1                 Up  2025-01-02  2025-01-24    22     14.013348            5     gradual
 2               Down  2025-01-25  2025-02-05    11    -13.564214            6     gradual
-3               Flat  2025-02-06  2025-02-09     3     -1.168831            9         NaN
-4                 Up  2025-02-10  2025-03-14    32     24.632035            3     gradual
-5               Flat  2025-03-15  2025-03-17     2      5.660173            7         NaN
-6               Down  2025-03-18  2025-04-01    14    -22.721861            4     gradual
-7                 Up  2025-04-02  2025-05-08    36     72.611833            2     gradual
-8               Down  2025-05-09  2025-06-17    39    -73.253968            1     gradual
-9               Flat  2025-06-18  2025-06-30    12      3.910534            8     NaN 
+3               Flat  2025-02-06  2025-02-09     3     -1.168831            8         NaN
+4                 Up  2025-02-10  2025-03-17    35     26.190476            3     gradual
+5               Down  2025-03-18  2025-04-01    14    -22.721861            4     gradual
+6                 Up  2025-04-02  2025-05-08    36     72.611833            2     gradual
+7               Down  2025-05-09  2025-06-17    39    -73.253968            1     gradual
+8               Flat  2025-06-18  2025-06-30    12      3.910534            7         NaN
 -------------------------------------------------------------------------------
 ```
 
@@ -144,7 +143,7 @@ results.filter_segments(direction='Up', sort_by='change_rank')[:3]
 | time_index | direction | start | end | trend_class | change | pct_change | days | total_change | SNR | change_rank |
 |---|---|---|---|---|---|---|---|---|---|---|
 | 7 | Up | 2025-04-02 | 2025-05-08 | gradual | 72.61 | 367.50% | 36 | 72.61 | 21.70 | 2 |
-| 4 | Up | 2025-02-10 | 2025-03-14 | gradual | 24.63 | 169.22% | 32 | 24.63 | 18.87 | 3 |
+| 4 | Up | 2025-02-10 | 2025-03-17 | gradual | 26.19 | 179.93% | 35 | 26.19 | 18.61 | 3 |
 | 1 | Up | 2025-01-02 | 2025-01-24 | gradual | 14.01 | 104.41% | 22 | 14.01 | 22.21 | 5 |
 
 `filter_segments` ranks segments by magnitude (`change_rank`). See the [API reference](https://russellsb.github.io/pytrendy/main/reference/pytrendy/io/results_pytrendy/#pytrendy.io.results_pytrendy.PyTrendyResults.filter_segments) for all filter and sort options.

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

@@ -52,7 +52,7 @@ results.print_summary()
 Detected: 
 - 3 Uptrends. 
 - 3 Downtrends.
-- 3 Flats.
+- 2 Flats.
 - 0 Noise.
 
 The best detected trend is Down between dates 2025-05-09 - 2025-06-17
@@ -63,13 +63,12 @@ Full Results:
 time_index                                                                               
 1                 Up  2025-01-02  2025-01-24    22     14.013348            5     gradual
 2               Down  2025-01-25  2025-02-05    11    -13.564214            6     gradual
-3               Flat  2025-02-06  2025-02-09     3     -1.168831            9         NaN
-4                 Up  2025-02-10  2025-03-14    32     24.632035            3     gradual
-5               Flat  2025-03-15  2025-03-17     2      5.660173            7         NaN
-6               Down  2025-03-18  2025-04-01    14    -22.721861            4     gradual
-7                 Up  2025-04-02  2025-05-08    36     72.611833            2     gradual
-8               Down  2025-05-09  2025-06-17    39    -73.253968            1     gradual
-9               Flat  2025-06-18  2025-06-30    12      3.910534            8     NaN 
+3               Flat  2025-02-06  2025-02-09     3     -1.168831            8         NaN
+4                 Up  2025-02-10  2025-03-17    35     26.190476            3     gradual
+5               Down  2025-03-18  2025-04-01    14    -22.721861            4     gradual
+6                 Up  2025-04-02  2025-05-08    36     72.611833            2     gradual
+7               Down  2025-05-09  2025-06-17    39    -73.253968            1     gradual
+8               Flat  2025-06-18  2025-06-30    12      3.910534            7         NaN
 -------------------------------------------------------------------------------
 ```
 
@@ -81,7 +80,7 @@ results.filter_segments(direction='Up', sort_by='change_rank')[:3]
 | time_index | direction | start | end | trend_class | change | pct_change | days | total_change | SNR | change_rank |
 |---|---|---|---|---|---|---|---|---|---|---|
 | 7 | Up | 2025-04-02 | 2025-05-08 | gradual | 72.61 | 367.50% | 36 | 72.61 | 21.70 | 2 |
-| 4 | Up | 2025-02-10 | 2025-03-14 | gradual | 24.63 | 169.22% | 32 | 24.63 | 18.87 | 3 |
+| 4 | Up | 2025-02-10 | 2025-03-17 | gradual | 26.19 | 179.93% | 35 | 26.19 | 18.61 | 3 |
 | 1 | Up | 2025-01-02 | 2025-01-24 | gradual | 14.01 | 104.41% | 22 | 14.01 | 22.21 | 5 |
 
 `filter_segments` ranks segments by magnitude (`change_rank`). See the [API reference](https://russellsb.github.io/pytrendy/main/reference/pytrendy/io/results_pytrendy/#pytrendy.io.results_pytrendy.PyTrendyResults.filter_segments) for all filter and sort options.

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

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

@@ -44,6 +44,7 @@ def detect_trends(df: pd.DataFrame, date_col: str, value_col: str, plot=True, me
             - **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:
+
             - **figsize** (`tuple`): Figure size as (width, height). Defaults to (20, 5).
             - **title** (`str`): Plot title. Defaults to "PyTrendy Detection".
             - **xlabel** (`str`): X-axis label. Defaults to "Date".

{pytrendy-1.4.0.dev1 → pytrendy-1.4.0.dev3}/pytrendy/io/plot_pytrendy.py

@@ -23,6 +23,7 @@ def plot_pytrendy(df: pd.DataFrame, value_col: str, segments_enhanced: list[dict
             If True, suppresses the automatic display of the plot with plt.show(). Defaults to False.
         plot_params (dict, optional):
             Optional dict to customise plot appearance. Supported keys:
+
             - **figsize** (`tuple`): Figure size as (width, height). Defaults to (20, 5).
             - **title** (`str`): Plot title. Defaults to "PyTrendy Detection".
             - **xlabel** (`str`): X-axis label. Defaults to "Date".
@@ -57,6 +58,8 @@ def plot_pytrendy(df: pd.DataFrame, value_col: str, segments_enhanced: list[dict
     }
     if plot_params:
         plot_params = dict(plot_params)  # avoid mutating caller's dict
+        has_custom_legend_loc = 'legend_loc' in plot_params
+        has_custom_legend_anchor = 'legend_bbox_to_anchor' in plot_params
         custom_colors = plot_params.pop('colors', None)
         custom_grid = plot_params.pop('grid', None)
         default_params.update(plot_params)
@@ -64,6 +67,8 @@ def plot_pytrendy(df: pd.DataFrame, value_col: str, segments_enhanced: list[dict
             default_params['colors'].update(custom_colors)
         if custom_grid:
             default_params['grid'].update(custom_grid)
+        if has_custom_legend_loc and not has_custom_legend_anchor:
+            default_params['legend_bbox_to_anchor'] = None
 
     # Define colors
     color_map = default_params['colors']
@@ -173,7 +178,11 @@ def plot_pytrendy(df: pd.DataFrame, value_col: str, segments_enhanced: list[dict
     plt.setp(ax.get_xticklabels(), rotation=90, ha='right')
 
     # Optional: show grid lines for both
-    ax.grid(default_params['grid']['visible'], **{k: v for k, v in default_params['grid'].items() if k != 'visible'})
+    grid_params = default_params['grid']
+    if grid_params['visible']:
+        ax.grid(True, **{k: v for k, v in grid_params.items() if k != 'visible'})
+    else:
+        ax.grid(False, which='both')
 
     ax.set_title(default_params['title'], fontsize=20)
     ax.set_xlabel(default_params['xlabel'])

{pytrendy-1.4.0.dev1 → pytrendy-1.4.0.dev3}/pytrendy/post_processing/segments_refine/abrupt_shaving.py

@@ -134,6 +134,10 @@ def shave_abrupt_trends(df: pd.DataFrame, value_col: str, segments: list[dict],
             if segment['direction'] not in ['Up', 'Down'] or segment['trend_class'] != 'abrupt': 
                 continue
 
+            # Skip segments already padded in first pass; .get returns False when key absent (unpadded segments)
+            if second_pass and segment.get('padded', False):
+                continue
+
             abrupt_start = pd.to_datetime(segment['start'])
             abrupt_end = pd.to_datetime(segment['end'])
 

{pytrendy-1.4.0.dev1 → pytrendy-1.4.0.dev3}/pytrendy/process_signals.py

@@ -53,6 +53,7 @@ def process_signals(df: pd.DataFrame, value_col: str, method_params: dict, debug
 
     THRESHOLD_NOISE = 2.5 # Sensitivity to detecting noise (recommended 0-10)
     THRESHOLD_SMOOTH = 0.001 # Sensitivity to detecting trends as fraction of iqr
+    THRESHOLD_FLAT = 0.835 # Sensitivity to detecting flats as a fraction of min std (non-zero)
 
     # 1. Noise detection via SNR.
     # 1.1 Compute the SNR
@@ -174,31 +175,36 @@ def process_signals(df: pd.DataFrame, value_col: str, method_params: dict, debug
 
     # 3. Flat detection using rolling std of savgol filter.
     # with leading and trailing to cater for periods centred windows doesnt cover
+
+    # 3.1 Compute smoothed signal rolling std to be used by following logic
     df['smoothed'] = savgol_filter(df['value_cleaned'], window_length=WINDOW_SMOOTH, polyorder=1)
     df['smoothed_std'] = df['smoothed'].rolling(WINDOW_FLAT, center=True).std()
     df['smoothed_std_leading'] = df['smoothed'].iloc[::-1].rolling(window=WINDOW_FLAT).std().iloc[::-1]
     df['smoothed_std_trailing'] = df['smoothed'].rolling(WINDOW_FLAT).std()
     df['smoothed_std'] = df['smoothed_std'].fillna(df['smoothed_std_leading']).fillna(df['smoothed_std_trailing'])
 
+    # 3.2 Compute derivative early so flat detection can check both smoothness and motion.
+    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)
+
+    # 3.3 Compute Flat Flag using both std and deriv limits
     df['flat_flag'] = 0
     rolling_std = df['value_cleaned'].rolling(WINDOW_FLAT, center=True).std()
-    min_nonzero_std = rolling_std[rolling_std > 0].min()
-    df.loc[(df['smoothed_std'] <= min_nonzero_std) & (df['noise_flag'] == 0), 'flat_flag'] = 1 
+    nonzero_std = rolling_std[rolling_std > 0]
+    min_nonzero_std = nonzero_std.min() if not nonzero_std.empty else 0.0
+    derivative_near_zero = df['smoothed_deriv'].abs() <= derivative_limit
+    extremely_smooth = df['smoothed_std'] < (min_nonzero_std * THRESHOLD_FLAT)
+    df.loc[(df['smoothed_std'] <= min_nonzero_std) & (df['noise_flag'] == 0) & (derivative_near_zero | extremely_smooth), 'flat_flag'] = 1 
 
-    # 4. Detect up/down trend. Uses first derivates of savgol filter (like diff). 
-    # Savgol filter (rolling avg improvement). Caters for seasonality with tightness to day.
-    # Results in signal that's uptrend > 0, else down. As long as its not on a flat or noise.
+    # 4. Detect up/down trend.
     df['trend_flag'] = 0
     df.loc[df['flat_flag'] == 1, 'trend_flag'] = -2
     df.loc[df['noise_flag'] == 1, 'trend_flag'] = -3
 
-    # Important condition to establish non-trend segments to avoid detecting trends over
-    avoid_condition = (df['flat_flag'] == 0) # flat is always avoided
-    if method_params['avoid_noise']: # noise can be optionally avoided, up to the user
+    avoid_condition = (df['flat_flag'] == 0)
+    if method_params['avoid_noise']:
         avoid_condition &= (df['noise_flag'] == 0)
 
-    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) & avoid_condition, 'trend_flag'] = 1
     df.loc[(df['smoothed_deriv'] < -derivative_limit) & avoid_condition, 'trend_flag'] = -1