pytrendy 1.4.0.dev5__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.dev5 → pytrendy-2.0.0}/PKG-INFO +20 -17
  2. {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/README.md +15 -15
  3. {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pyproject.toml +13 -5
  4. {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/detect_trends.py +29 -8
  5. pytrendy-2.0.0/pytrendy/io/plot_pytrendy.py +643 -0
  6. pytrendy-1.4.0.dev5/pytrendy/io/prepare_index.py → pytrendy-2.0.0/pytrendy/io/prep_index.py +1 -1
  7. pytrendy-2.0.0/pytrendy/io/prep_signal_params.py +204 -0
  8. {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/io/results_pytrendy.py +17 -26
  9. {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/post_processing/segments_analyse.py +11 -10
  10. {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/post_processing/segments_get.py +14 -6
  11. {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/post_processing/segments_refine/__init__.py +14 -9
  12. {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/post_processing/segments_refine/artifact_cleanup.py +9 -10
  13. {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/post_processing/segments_refine/segment_grouping.py +6 -11
  14. {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/process_signals.py +32 -29
  15. pytrendy-1.4.0.dev5/pytrendy/io/plot_pytrendy.py +0 -313
  16. {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/LICENSE +0 -0
  17. {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/__init__.py +0 -0
  18. {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/io/__init__.py +0 -0
  19. {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/io/data/classes_signals.csv +0 -0
  20. {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/io/data/series_synthetic.csv +0 -0
  21. {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/io/data_loader.py +0 -0
  22. {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/post_processing/__init__.py +0 -0
  23. {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/post_processing/segments_refine/abrupt_shaving.py +0 -0
  24. {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/post_processing/segments_refine/gradual_expand_contract.py +0 -0
  25. {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/post_processing/segments_refine/trend_classify.py +0 -0
  26. {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/post_processing/segments_refine/update_neighbours.py +0 -0
  27. {pytrendy-1.4.0.dev5 → 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.dev5
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.dev5"
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,7 +8,7 @@ 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 prepare_index
11
+ from .io import prep_index, prep_signal_params
12
12
 
13
13
 
14
14
  def detect_trends(df: pd.DataFrame,
@@ -16,6 +16,7 @@ def detect_trends(df: pd.DataFrame,
16
16
  date_col: str|None=None,
17
17
  plot: bool=True,
18
18
  method_params: dict|None=None,
19
+ signal_params: dict|None=None,
19
20
  plot_params: dict|None=None,
20
21
  debug: bool=False
21
22
  ) -> PyTrendyResults:
@@ -51,6 +52,22 @@ def detect_trends(df: pd.DataFrame,
51
52
  - **abrupt_padding** (`int`): Number of days to pad after abrupt transitions. Defaults to `0`.
52
53
  - **gradual_padding** (`int`): Number of days to pad after gradual trend ends. Defaults to `0`.
53
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.
54
71
  plot_params (dict, optional):
55
72
  Optional dict to customise plot appearance. Only used when `plot` is `True`. Supported keys:
56
73
 
@@ -73,7 +90,7 @@ def detect_trends(df: pd.DataFrame,
73
90
  Use this object to access segment statistics, rankings, and export utilities.
74
91
  """
75
92
  # Reject the deprecated positional order detect_trends(df, date_col, value_col).
76
- if date_col is not None and prepare_index.is_legacy_positional_order(df, value_col, date_col):
93
+ if date_col is not None and prep_index.is_legacy_positional_order(df, value_col, date_col):
77
94
  raise TypeError(
78
95
  "detect_trends received arguments in the deprecated (date_col, value_col) order. "
79
96
  "Pass value_col first: detect_trends(df, value_col, date_col=...)."
@@ -81,7 +98,7 @@ def detect_trends(df: pd.DataFrame,
81
98
 
82
99
  # Stage the DataFrame on an internal integer index, keeping the external index
83
100
  # values and a lookup so boundaries can be remapped back later.
84
- df, external_index, index_lookup, index_type = prepare_index.prepare_index(df, date_col, value_col)
101
+ df, external_index, index_lookup, index_type = prep_index.prep_index(df, date_col, value_col)
85
102
 
86
103
  if method_params is None:
87
104
  method_params = {} # Avoid mutable default argument by accepting None and constructing a new dict here
@@ -102,18 +119,22 @@ def detect_trends(df: pd.DataFrame,
102
119
  'avoid_noise': method_params.get('avoid_noise', True),
103
120
  }
104
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
+
105
126
  # Core 5-step pipeline
106
- df = process_signals(df, value_col, method_params, debug)
107
- segments = get_segments(df)
108
- 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)
109
130
  segments = analyse_segments(df, value_col, segments)
110
131
 
111
132
  # Translate internal segment boundaries back to the user's external index values.
112
- segments = prepare_index.remap_boundaries(segments, index_lookup)
133
+ segments = prep_index.remap_boundaries(segments, index_lookup)
113
134
 
114
135
  if plot:
115
136
  # Restore the external index for plotting before rendering the segments.
116
- plot_df = prepare_index.prepare_plot_frame(df, date_col, external_index, index_type)
137
+ plot_df = prep_index.prepare_plot_frame(df, date_col, external_index, index_type)
117
138
  plot_pytrendy(df=plot_df, value_col=value_col, segments_enhanced=segments, index_type=index_type, plot_params=plot_params)
118
139
 
119
140
  results = PyTrendyResults(segments=segments, index_type=index_type)