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.
- {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/PKG-INFO +20 -17
- {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/README.md +15 -15
- {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pyproject.toml +13 -5
- {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/detect_trends.py +58 -16
- pytrendy-2.0.0/pytrendy/io/plot_pytrendy.py +643 -0
- pytrendy-2.0.0/pytrendy/io/prep_index.py +216 -0
- pytrendy-2.0.0/pytrendy/io/prep_signal_params.py +204 -0
- {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/io/results_pytrendy.py +30 -17
- {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/post_processing/segments_analyse.py +11 -10
- {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/post_processing/segments_get.py +23 -15
- {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/post_processing/segments_refine/__init__.py +14 -9
- {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/post_processing/segments_refine/abrupt_shaving.py +21 -23
- {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/post_processing/segments_refine/artifact_cleanup.py +76 -78
- {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/post_processing/segments_refine/gradual_expand_contract.py +23 -25
- {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/post_processing/segments_refine/segment_grouping.py +7 -12
- {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/post_processing/segments_refine/trend_classify.py +3 -3
- {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/post_processing/segments_refine/update_neighbours.py +23 -21
- {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/process_signals.py +50 -43
- pytrendy-1.4.0.dev4/pytrendy/io/plot_pytrendy.py +0 -204
- {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/LICENSE +0 -0
- {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/__init__.py +0 -0
- {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/io/__init__.py +0 -0
- {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/io/data/classes_signals.csv +0 -0
- {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/io/data/series_synthetic.csv +0 -0
- {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/io/data_loader.py +0 -0
- {pytrendy-1.4.0.dev4 → pytrendy-2.0.0}/pytrendy/post_processing/__init__.py +0 -0
- {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:
|
|
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.
|
|
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
|
|
129
|
-
time_index
|
|
130
|
-
1 Up 2025-01-02 2025-01-24
|
|
131
|
-
2 Down 2025-01-25 2025-02-05
|
|
132
|
-
3 Flat 2025-02-06 2025-02-09
|
|
133
|
-
4 Up 2025-02-10 2025-03-17
|
|
134
|
-
5 Down 2025-03-18 2025-04-01
|
|
135
|
-
6 Up 2025-04-02 2025-05-08
|
|
136
|
-
7 Down 2025-05-09 2025-06-17
|
|
137
|
-
8 Flat 2025-06-18 2025-06-30
|
|
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 |
|
|
147
|
-
|
|
148
|
-
| 7 | Up | 2025-04-02 | 2025-05-08 | gradual |
|
|
149
|
-
| 4 | Up | 2025-02-10 | 2025-03-17 | gradual |
|
|
150
|
-
| 1 | Up | 2025-01-02 | 2025-01-24 | gradual |
|
|
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
|
|
66
|
-
time_index
|
|
67
|
-
1 Up 2025-01-02 2025-01-24
|
|
68
|
-
2 Down 2025-01-25 2025-02-05
|
|
69
|
-
3 Flat 2025-02-06 2025-02-09
|
|
70
|
-
4 Up 2025-02-10 2025-03-17
|
|
71
|
-
5 Down 2025-03-18 2025-04-01
|
|
72
|
-
6 Up 2025-04-02 2025-05-08
|
|
73
|
-
7 Down 2025-05-09 2025-06-17
|
|
74
|
-
8 Flat 2025-06-18 2025-06-30
|
|
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 |
|
|
84
|
-
|
|
85
|
-
| 7 | Up | 2025-04-02 | 2025-05-08 | gradual |
|
|
86
|
-
| 4 | Up | 2025-02-10 | 2025-03-17 | gradual |
|
|
87
|
-
| 1 | Up | 2025-01-02 | 2025-01-24 | gradual |
|
|
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 = "
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
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
|
-
|
|
99
|
-
|
|
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
|