pytrendy 1.4.0.dev4__tar.gz → 2.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/PKG-INFO +20 -17
  2. {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/README.md +15 -15
  3. {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pyproject.toml +13 -5
  4. {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/detect_trends.py +58 -16
  5. pytrendy-2.0.0/pytrendy/io/plot_pytrendy.py +643 -0
  6. pytrendy-2.0.0/pytrendy/io/prep_index.py +216 -0
  7. pytrendy-2.0.0/pytrendy/io/prep_signal_params.py +204 -0
  8. {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/io/results_pytrendy.py +30 -17
  9. {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/post_processing/segments_analyse.py +11 -10
  10. {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/post_processing/segments_get.py +23 -15
  11. {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/post_processing/segments_refine/__init__.py +14 -9
  12. {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/post_processing/segments_refine/abrupt_shaving.py +21 -23
  13. {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/post_processing/segments_refine/artifact_cleanup.py +76 -78
  14. {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/post_processing/segments_refine/gradual_expand_contract.py +23 -25
  15. {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/post_processing/segments_refine/segment_grouping.py +7 -12
  16. {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/post_processing/segments_refine/trend_classify.py +3 -3
  17. {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/post_processing/segments_refine/update_neighbours.py +23 -21
  18. {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/process_signals.py +50 -43
  19. pytrendy-1.4.0.dev4/pytrendy/io/plot_pytrendy.py +0 -204
  20. {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/LICENSE +0 -0
  21. {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/__init__.py +0 -0
  22. {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/io/__init__.py +0 -0
  23. {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/io/data/classes_signals.csv +0 -0
  24. {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/io/data/series_synthetic.csv +0 -0
  25. {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/io/data_loader.py +0 -0
  26. {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/post_processing/__init__.py +0 -0
  27. {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/simpledtw.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pytrendy
3
- Version: 1.4.0.dev4
3
+ Version: 2.0.0
4
4
  Summary: Trend Detection in Python. Applicable for real-world industry use cases in time series.
5
5
  License: MIT License
6
6
 
@@ -42,7 +42,8 @@ Classifier: Intended Audience :: Developers
42
42
  Classifier: Operating System :: OS Independent
43
43
  Provides-Extra: dev
44
44
  Provides-Extra: docs
45
- Requires-Dist: matplotlib (==3.10.8)
45
+ Requires-Dist: matplotlib (==3.11.2) ; (python_version >= "3.11") and (extra == "dev")
46
+ Requires-Dist: matplotlib (>=3.10)
46
47
  Requires-Dist: mkdocs (>=1.6,<2) ; extra == "docs"
47
48
  Requires-Dist: mkdocs-api-autonav (==0.4.0) ; extra == "docs"
48
49
  Requires-Dist: mkdocs-jupyterlite (==0.4.1) ; extra == "docs"
@@ -51,10 +52,12 @@ Requires-Dist: mkdocstrings (>=0.28.3,<1) ; extra == "docs"
51
52
  Requires-Dist: mkdocstrings-python (>=1.16,<2) ; extra == "docs"
52
53
  Requires-Dist: numpy
53
54
  Requires-Dist: pandas
55
+ Requires-Dist: pymdown-extensions (<12.2) ; extra == "docs"
54
56
  Requires-Dist: pytest ; extra == "dev"
55
57
  Requires-Dist: pytest-cov ; extra == "dev"
56
58
  Requires-Dist: pytest-mpl ; extra == "dev"
57
59
  Requires-Dist: pytest-timeout ; extra == "dev"
60
+ Requires-Dist: ruff ; extra == "dev"
58
61
  Requires-Dist: scipy
59
62
  Project-URL: Documentation, https://russellsb.github.io/pytrendy/main/
60
63
  Project-URL: Homepage, https://russellsb.github.io/pytrendy/main/
@@ -125,16 +128,16 @@ The best detected trend is Down between dates 2025-05-09 - 2025-06-17
125
128
 
126
129
  Full Results:
127
130
  -------------------------------------------------------------------------------
128
- direction start end days total_change change_rank trend_class
129
- time_index
130
- 1 Up 2025-01-02 2025-01-24 22 14.013348 5 gradual
131
- 2 Down 2025-01-25 2025-02-05 11 -13.564214 6 gradual
132
- 3 Flat 2025-02-06 2025-02-09 3 -1.168831 8 NaN
133
- 4 Up 2025-02-10 2025-03-17 35 26.190476 3 gradual
134
- 5 Down 2025-03-18 2025-04-01 14 -22.721861 4 gradual
135
- 6 Up 2025-04-02 2025-05-08 36 72.611833 2 gradual
136
- 7 Down 2025-05-09 2025-06-17 39 -73.253968 1 gradual
137
- 8 Flat 2025-06-18 2025-06-30 12 3.910534 7 NaN
131
+ direction start end steps total_change change_rank trend_class
132
+ time_index
133
+ 1 Up 2025-01-02 2025-01-24 22 14.013348 5 gradual
134
+ 2 Down 2025-01-25 2025-02-05 11 -13.564214 6 gradual
135
+ 3 Flat 2025-02-06 2025-02-09 3 -1.168831 8 NaN
136
+ 4 Up 2025-02-10 2025-03-17 35 26.190476 3 gradual
137
+ 5 Down 2025-03-18 2025-04-01 14 -22.721861 4 gradual
138
+ 6 Up 2025-04-02 2025-05-08 36 72.611833 2 gradual
139
+ 7 Down 2025-05-09 2025-06-17 39 -73.253968 1 gradual
140
+ 8 Flat 2025-06-18 2025-06-30 12 3.910534 7 NaN
138
141
  -------------------------------------------------------------------------------
139
142
  ```
140
143
 
@@ -143,11 +146,11 @@ Explore the strongest uptrends:
143
146
  results.filter_segments(direction='Up', sort_by='change_rank')[:3]
144
147
  ```
145
148
 
146
- | time_index | direction | start | end | trend_class | change | pct_change | days | total_change | SNR | change_rank |
147
- |---|---|---|---|---|---|---|---|---|---|---|
148
- | 7 | Up | 2025-04-02 | 2025-05-08 | gradual | 72.61 | 367.50% | 36 | 72.61 | 21.70 | 2 |
149
- | 4 | Up | 2025-02-10 | 2025-03-17 | gradual | 26.19 | 179.93% | 35 | 26.19 | 18.61 | 3 |
150
- | 1 | Up | 2025-01-02 | 2025-01-24 | gradual | 14.01 | 104.41% | 22 | 14.01 | 22.21 | 5 |
149
+ | time_index | direction | start | end | trend_class | pct_change | steps | total_change | SNR | change_rank |
150
+ |---|---|---|---|---|---|---|---|---|---|
151
+ | 7 | Up | 2025-04-02 | 2025-05-08 | gradual | 367.50% | 36 | 72.61 | 21.70 | 2 |
152
+ | 4 | Up | 2025-02-10 | 2025-03-17 | gradual | 179.93% | 35 | 26.19 | 18.61 | 3 |
153
+ | 1 | Up | 2025-01-02 | 2025-01-24 | gradual | 104.41% | 22 | 14.01 | 22.21 | 5 |
151
154
 
152
155
  `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.
153
156
 
@@ -62,16 +62,16 @@ The best detected trend is Down between dates 2025-05-09 - 2025-06-17
62
62
 
63
63
  Full Results:
64
64
  -------------------------------------------------------------------------------
65
- direction start end days total_change change_rank trend_class
66
- time_index
67
- 1 Up 2025-01-02 2025-01-24 22 14.013348 5 gradual
68
- 2 Down 2025-01-25 2025-02-05 11 -13.564214 6 gradual
69
- 3 Flat 2025-02-06 2025-02-09 3 -1.168831 8 NaN
70
- 4 Up 2025-02-10 2025-03-17 35 26.190476 3 gradual
71
- 5 Down 2025-03-18 2025-04-01 14 -22.721861 4 gradual
72
- 6 Up 2025-04-02 2025-05-08 36 72.611833 2 gradual
73
- 7 Down 2025-05-09 2025-06-17 39 -73.253968 1 gradual
74
- 8 Flat 2025-06-18 2025-06-30 12 3.910534 7 NaN
65
+ direction start end steps total_change change_rank trend_class
66
+ time_index
67
+ 1 Up 2025-01-02 2025-01-24 22 14.013348 5 gradual
68
+ 2 Down 2025-01-25 2025-02-05 11 -13.564214 6 gradual
69
+ 3 Flat 2025-02-06 2025-02-09 3 -1.168831 8 NaN
70
+ 4 Up 2025-02-10 2025-03-17 35 26.190476 3 gradual
71
+ 5 Down 2025-03-18 2025-04-01 14 -22.721861 4 gradual
72
+ 6 Up 2025-04-02 2025-05-08 36 72.611833 2 gradual
73
+ 7 Down 2025-05-09 2025-06-17 39 -73.253968 1 gradual
74
+ 8 Flat 2025-06-18 2025-06-30 12 3.910534 7 NaN
75
75
  -------------------------------------------------------------------------------
76
76
  ```
77
77
 
@@ -80,11 +80,11 @@ Explore the strongest uptrends:
80
80
  results.filter_segments(direction='Up', sort_by='change_rank')[:3]
81
81
  ```
82
82
 
83
- | time_index | direction | start | end | trend_class | change | pct_change | days | total_change | SNR | change_rank |
84
- |---|---|---|---|---|---|---|---|---|---|---|
85
- | 7 | Up | 2025-04-02 | 2025-05-08 | gradual | 72.61 | 367.50% | 36 | 72.61 | 21.70 | 2 |
86
- | 4 | Up | 2025-02-10 | 2025-03-17 | gradual | 26.19 | 179.93% | 35 | 26.19 | 18.61 | 3 |
87
- | 1 | Up | 2025-01-02 | 2025-01-24 | gradual | 14.01 | 104.41% | 22 | 14.01 | 22.21 | 5 |
83
+ | time_index | direction | start | end | trend_class | pct_change | steps | total_change | SNR | change_rank |
84
+ |---|---|---|---|---|---|---|---|---|---|
85
+ | 7 | Up | 2025-04-02 | 2025-05-08 | gradual | 367.50% | 36 | 72.61 | 21.70 | 2 |
86
+ | 4 | Up | 2025-02-10 | 2025-03-17 | gradual | 179.93% | 35 | 26.19 | 18.61 | 3 |
87
+ | 1 | Up | 2025-01-02 | 2025-01-24 | gradual | 104.41% | 22 | 14.01 | 22.21 | 5 |
88
88
 
89
89
  `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.
90
90
 
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "pytrendy"
3
- version = "1.4.0.dev4"
3
+ version = "2.0.0"
4
4
  description = "Trend Detection in Python. Applicable for real-world industry use cases in time series."
5
5
  authors = [
6
6
  { name = "Russell Sammut Bonnici", email = "r.sammutbonnici@gmail.com" },
@@ -17,7 +17,7 @@ dependencies = [
17
17
  "numpy",
18
18
  "pandas",
19
19
  "scipy",
20
- "matplotlib==3.10.8"
20
+ "matplotlib>=3.10"
21
21
  ]
22
22
  keywords = [
23
23
  "trend detection",
@@ -47,10 +47,14 @@ classifiers = [
47
47
 
48
48
  [project.optional-dependencies]
49
49
  dev = [
50
+ # Pinned for deterministic pytest-mpl baselines. Development needs Python
51
+ # >=3.11; the marker keeps Poetry's solver valid over the declared >=3.10 range.
52
+ "matplotlib==3.11.2; python_version >= '3.11'",
50
53
  "pytest",
51
54
  "pytest-cov",
52
55
  "pytest-mpl",
53
- "pytest-timeout"
56
+ "pytest-timeout",
57
+ "ruff"
54
58
  ]
55
59
  docs = [
56
60
  "mkdocs>=1.6,<2",
@@ -58,7 +62,8 @@ docs = [
58
62
  "mkdocs-api-autonav==0.4.0",
59
63
  "mkdocstrings>=0.28.3,<1",
60
64
  "mkdocstrings-python>=1.16,<2",
61
- "mkdocs-jupyterlite==0.4.1"
65
+ "mkdocs-jupyterlite==0.4.1",
66
+ "pymdown-extensions<12.2"
62
67
  ]
63
68
 
64
69
  [project.urls]
@@ -76,4 +81,7 @@ timeout = 15
76
81
  markers = [
77
82
  "core: essential tests that must pass for core functionality",
78
83
  "plot: tests for visualization/plotting functionality"
79
- ]
84
+ ]
85
+
86
+ [tool.ruff]
87
+ exclude = ["**/*"]
@@ -8,8 +8,18 @@ from .post_processing.segments_refine import refine_segments
8
8
  from .post_processing.segments_analyse import analyse_segments
9
9
  from .io.plot_pytrendy import plot_pytrendy
10
10
  from .io.results_pytrendy import PyTrendyResults
11
+ from .io import prep_index, prep_signal_params
11
12
 
12
- def detect_trends(df: pd.DataFrame, date_col: str, value_col: str, plot=True, method_params: dict=None, plot_params: dict=None, debug: bool=False ) -> PyTrendyResults:
13
+
14
+ def detect_trends(df: pd.DataFrame,
15
+ value_col: str,
16
+ date_col: str|None=None,
17
+ plot: bool=True,
18
+ method_params: dict|None=None,
19
+ signal_params: dict|None=None,
20
+ plot_params: dict|None=None,
21
+ debug: bool=False
22
+ ) -> PyTrendyResults:
13
23
  """
14
24
  This is the main function that runs trend detection end-to-end.
15
25
 
@@ -29,20 +39,35 @@ def detect_trends(df: pd.DataFrame, date_col: str, value_col: str, plot=True, me
29
39
  Args:
30
40
  df (pd.DataFrame):
31
41
  Input time series data containing at least the specified `date_col` and `value_col`.
32
- The `date_col` must contain datetime-like values (daily frequency recommended).
33
- date_col (str):
34
- Name of the column representing timestamps. This column is converted to datetime and set as the index.
35
42
  value_col (str):
36
43
  Name of the column containing the primary signal to analyse for trend detection.
44
+ date_col (str|None):
45
+ Column giving the x-axis position of each observation. Typically dates, but any unique, sortable values (integer, float, or string) are supported. If not specified, the DataFrame's index is used.
37
46
  plot (bool, optional):
38
47
  If `True`, generates a matplotlib plot showing the detected trend segments over the original signal.
39
48
  Defaults to `True`.
40
49
  method_params (dict, optional):
41
50
  Optional parameters to customize detection heuristics. Supported keys:
42
51
 
43
- - **abrupt_padding** (`int`): Number of days to pad around abrupt transitions. Defaults to `0`.
52
+ - **abrupt_padding** (`int`): Number of days to pad after abrupt transitions. Defaults to `0`.
44
53
  - **gradual_padding** (`int`): Number of days to pad after gradual trend ends. Defaults to `0`.
45
54
  - **avoid_noise** (`bool`): Whether to avoid noisy segments in trend detection. Defaults to `True`.
55
+ signal_params (dict, optional):
56
+ Optional parameters to customize the signal-processing constants. Supported keys (independent from `method_params`):
57
+
58
+ - **window_smooth** (`int`): Savitzky-Golay smoothing window, in points. When omitted it is inferred from the index cadence (193/97/49/15/9/25/9/5 for 15min/30min/hourly/daily/weekly/monthly/quarterly/yearly, and 15 for anything unmapped). An explicit value always wins. The resolved window is clamped to the series length.
59
+ - **smooth_factor** (`float`): Fraction of `window_smooth` spanned by the derived `window_flat` window. Raising it smooths the flat baseline (fewer flat flags); lowering it responds more locally. Defaults to `0.5`.
60
+ - **noise_factor** (`float`): Fraction of `window_smooth` spanned by the derived `window_noise` window. Raising it smooths the noise (SNR) estimate (fewer noise flags); lowering it responds more locally. Defaults to `0.5`.
61
+ - **grouping_distance** (`int`): Maximum gap, in steps, for grouping nearby segments. Defaults to `7`.
62
+ - **min_trend_length** (`int`): Minimum length, in steps, for an Up/Down segment to be retained. Defaults to `3`.
63
+ - **min_flat_noise_length** (`int`): Minimum length, in steps, for a Flat/Noise segment to be retained. Defaults to `1`.
64
+ - **threshold_noise** (`float`): SNR threshold (dB) below which a region is classified as noise. Defaults to `2.5`.
65
+ - **threshold_smooth** (`float`): Derivative threshold, as a fraction of the signal IQR, below which motion counts as flat. Defaults to `0.001`.
66
+ - **threshold_flat** (`float`): Flat sensitivity, as a fraction of the minimum non-zero rolling std. Defaults to `0.835`.
67
+
68
+ This surface is independent from `method_params`, which controls the padding and noise heuristics instead.
69
+ Window sizes are in points and minimum lengths in steps; at non-daily spacing a given count spans a
70
+ different real-time duration.
46
71
  plot_params (dict, optional):
47
72
  Optional dict to customise plot appearance. Only used when `plot` is `True`. Supported keys:
48
73
 
@@ -64,11 +89,17 @@ def detect_trends(df: pd.DataFrame, date_col: str, value_col: str, plot=True, me
64
89
  An object encapsulating the detected segments and associated metadata.
65
90
  Use this object to access segment statistics, rankings, and export utilities.
66
91
  """
67
- df = df.copy()
68
- df[date_col] = pd.to_datetime(df[date_col])
69
- df.set_index(date_col, inplace=True)
70
- df = df[[value_col]]
71
-
92
+ # Reject the deprecated positional order detect_trends(df, date_col, value_col).
93
+ if date_col is not None and prep_index.is_legacy_positional_order(df, value_col, date_col):
94
+ raise TypeError(
95
+ "detect_trends received arguments in the deprecated (date_col, value_col) order. "
96
+ "Pass value_col first: detect_trends(df, value_col, date_col=...)."
97
+ )
98
+
99
+ # Stage the DataFrame on an internal integer index, keeping the external index
100
+ # values and a lookup so boundaries can be remapped back later.
101
+ df, external_index, index_lookup, index_type = prep_index.prep_index(df, date_col, value_col)
102
+
72
103
  if method_params is None:
73
104
  method_params = {} # Avoid mutable default argument by accepting None and constructing a new dict here
74
105
 
@@ -88,12 +119,23 @@ def detect_trends(df: pd.DataFrame, date_col: str, value_col: str, plot=True, me
88
119
  'avoid_noise': method_params.get('avoid_noise', True),
89
120
  }
90
121
 
122
+ # Configures signal-processing constants. The external index lets the smoothing window default to a
123
+ # cadence-aware value; unknown keys are accepted and forwarded (validation is deliberately out of scope for now).
124
+ signal_params = prep_signal_params.prep_signal_params(signal_params, index=external_index)
125
+
91
126
  # Core 5-step pipeline
92
- df = process_signals(df, value_col, method_params, debug)
93
- segments = get_segments(df)
94
- segments = refine_segments(df, value_col, segments, method_params)
127
+ df = process_signals(df, value_col, method_params, signal_params, debug)
128
+ segments = get_segments(df, signal_params)
129
+ segments = refine_segments(df, value_col, segments, method_params, signal_params)
95
130
  segments = analyse_segments(df, value_col, segments)
96
- if plot: plot_pytrendy(df, value_col, segments, plot_params=plot_params)
97
131
 
98
- results = PyTrendyResults(segments)
99
- return results
132
+ # Translate internal segment boundaries back to the user's external index values.
133
+ segments = prep_index.remap_boundaries(segments, index_lookup)
134
+
135
+ if plot:
136
+ # Restore the external index for plotting before rendering the segments.
137
+ plot_df = prep_index.prepare_plot_frame(df, date_col, external_index, index_type)
138
+ plot_pytrendy(df=plot_df, value_col=value_col, segments_enhanced=segments, index_type=index_type, plot_params=plot_params)
139
+
140
+ results = PyTrendyResults(segments=segments, index_type=index_type)
141
+ return results