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.
- {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/PKG-INFO +20 -17
- {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/README.md +15 -15
- {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pyproject.toml +13 -5
- {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/detect_trends.py +29 -8
- pytrendy-2.0.0/pytrendy/io/plot_pytrendy.py +643 -0
- pytrendy-1.4.0.dev5/pytrendy/io/prepare_index.py → pytrendy-2.0.0/pytrendy/io/prep_index.py +1 -1
- pytrendy-2.0.0/pytrendy/io/prep_signal_params.py +204 -0
- {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/io/results_pytrendy.py +17 -26
- {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/post_processing/segments_analyse.py +11 -10
- {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/post_processing/segments_get.py +14 -6
- {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/post_processing/segments_refine/__init__.py +14 -9
- {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/post_processing/segments_refine/artifact_cleanup.py +9 -10
- {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/post_processing/segments_refine/segment_grouping.py +6 -11
- {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/process_signals.py +32 -29
- pytrendy-1.4.0.dev5/pytrendy/io/plot_pytrendy.py +0 -313
- {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/LICENSE +0 -0
- {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/__init__.py +0 -0
- {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/io/__init__.py +0 -0
- {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/io/data/classes_signals.csv +0 -0
- {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/io/data/series_synthetic.csv +0 -0
- {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/io/data_loader.py +0 -0
- {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/post_processing/__init__.py +0 -0
- {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/post_processing/segments_refine/abrupt_shaving.py +0 -0
- {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/post_processing/segments_refine/gradual_expand_contract.py +0 -0
- {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/post_processing/segments_refine/trend_classify.py +0 -0
- {pytrendy-1.4.0.dev5 → pytrendy-2.0.0}/pytrendy/post_processing/segments_refine/update_neighbours.py +0 -0
- {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:
|
|
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,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
|
|
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
|
|
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 =
|
|
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 =
|
|
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 =
|
|
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)
|