pytrendy 1.2.0.dev4__tar.gz → 1.2.0.dev5__tar.gz

{pytrendy-1.2.0.dev4 → pytrendy-1.2.0.dev5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytrendy
-Version: 1.2.0.dev4
+Version: 1.2.0.dev5
 Summary: Trend Detection in Python. Applicable for real-world industry use cases in time series.
 License: MIT License
          
@@ -24,21 +24,25 @@ License: MIT License
          OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
          SOFTWARE.
 License-File: LICENSE
+Keywords: trend detection,time series,time series analysis,signal processing,uptrend,downtrend,changepoint detection,trend classification,stock analysis,marketing analytics,causal inference
 Author: Russell Sammut Bonnici
 Author-email: r.sammutbonnici@gmail.com
 Maintainer: Russell Sammut Bonnici
 Maintainer-email: r.sammutbonnici@gmail.com
 Requires-Python: >=3.10
-Classifier: License :: Other/Proprietary License
-Classifier: Programming Language :: Python :: 3
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
 Provides-Extra: dev
 Provides-Extra: docs
-Requires-Dist: matplotlib
+Requires-Dist: matplotlib (==3.10.8)
 Requires-Dist: mkdocs (>=1.6,<2) ; extra == "docs"
 Requires-Dist: mkdocs-api-autonav (==0.4.0) ; extra == "docs"
 Requires-Dist: mkdocs-jupyterlite (==0.4.1) ; extra == "docs"
@@ -52,6 +56,8 @@ Requires-Dist: pytest-cov ; extra == "dev"
 Requires-Dist: pytest-mpl ; extra == "dev"
 Requires-Dist: pytest-timeout ; extra == "dev"
 Requires-Dist: scipy
+Project-URL: Documentation, https://russellsb.github.io/pytrendy/main/
+Project-URL: Homepage, https://russellsb.github.io/pytrendy/main/
 Project-URL: Repository, https://github.com/RussellSB/pytrendy
 Description-Content-Type: text/markdown
 
@@ -71,10 +77,18 @@ Description-Content-Type: text/markdown
   [![Downloads](https://static.pepy.tech/badge/pytrendy)](https://pepy.tech/project/pytrendy)
 </div>
 
-PyTrendy is a robust solution for identifying and analyzing trends in time series. Unlike other trend detection packages, it is robust to noisy & flat segments, and handles for gradual & abrupt trend cases with a high precision. It aims to be the best package for trend detection in python.
+PyTrendy is a robust solution for identifying and analysing trends in time series. Unlike other trend detection packages, it is robust to noisy and flat segments, and handles gradual and abrupt trend cases with high precision. It aims to be the best package for trend detection in Python.
 
 **Read more in the documentation:** [russellsb.github.io/pytrendy/main](https://russellsb.github.io/pytrendy/main/)
 
+## Why PyTrendy?
+
+Most time series tools give you either a "trend component" (via decomposition) or "changepoints" (the moments of shift). PyTrendy is built for **labelled segment analysis**, answering *what trends existed, how strong were they, and when did they start and end?*
+
+- **Beyond step changes** - `ruptures` is the gold standard for abrupt shifts, but it doesn't handle gradual slope changes (digital marketing, stocks, energy). PyTrendy detects both in a single run.
+- **The flat/noise problem** - closest peers (`pytrendseries`, `trendet`, `tstrends`) over-fit trends on flat or noisy periods. PyTrendy's signal-processing and post-processing logic ensures trends are only detected when they are precise and valid.
+- **Strategic value** - where dozens of time series interact, knowing how they align or confound at specific times is invaluable for experiment design.
+
 ## Features
 
 ![](https://raw.githubusercontent.com/RussellSB/pytrendy/refs/heads/develop/plots/Gradual-Cropped.gif)
@@ -118,8 +132,25 @@ time_index
 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 
+9               Flat  2025-06-18  2025-06-30    12      3.910534            8     NaN 
 -------------------------------------------------------------------------------
 ```
 
+Explore the strongest uptrends:
+```py
+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 |
+| 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.
+
+For the full per-segment metrics table, use `results.df`.
+
+For more examples on interpreting the results, see [Gradual trend fundamentals](https://russellsb.github.io/pytrendy/main/examples/fundamentals/gradual/).
+
 

{pytrendy-1.2.0.dev4 → pytrendy-1.2.0.dev5}/README.md

@@ -14,10 +14,18 @@
   [![Downloads](https://static.pepy.tech/badge/pytrendy)](https://pepy.tech/project/pytrendy)
 </div>
 
-PyTrendy is a robust solution for identifying and analyzing trends in time series. Unlike other trend detection packages, it is robust to noisy & flat segments, and handles for gradual & abrupt trend cases with a high precision. It aims to be the best package for trend detection in python.
+PyTrendy is a robust solution for identifying and analysing trends in time series. Unlike other trend detection packages, it is robust to noisy and flat segments, and handles gradual and abrupt trend cases with high precision. It aims to be the best package for trend detection in Python.
 
 **Read more in the documentation:** [russellsb.github.io/pytrendy/main](https://russellsb.github.io/pytrendy/main/)
 
+## Why PyTrendy?
+
+Most time series tools give you either a "trend component" (via decomposition) or "changepoints" (the moments of shift). PyTrendy is built for **labelled segment analysis**, answering *what trends existed, how strong were they, and when did they start and end?*
+
+- **Beyond step changes** - `ruptures` is the gold standard for abrupt shifts, but it doesn't handle gradual slope changes (digital marketing, stocks, energy). PyTrendy detects both in a single run.
+- **The flat/noise problem** - closest peers (`pytrendseries`, `trendet`, `tstrends`) over-fit trends on flat or noisy periods. PyTrendy's signal-processing and post-processing logic ensures trends are only detected when they are precise and valid.
+- **Strategic value** - where dozens of time series interact, knowing how they align or confound at specific times is invaluable for experiment design.
+
 ## Features
 
 ![](https://raw.githubusercontent.com/RussellSB/pytrendy/refs/heads/develop/plots/Gradual-Cropped.gif)
@@ -61,7 +69,24 @@ time_index
 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 
+9               Flat  2025-06-18  2025-06-30    12      3.910534            8     NaN 
 -------------------------------------------------------------------------------
 ```
 
+Explore the strongest uptrends:
+```py
+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 |
+| 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.
+
+For the full per-segment metrics table, use `results.df`.
+
+For more examples on interpreting the results, see [Gradual trend fundamentals](https://russellsb.github.io/pytrendy/main/examples/fundamentals/gradual/).
+

{pytrendy-1.2.0.dev4 → pytrendy-1.2.0.dev5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pytrendy"
-version = "1.2.0.dev4"
+version = "1.2.0.dev5"
 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" },
@@ -17,7 +17,32 @@ dependencies = [
     "numpy",
     "pandas",
     "scipy",
-    "matplotlib"
+    "matplotlib==3.10.8"
+]
+keywords = [
+    "trend detection",
+    "time series",
+    "time series analysis",
+    "signal processing",
+    "uptrend",
+    "downtrend",
+    "changepoint detection",
+    "trend classification",
+    "stock analysis",
+    "marketing analytics",
+    "causal inference"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Topic :: Office/Business :: Financial",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent"
 ]
 
 [project.optional-dependencies]
@@ -37,7 +62,9 @@ docs = [
 ]
 
 [project.urls]
-repository = "https://github.com/RussellSB/pytrendy"
+Homepage = "https://russellsb.github.io/pytrendy/main/"
+Documentation = "https://russellsb.github.io/pytrendy/main/"
+Repository = "https://github.com/RussellSB/pytrendy"
 
 [tool.setuptools.packages.find]
 where = ["."]

{pytrendy-1.2.0.dev4 → pytrendy-1.2.0.dev5}/pytrendy/__init__.py

@@ -8,7 +8,7 @@ apply classification heuristics, and access structured results for downstream an
 
 ---
 
-This package is organized into the following modules:
+This package is organised into the following modules:
 
 # 1. [detect_trends](detect_trends)
 
@@ -50,8 +50,8 @@ Designed for both exploratory workflows and programmatic integration, this modul
 
 # 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.  
+The `post_processing` module provides utilities for refining, classifying, and analysing trend segments.
+It transforms raw detections into interpretable, ranked structures by adjusting boundaries, labelling temporal behaviour, 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)
@@ -72,7 +72,7 @@ This module ensures that the output is analytically robust and ready for downstr
 
 ## 3.3 [segments_analyse](post_processing/segments_analyse)
 
-- Computes metrics for each segment, comparing pretreatment vs post-treatment behavior.
+- Computes metrics for each segment, comparing pretreatment vs post-treatment behaviour.
 - Includes absolute and percent change, duration, and cumulative movement.
 - Calculates signal-to-noise ratio (SNR) and assigns a change rank.
 - Enables filtering and prioritization of significant trends.

{pytrendy-1.2.0.dev4 → pytrendy-1.2.0.dev5}/pytrendy/detect_trends.py

@@ -33,7 +33,7 @@ def detect_trends(df: pd.DataFrame, date_col: str, value_col: str, plot=True, me
         date_col (str):
             Name of the column representing timestamps. This column is converted to datetime and set as the index.
         value_col (str):
-            Name of the column containing the primary signal to analyze for trend detection.
+            Name of the column containing the primary signal to analyse for trend detection.
         plot (bool, optional):
             If `True`, generates a matplotlib plot showing the detected trend segments over the original signal.
             Defaults to `True`.

{pytrendy-1.2.0.dev4 → pytrendy-1.2.0.dev5}/pytrendy/io/plot_pytrendy.py

@@ -27,7 +27,7 @@ def plot_pytrendy(df: pd.DataFrame, value_col: str, segments_enhanced: list[dict
             The figure object containing the plot. Can be displayed with `plt.show()` or saved.
     """
     
-    # Define colors
+    # Define colours
     color_map = {
         'Up': 'lightgreen',
         'Down': 'lightcoral',

{pytrendy-1.2.0.dev4 → pytrendy-1.2.0.dev5}/pytrendy/io/results_pytrendy.py

@@ -7,7 +7,7 @@ import math
 
 class PyTrendyResults: 
     """
-    Wrapper class for accessing and analyzing detected trend segments.
+    Wrapper class for accessing and analysing detected trend segments.
 
     This class provides utilities for summarizing, filtering, and exporting trend segments
     detected by the `detect_trends` pipeline. It encapsulates both raw segment data and

{pytrendy-1.2.0.dev4 → pytrendy-1.2.0.dev5}/pytrendy/post_processing/__init__.py

@@ -20,7 +20,7 @@ Applies minimum length constraints to ensure meaningful segments are retained:
 
 ## 2. Segment Refinement Package
 
-The segment refinement functionality is organized under the `segments_refine` package:
+The segment refinement functionality is organised under the `segments_refine` package:
 
 ### [segments_refine](segments_refine)
 Main orchestration module with `refine_segments()` function that coordinates the full post-processing pipeline.
@@ -28,7 +28,7 @@ Main orchestration module with `refine_segments()` function that coordinates the
 The `segments_refine` package contains focused sub-modules:
 
 ### [segments_refine.update_neighbours](segments_refine/update_neighbours)
-Helper functions for adjusting segment boundaries when neighboring segments are updated:
+Helper functions for adjusting segment boundaries when neighbouring segments are updated:
 - `update_prev_segment`: Adjusts the end of the previous segment
 - `update_next_segment`: Adjusts the start of the next segment
 
@@ -50,7 +50,7 @@ Helper functions for adjusting segment boundaries when neighboring segments are
 
 
 ## 3. [segments_analyse](segments_analyse)
-Adds quantitative descriptors to each segment, comparing pretreatment vs post-treatment behavior.
+Adds quantitative descriptors to each segment, comparing pretreatment vs post-treatment behaviour.
 
 Metrics include:
 

{pytrendy-1.2.0.dev4 → pytrendy-1.2.0.dev5}/pytrendy/post_processing/segments_analyse.py

@@ -7,7 +7,7 @@ def analyse_segments(df: pd.DataFrame, value_col: str, segments: list[dict]) ->
     """
     Enhances trend segments with quantitative metrics and rankings.
 
-    This function compares signal behavior before and after each trend period to characterize
+    This function compares signal behaviour before and after each trend period to characterize
     the magnitude and clarity of change. 
 
     It computes descriptors that reflect how the signal
@@ -32,7 +32,7 @@ def analyse_segments(df: pd.DataFrame, value_col: str, segments: list[dict]) ->
         df (pd.DataFrame): 
             Time series DataFrame containing signal, noise, and smoothed columns.
         value_col (str): 
-            Name of the column containing the signal to analyze.
+            Name of the column containing the signal to analyse.
         segments (list): 
             List of segment dictionaries with `'start'`, `'end'`, and `'direction'`.
 

{pytrendy-1.2.0.dev4 → pytrendy-1.2.0.dev5}/pytrendy/post_processing/segments_refine/artifact_cleanup.py

@@ -16,7 +16,7 @@ def clean_artifacts(df: pd.DataFrame, value_col: str, segments_refined: list[dic
 
     Args:
         segments_refined (list): List of segment dictionaries potentially with artifacts from post-processing.
-        method_params (dict): Optional parameters for cleanup behavior. Supported keys:
+        method_params (dict): Optional parameters for cleanup behaviour. Supported keys:
 
             - **abrupt_padding** (`int`): Padding window in days used by abrupt refinement; included for pipeline consistency. Defaults to `0`.
             - **avoid_noise** (`bool`): Whether to avoid noisy segments in trend detection. Defaults to `True`.

{pytrendy-1.2.0.dev4 → pytrendy-1.2.0.dev5}/pytrendy/post_processing/segments_refine/update_neighbours.py

@@ -1,6 +1,6 @@
 """**Boundary Adjustment Utilities**
 
-Functions for adjusting segment boundaries when neighboring segments are updated.
+Functions for adjusting segment boundaries when neighbouring segments are updated.
 """
 
 import pandas as pd

{pytrendy-1.2.0.dev4 → pytrendy-1.2.0.dev5}/pytrendy/process_signals.py

@@ -54,7 +54,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
 
-    # 1. Noise detection via SNR. 
+    # 1. Noise detection via SNR.
     # 1.1 Compute the SNR
     df['signal'] = df[value_col].rolling(window=WINDOW_NOISE, center=True, min_periods=1).mean()
     df['noise'] = df[value_col] - df['signal']
@@ -63,13 +63,22 @@ def process_signals(df: pd.DataFrame, value_col: str, method_params: dict, debug
     # 1.2 Define noise flag when SNR & not all zero
     df['noise_flag'] = 0
     df.loc[(df['snr'] <= THRESHOLD_NOISE), 'noise_flag'] = 1
-    
-    # 1.3 Double check & refresh noise flag. Distinguish noise from abrupt change.
+
+    # Skip noise detection when user opts out.
+    if not method_params['avoid_noise']:
+        df['noise_flag'] = 0
+
+    # Suppress false noise on zero-baseline leading edge: the centred rolling mean
+    # sees the abrupt jump before the value moves, producing signal≈noise. When
+    # value=0 and previous=0, we are inside a run of zeros — not noise.
+    df.loc[(df[value_col] == 0) & (df[value_col].shift(1) == 0) & (df['signal'] != 0), 'noise_flag'] = 0
+
+    # 1.4 Double check & refresh noise flag. Distinguish noise from abrupt change.
     df['noise_flag_diff'] = df['noise_flag'].diff()
     noise_starts = df.loc[df['noise_flag_diff'] == 1].index
     noise_ends = df.loc[df['noise_flag_diff'] == -1].index
-    
-    # 1.3.1 Construct noise segments list based on flag_diff
+
+    # 1.4.1 Construct noise segments list based on flag_diff
     noise_segments = []
     for noise_start in noise_starts: # Loops from first start onwards
         after_ends = [end for end in noise_ends if end > noise_start]
@@ -86,8 +95,8 @@ def process_signals(df: pd.DataFrame, value_col: str, method_params: dict, debug
             noise_start = max(noise_end - pd.Timedelta(days=1), df.index[0])
             noise_segments.insert(0, dict(start=noise_start, end=noise_end))
 
-    # 1.3.2 Group noise segments if within a close enough distance of each other
-    if len(noise_segments) <= 1: 
+    # 1.4.2 Group noise segments if within a close enough distance of each other
+    if len(noise_segments) <= 1:
         noise_segments_grouped = noise_segments
     else: # only try group logic if > 1 segments to group
         noise_segments_grouped = []
@@ -103,13 +112,13 @@ def process_signals(df: pd.DataFrame, value_col: str, method_params: dict, debug
                     noise_segments_grouped.append(seg)
             prev_seg = seg.copy()
 
-    # 1.3.3 Update noise flag to larger groupings, so segments continuous to then refine
+    # 1.4.3 Update noise flag to larger groupings, so segments continuous to then refine
     if noise_segments_grouped != noise_segments:
         df.loc[:, 'noise_flag'] = 0
         for seg in noise_segments_grouped:
             df.loc[seg['start']:seg['end'], 'noise_flag'] = 1
-        
-    # 1.3.4 Refine the noise segments early
+
+    # 1.4.4 Refine the noise segments early
     for segment in noise_segments_grouped:
 
         width = (pd.to_datetime(segment['end']) - pd.to_datetime(segment['start'])).days
@@ -137,7 +146,7 @@ def process_signals(df: pd.DataFrame, value_col: str, method_params: dict, debug
         ts_max = df.loc[start:end, value_col].abs().idxmax()
 
         # Define center as 30% - 70% of window.
-        center_start = (start + (0.3 * width_padded)).floor('D') 
+        center_start = (start + (0.3 * width_padded)).floor('D')
         center_end   = (start + (0.7 * width_padded)).floor('D')
         is_central = ts_max >= center_start and ts_max <= center_end
 
@@ -146,7 +155,7 @@ def process_signals(df: pd.DataFrame, value_col: str, method_params: dict, debug
             df_left = df.loc[:ts_max+pd.Timedelta(days=1)].copy()
             df_left['diff'] = df_left[value_col].diff(periods=-1).shift(-2)
             lowers = df_left.loc[df_left['diff'] > 0]
-            if len(lowers) > 0: 
+            if len(lowers) > 0:
                 noise_start = lowers.index[-1]
                 df.loc[start:noise_start, 'noise_flag'] = 0
 
@@ -164,7 +173,7 @@ def process_signals(df: pd.DataFrame, value_col: str, method_params: dict, debug
     df['value_cleaned'] = df['value_cleaned'].ffill().bfill()
 
     # 3. Flat detection using rolling std of savgol filter.
-    # with leading and trailing to cater for periods centered windows doesnt cover
+    # with leading and trailing to cater for periods centred windows doesnt cover
     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]