pytrendy 2.0.0.dev6__tar.gz → 2.0.0.dev8__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-2.0.0.dev6 → pytrendy-2.0.0.dev8}/PKG-INFO +3 -2
- {pytrendy-2.0.0.dev6 → pytrendy-2.0.0.dev8}/pyproject.toml +5 -2
- {pytrendy-2.0.0.dev6 → pytrendy-2.0.0.dev8}/pytrendy/detect_trends.py +4 -4
- {pytrendy-2.0.0.dev6 → pytrendy-2.0.0.dev8}/pytrendy/io/plot_pytrendy.py +258 -19
- pytrendy-2.0.0.dev8/pytrendy/io/prep_signal_params.py +204 -0
- pytrendy-2.0.0.dev6/pytrendy/io/prep_signal_params.py +0 -44
- {pytrendy-2.0.0.dev6 → pytrendy-2.0.0.dev8}/LICENSE +0 -0
- {pytrendy-2.0.0.dev6 → pytrendy-2.0.0.dev8}/README.md +0 -0
- {pytrendy-2.0.0.dev6 → pytrendy-2.0.0.dev8}/pytrendy/__init__.py +0 -0
- {pytrendy-2.0.0.dev6 → pytrendy-2.0.0.dev8}/pytrendy/io/__init__.py +0 -0
- {pytrendy-2.0.0.dev6 → pytrendy-2.0.0.dev8}/pytrendy/io/data/classes_signals.csv +0 -0
- {pytrendy-2.0.0.dev6 → pytrendy-2.0.0.dev8}/pytrendy/io/data/series_synthetic.csv +0 -0
- {pytrendy-2.0.0.dev6 → pytrendy-2.0.0.dev8}/pytrendy/io/data_loader.py +0 -0
- {pytrendy-2.0.0.dev6 → pytrendy-2.0.0.dev8}/pytrendy/io/prep_index.py +0 -0
- {pytrendy-2.0.0.dev6 → pytrendy-2.0.0.dev8}/pytrendy/io/results_pytrendy.py +0 -0
- {pytrendy-2.0.0.dev6 → pytrendy-2.0.0.dev8}/pytrendy/post_processing/__init__.py +0 -0
- {pytrendy-2.0.0.dev6 → pytrendy-2.0.0.dev8}/pytrendy/post_processing/segments_analyse.py +0 -0
- {pytrendy-2.0.0.dev6 → pytrendy-2.0.0.dev8}/pytrendy/post_processing/segments_get.py +0 -0
- {pytrendy-2.0.0.dev6 → pytrendy-2.0.0.dev8}/pytrendy/post_processing/segments_refine/__init__.py +0 -0
- {pytrendy-2.0.0.dev6 → pytrendy-2.0.0.dev8}/pytrendy/post_processing/segments_refine/abrupt_shaving.py +0 -0
- {pytrendy-2.0.0.dev6 → pytrendy-2.0.0.dev8}/pytrendy/post_processing/segments_refine/artifact_cleanup.py +0 -0
- {pytrendy-2.0.0.dev6 → pytrendy-2.0.0.dev8}/pytrendy/post_processing/segments_refine/gradual_expand_contract.py +0 -0
- {pytrendy-2.0.0.dev6 → pytrendy-2.0.0.dev8}/pytrendy/post_processing/segments_refine/segment_grouping.py +0 -0
- {pytrendy-2.0.0.dev6 → pytrendy-2.0.0.dev8}/pytrendy/post_processing/segments_refine/trend_classify.py +0 -0
- {pytrendy-2.0.0.dev6 → pytrendy-2.0.0.dev8}/pytrendy/post_processing/segments_refine/update_neighbours.py +0 -0
- {pytrendy-2.0.0.dev6 → pytrendy-2.0.0.dev8}/pytrendy/process_signals.py +0 -0
- {pytrendy-2.0.0.dev6 → pytrendy-2.0.0.dev8}/pytrendy/simpledtw.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: pytrendy
|
|
3
|
-
Version: 2.0.0.
|
|
3
|
+
Version: 2.0.0.dev8
|
|
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"
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "pytrendy"
|
|
3
|
-
version = "2.0.0.
|
|
3
|
+
version = "2.0.0.dev8"
|
|
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,6 +47,9 @@ 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",
|
|
@@ -55,7 +55,7 @@ def detect_trends(df: pd.DataFrame,
|
|
|
55
55
|
signal_params (dict, optional):
|
|
56
56
|
Optional parameters to customize the signal-processing constants. Supported keys (independent from `method_params`):
|
|
57
57
|
|
|
58
|
-
- **window_smooth** (`int`): Savitzky-Golay smoothing window, in points.
|
|
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
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
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
61
|
- **grouping_distance** (`int`): Maximum gap, in steps, for grouping nearby segments. Defaults to `7`.
|
|
@@ -119,9 +119,9 @@ def detect_trends(df: pd.DataFrame,
|
|
|
119
119
|
'avoid_noise': method_params.get('avoid_noise', True),
|
|
120
120
|
}
|
|
121
121
|
|
|
122
|
-
# Configures signal-processing constants.
|
|
123
|
-
# forwarded (validation is deliberately out of scope for now).
|
|
124
|
-
signal_params = prep_signal_params.prep_signal_params(signal_params)
|
|
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
125
|
|
|
126
126
|
# Core 5-step pipeline
|
|
127
127
|
df = process_signals(df, value_col, method_params, signal_params, debug)
|
|
@@ -8,6 +8,16 @@ import matplotlib.patches as mpatches
|
|
|
8
8
|
from matplotlib import colors as mcolors
|
|
9
9
|
|
|
10
10
|
|
|
11
|
+
# Tick-density calibration. All private (no public API).
|
|
12
|
+
_MAX_PINNED_TICKS = 40 # label-density target for pinned and calendar majors (lower = sparser)
|
|
13
|
+
_WEEKLY_MAX_SPAN_DAYS = 200 # daily spans up to here use weekly majors
|
|
14
|
+
_BIWEEKLY_MAX_SPAN_DAYS = 400 # ...to here biweekly majors; beyond, month majors
|
|
15
|
+
_MAX_MINOR_TICKS = 900 # minor-ruler legibility target; matplotlib's hard ceiling is MAXTICKS (1000)
|
|
16
|
+
_YEAR_MAJOR_MIN_SPAN_DAYS = 1460 # monthly-or-coarser spans switch to year majors from ~4 years
|
|
17
|
+
_MULTI_DAY_MAJOR_TICK_LENGTH = 6 # explicit observation ticks need extra length on wide, short figures
|
|
18
|
+
_MULTI_DAY_MINOR_TICK_LENGTH = 4 # long enough to read the ruler, short enough to keep majors dominant
|
|
19
|
+
|
|
20
|
+
|
|
11
21
|
def _annotation_color(color):
|
|
12
22
|
"""
|
|
13
23
|
Return a darker annotation colour for a segment fill colour.
|
|
@@ -68,6 +78,227 @@ def _adjacent_to(index, value, offset):
|
|
|
68
78
|
return None # non-unique index: no well-defined adjacent point
|
|
69
79
|
return _safe_adjacent(index, pos, offset)
|
|
70
80
|
|
|
81
|
+
def _thinned_positions(index, cap):
|
|
82
|
+
"""Observation positions thinned to at most *cap* ticks."""
|
|
83
|
+
if len(index) <= cap:
|
|
84
|
+
return index
|
|
85
|
+
return index[::int(np.ceil(len(index) / cap))]
|
|
86
|
+
|
|
87
|
+
def _pinned_tick_positions(index):
|
|
88
|
+
"""Pick tick positions pinned to observations, thinned past the cap.
|
|
89
|
+
|
|
90
|
+
Purely positional (``index[::ceil(n/_MAX_PINNED_TICKS)]``), so it is
|
|
91
|
+
agnostic to index granularity: non-daily dates (weekly, fortnightly,
|
|
92
|
+
month-end, yearly) and numerical indexes all follow the same rule. Used as
|
|
93
|
+
the fallback when no calendar unit fits a multi-day cadence.
|
|
94
|
+
"""
|
|
95
|
+
return _thinned_positions(index, _MAX_PINNED_TICKS)
|
|
96
|
+
|
|
97
|
+
def _sampling_locator(interval_days):
|
|
98
|
+
"""Locator marking every *interval_days*, or None when unexpressible.
|
|
99
|
+
|
|
100
|
+
matplotlib's time locators align by minute-of-hour or hour-of-day, so a
|
|
101
|
+
sampling gap is expressible only if it divides an hour (``MinuteLocator``)
|
|
102
|
+
or a day (``HourLocator``, ``DayLocator``). 30-minute bars ->
|
|
103
|
+
``MinuteLocator(30)``, hourly -> ``HourLocator(1)``, daily ->
|
|
104
|
+
``DayLocator()``. A 45- or 90-minute gap has no such locator, so callers
|
|
105
|
+
fall back to positional ticks.
|
|
106
|
+
"""
|
|
107
|
+
minutes = interval_days * 24 * 60
|
|
108
|
+
if abs(minutes - round(minutes)) > 1e-6:
|
|
109
|
+
return None
|
|
110
|
+
minutes = int(round(minutes))
|
|
111
|
+
if minutes < 1:
|
|
112
|
+
return None
|
|
113
|
+
if minutes < 60:
|
|
114
|
+
return mdates.MinuteLocator(interval=minutes) if 60 % minutes == 0 else None
|
|
115
|
+
if minutes % 60:
|
|
116
|
+
return None
|
|
117
|
+
hours = minutes // 60
|
|
118
|
+
if hours < 24:
|
|
119
|
+
return mdates.HourLocator(interval=hours) if 24 % hours == 0 else None
|
|
120
|
+
return mdates.DayLocator(interval=max(1, int(np.ceil(interval_days - 1e-9))))
|
|
121
|
+
|
|
122
|
+
def _minor_locator(step_days, span_steps, index):
|
|
123
|
+
"""True-granularity minor locator, thinned under matplotlib's tick limit.
|
|
124
|
+
|
|
125
|
+
The interval tracks the data's own sampling gap. When the span projects more
|
|
126
|
+
than ``_MAX_MINOR_TICKS`` of them the interval is coarsened by
|
|
127
|
+
``ceil(count / limit)``. matplotlib's hard ceiling is ``MAXTICKS`` (1000), but
|
|
128
|
+
900 is the legibility target -- a ruler, not a band (e.g. 60 days of
|
|
129
|
+
30-minute bars: 2880 -> interval x4 -> every 2 hours, ~720 ticks). Returns an
|
|
130
|
+
explicit array of positions for a gap no locator can express (e.g. 45-minute
|
|
131
|
+
bars), thinned to the same target.
|
|
132
|
+
"""
|
|
133
|
+
base = _sampling_locator(step_days)
|
|
134
|
+
if base is None:
|
|
135
|
+
# Inexpressible cadence -> the true-granularity ruler as explicit
|
|
136
|
+
# observation positions. Fixed ticks bypass Locator.MAXTICKS, so the
|
|
137
|
+
# thinning here is our own legibility choice.
|
|
138
|
+
return _thinned_positions(index, _MAX_MINOR_TICKS)
|
|
139
|
+
if span_steps <= _MAX_MINOR_TICKS:
|
|
140
|
+
return base
|
|
141
|
+
# Coarsen to the first expressible multiple, so 30-minute bars thin to whole
|
|
142
|
+
# hours rather than an unexpressible 5.5 hours (which would drop the ruler).
|
|
143
|
+
factor = int(np.ceil(span_steps / _MAX_MINOR_TICKS))
|
|
144
|
+
locator = _sampling_locator(step_days * factor)
|
|
145
|
+
while locator is None:
|
|
146
|
+
factor += 1
|
|
147
|
+
locator = _sampling_locator(step_days * factor)
|
|
148
|
+
return locator
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
def _divides(step_days, unit_days):
|
|
152
|
+
"""True if *step_days* is at most *unit_days* and divides it near-exactly."""
|
|
153
|
+
if step_days <= 0 or step_days > unit_days:
|
|
154
|
+
return False
|
|
155
|
+
ratio = unit_days / step_days
|
|
156
|
+
return abs(ratio - round(ratio)) < 1e-6
|
|
157
|
+
|
|
158
|
+
def _expressible_hour_interval(step_days, min_hours):
|
|
159
|
+
"""Smallest whole-hour interval >= *min_hours* an ``HourLocator`` can mark.
|
|
160
|
+
|
|
161
|
+
``HourLocator`` aligns to whole hours of the day, so only intervals dividing
|
|
162
|
+
24 hours are expressible; the interval must also divide the sampling gap
|
|
163
|
+
evenly so every observation lands on a major gridline. Returns the interval
|
|
164
|
+
in hours, or None when no hour granularity fits (e.g. a 5-hour gap).
|
|
165
|
+
"""
|
|
166
|
+
step_minutes = step_days * 24 * 60
|
|
167
|
+
for hours in range(1, 24):
|
|
168
|
+
if 24 % hours or hours < min_hours:
|
|
169
|
+
continue
|
|
170
|
+
ratio = hours * 60 / step_minutes
|
|
171
|
+
if abs(ratio - round(ratio)) < 1e-6:
|
|
172
|
+
return hours
|
|
173
|
+
return None
|
|
174
|
+
|
|
175
|
+
def _intraday_major_locator(step_days, span_days):
|
|
176
|
+
"""Major locator for sub-daily data, widening with span; None if no unit fits.
|
|
177
|
+
|
|
178
|
+
Each rung searches upward from its preferred interval for the smallest
|
|
179
|
+
expressible multiple that also divides the sampling gap; only when none
|
|
180
|
+
exists does the next rung get a turn, and the terminal fallback is positional
|
|
181
|
+
ticks. A 30-minute gap gives 2-hour majors under a one-day span, 6-hour over
|
|
182
|
+
three days, days thereafter; a 45-minute gap gives 3-hour majors under a day
|
|
183
|
+
(the smallest whole-hour multiple of 45 minutes), then 6-hour over three
|
|
184
|
+
days, and nothing expressible beyond -- where the caller pins positions.
|
|
185
|
+
"""
|
|
186
|
+
if span_days <= 1:
|
|
187
|
+
# Exactly-hourly keeps HourLocator(1); every other cadence starts at 2 h.
|
|
188
|
+
floor = 1 if np.isclose(step_days, 1 / 24) else 2
|
|
189
|
+
hours = _expressible_hour_interval(step_days, floor)
|
|
190
|
+
if hours is not None:
|
|
191
|
+
return mdates.HourLocator(interval=hours)
|
|
192
|
+
if span_days <= 3:
|
|
193
|
+
hours = _expressible_hour_interval(step_days, 6)
|
|
194
|
+
if hours is not None:
|
|
195
|
+
return mdates.HourLocator(interval=hours)
|
|
196
|
+
if not _divides(step_days, 1):
|
|
197
|
+
return None
|
|
198
|
+
if span_days <= 7:
|
|
199
|
+
return mdates.DayLocator()
|
|
200
|
+
if span_days <= _WEEKLY_MAX_SPAN_DAYS:
|
|
201
|
+
return mdates.WeekdayLocator(interval=1)
|
|
202
|
+
if span_days <= _BIWEEKLY_MAX_SPAN_DAYS:
|
|
203
|
+
return mdates.WeekdayLocator(interval=2)
|
|
204
|
+
return mdates.MonthLocator()
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
def _format_for(major_locator):
|
|
208
|
+
"""Major label format keyed to the major unit, not the span.
|
|
209
|
+
|
|
210
|
+
Hour-or-finer majors carry date and time on two lines (sub-day plots need
|
|
211
|
+
the clock); day-or-coarser majors (Day/Weekday/Month locators, or pinned
|
|
212
|
+
positions) read as dates only. So a 3-7-day span on the day rung no longer
|
|
213
|
+
labels a trailing ``00:00``.
|
|
214
|
+
"""
|
|
215
|
+
if isinstance(major_locator, (mdates.HourLocator, mdates.MinuteLocator,
|
|
216
|
+
mdates.SecondLocator)):
|
|
217
|
+
return '%Y-%m-%d\n%H:%M'
|
|
218
|
+
return '%Y-%m-%d'
|
|
219
|
+
|
|
220
|
+
|
|
221
|
+
def _calendar_major_positions(index, step_days, span_days):
|
|
222
|
+
"""Calendar-unit majors, snapped to the first available observation.
|
|
223
|
+
|
|
224
|
+
Majors step up from the cadence to a calendar unit: weekly-ish cadences
|
|
225
|
+
(< 15 days) read month by month; monthly-or-coarser cadences use year majors
|
|
226
|
+
once the span reaches ~4 years (shorter monthly series stay month-based);
|
|
227
|
+
yearly cadences always use year majors. The interval scales so the label
|
|
228
|
+
count stays near ``_MAX_PINNED_TICKS``, and each period's tick lands on the
|
|
229
|
+
first observed point in it.
|
|
230
|
+
"""
|
|
231
|
+
use_years = step_days >= 200 or (step_days >= 15 and span_days >= _YEAR_MAJOR_MIN_SPAN_DAYS)
|
|
232
|
+
units = span_days / (365.25 if use_years else 30.44)
|
|
233
|
+
interval = max(1, int(np.ceil(units / _MAX_PINNED_TICKS)))
|
|
234
|
+
if not use_years and step_days >= 15:
|
|
235
|
+
interval = max(2, interval)
|
|
236
|
+
periods = index.to_period('Y' if use_years else 'M')
|
|
237
|
+
starts = np.r_[True, periods[1:] != periods[:-1]]
|
|
238
|
+
return index[np.flatnonzero(starts)[::interval]]
|
|
239
|
+
|
|
240
|
+
|
|
241
|
+
def _date_tick_spec(index, span_steps):
|
|
242
|
+
"""Pick date-axis tick strategy from sampling cadence and span.
|
|
243
|
+
|
|
244
|
+
*span_steps* is the positional span ``len(index) - 1``. Cadence is read once
|
|
245
|
+
from the median calendar gap (median is DST-robust for daily data):
|
|
246
|
+
|
|
247
|
+
* Non-daily (gap > 1 day: weekly, fortnightly, month-end, yearly, ...):
|
|
248
|
+
majors step up to a calendar unit -- month periods for weekly-ish
|
|
249
|
+
cadences, year periods for monthly-or-coarser cadences once the span
|
|
250
|
+
reaches ~4 years (yearly cadences always) -- scaled to keep labels near
|
|
251
|
+
``_MAX_PINNED_TICKS`` and snapped to the first available observation in
|
|
252
|
+
each period. Minors are the data's own granularity as positional ticks at
|
|
253
|
+
the observations, thinned to ``_MAX_MINOR_TICKS``.
|
|
254
|
+
* Daily (gap of one day): the original span-in-steps ladder -- weekly ->
|
|
255
|
+
biweekly -> month majors, with a daily minor ruler.
|
|
256
|
+
* Sub-daily: minors follow the true sampling granularity (30-minute bars ->
|
|
257
|
+
every 30 minutes, hourly -> every hour), thinned below
|
|
258
|
+
``_MAX_MINOR_TICKS``; majors widen with the span in calendar days
|
|
259
|
+
(hours -> 6 hours -> days -> weeks -> months). When no major unit divides
|
|
260
|
+
the gap (45- or 90-minute bars past a few days), majors fall back to
|
|
261
|
+
positional ticks; when no minor locator can express the gap, the minor slot
|
|
262
|
+
becomes explicit positions at the observations.
|
|
263
|
+
|
|
264
|
+
The one-year minor cut-off applies to the daily and sub-daily rulers only;
|
|
265
|
+
multi-day minors thin (never drop) under ``_MAX_MINOR_TICKS``.
|
|
266
|
+
|
|
267
|
+
Returns ``(major_locator, minor_locator, pinned_positions, date_format)``.
|
|
268
|
+
The major slot is a locator or None; the minor slot is a locator, an array of
|
|
269
|
+
positions, or None; locators and pinned positions are mutually exclusive.
|
|
270
|
+
Multi-day calendar majors are returned in ``pinned_positions`` so they land
|
|
271
|
+
on observations rather than calendar boundaries.
|
|
272
|
+
"""
|
|
273
|
+
# The one calendar read: the series' sampling cadence in days, taken as the
|
|
274
|
+
# median calendar gap between observations. Median (not mean) so DST shifts
|
|
275
|
+
# and occasional gaps don't skew it.
|
|
276
|
+
diffs = np.diff(index.values)
|
|
277
|
+
median_step_days = np.median(diffs) / np.timedelta64(1, 'D') if len(diffs) else 1
|
|
278
|
+
span_days = span_steps * median_step_days
|
|
279
|
+
|
|
280
|
+
if median_step_days > 1:
|
|
281
|
+
pinned = _calendar_major_positions(index, median_step_days, span_days)
|
|
282
|
+
return None, _thinned_positions(index, _MAX_MINOR_TICKS), pinned, '%Y-%m-%d'
|
|
283
|
+
|
|
284
|
+
# Minors only while the span is within a year; past that the axis reads as a
|
|
285
|
+
# calendar.
|
|
286
|
+
minor = _minor_locator(median_step_days, span_steps, index) if span_days <= 365 else None
|
|
287
|
+
|
|
288
|
+
if np.isclose(median_step_days, 1):
|
|
289
|
+
if span_days <= _WEEKLY_MAX_SPAN_DAYS:
|
|
290
|
+
return mdates.WeekdayLocator(interval=1), mdates.DayLocator(), None, '%Y-%m-%d'
|
|
291
|
+
if span_days <= _BIWEEKLY_MAX_SPAN_DAYS:
|
|
292
|
+
return mdates.WeekdayLocator(interval=2), mdates.DayLocator(), None, '%Y-%m-%d'
|
|
293
|
+
# Beyond ~13 months: month majors with the year-capped minor ruler.
|
|
294
|
+
return mdates.MonthLocator(), minor, None, '%Y-%m-%d'
|
|
295
|
+
|
|
296
|
+
major = _intraday_major_locator(median_step_days, span_days)
|
|
297
|
+
if major is None:
|
|
298
|
+
return None, minor, _pinned_tick_positions(index), _format_for(major)
|
|
299
|
+
return major, minor, None, _format_for(major)
|
|
300
|
+
|
|
301
|
+
|
|
71
302
|
def plot_pytrendy(df: pd.DataFrame, value_col: str, segments_enhanced: list[dict], index_type: str = "date", suppress_show: bool = False, plot_params: dict = None) -> plt.Figure:
|
|
72
303
|
"""
|
|
73
304
|
Visualizes detected trend segments over the original time series signal.
|
|
@@ -320,28 +551,36 @@ def plot_pytrendy(df: pd.DataFrame, value_col: str, segments_enhanced: list[dict
|
|
|
320
551
|
|
|
321
552
|
if index_type in ('date', 'datetime64'):
|
|
322
553
|
index = df.index
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
if gap_days <= 1:
|
|
329
|
-
# Daily data: weekly majors on the default weekday, as before.
|
|
330
|
-
ax.xaxis.set_major_locator(mdates.WeekdayLocator(interval=1))
|
|
331
|
-
else:
|
|
332
|
-
# Non-daily spacing: pin majors to the data's own index positions so
|
|
554
|
+
span_steps = len(index) - 1
|
|
555
|
+
|
|
556
|
+
major, minor, pinned, date_format = _date_tick_spec(index, span_steps)
|
|
557
|
+
if pinned is not None:
|
|
558
|
+
# Positional ticks: pin majors to the data's own index positions so
|
|
333
559
|
# every major (and its 'major' gridline) lands exactly on an
|
|
334
560
|
# observation, for any cadence including irregular. A WeekdayLocator
|
|
335
561
|
# anchors its interval grid to the Unix epoch, which lands majors
|
|
336
562
|
# beside fortnightly / month-end observations.
|
|
337
|
-
ax.set_xticks(
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
if
|
|
344
|
-
|
|
563
|
+
ax.set_xticks(pinned)
|
|
564
|
+
else:
|
|
565
|
+
# Locator-based majors: coarsen with span so long series avoid a
|
|
566
|
+
# wall of labels. Minors carry the data's own sampling granularity
|
|
567
|
+
# where a matplotlib locator can express it, else they are omitted.
|
|
568
|
+
ax.xaxis.set_major_locator(major)
|
|
569
|
+
if minor is not None:
|
|
570
|
+
if isinstance(minor, (np.ndarray, pd.Index)):
|
|
571
|
+
# Inexpressible cadence: explicit positional ruler, bypassing
|
|
572
|
+
# Locator.MAXTICKS.
|
|
573
|
+
ax.set_xticks(minor, minor=True)
|
|
574
|
+
is_multi_day = (len(index) > 1 and
|
|
575
|
+
np.median(np.diff(index.values)) / np.timedelta64(1, 'D') > 1)
|
|
576
|
+
if is_multi_day:
|
|
577
|
+
ax.tick_params(axis='x', which='major', length=_MULTI_DAY_MAJOR_TICK_LENGTH,
|
|
578
|
+
width=1.0)
|
|
579
|
+
ax.tick_params(axis='x', which='minor', length=_MULTI_DAY_MINOR_TICK_LENGTH,
|
|
580
|
+
width=0.8)
|
|
581
|
+
else:
|
|
582
|
+
ax.xaxis.set_minor_locator(minor)
|
|
583
|
+
ax.xaxis.set_major_formatter(mdates.DateFormatter(date_format))
|
|
345
584
|
|
|
346
585
|
# Rotate major tick labels
|
|
347
586
|
plt.setp(ax.get_xticklabels(), rotation=90, ha='right')
|
|
@@ -386,4 +625,4 @@ def plot_pytrendy(df: pd.DataFrame, value_col: str, segments_enhanced: list[dict
|
|
|
386
625
|
plt.tight_layout()
|
|
387
626
|
if not suppress_show:
|
|
388
627
|
plt.show()
|
|
389
|
-
return fig
|
|
628
|
+
return fig
|
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
"""**Signal-Parameter Preparation**
|
|
2
|
+
|
|
3
|
+
The signal-processing stages share a common set of constants — smoothing and
|
|
4
|
+
rolling windows, grouping distance, and the noise/flat thresholds. ``detect_trends``
|
|
5
|
+
is the single public entry point, so this module is the one place those constants
|
|
6
|
+
are defaulted before the pipeline runs.
|
|
7
|
+
|
|
8
|
+
``window_smooth`` is granularity-aware: when the caller does not override it, it is
|
|
9
|
+
inferred from the index cadence so a single smoothing window spans a comparable
|
|
10
|
+
stretch of the series at every sampling frequency. The inferred point counts are:
|
|
11
|
+
|
|
12
|
+
| Cadence | P (pts/cycle) | window_smooth (= 2P+1) |
|
|
13
|
+
| ----------- | ------------- | ---------------------- |
|
|
14
|
+
| 15 minutes | 96 | 193 |
|
|
15
|
+
| 30 minutes | 48 | 97 |
|
|
16
|
+
| hourly | 24 | 49 |
|
|
17
|
+
| daily | 7 | 15 |
|
|
18
|
+
| weekly | 4 | 9 |
|
|
19
|
+
| monthly | 12 | 25 |
|
|
20
|
+
| quarterly | 4 | 9 |
|
|
21
|
+
| yearly | — (fallback) | 5 |
|
|
22
|
+
| other | — | 15 |
|
|
23
|
+
|
|
24
|
+
The table entries satisfy ``int(window_smooth × 0.5) = P``, so the default
|
|
25
|
+
``smooth_factor``/``noise_factor`` (0.5) make ``window_flat``/``window_noise``
|
|
26
|
+
span one seasonal cycle while ``window_smooth`` spans two. Keep new rows on the
|
|
27
|
+
``2P+1`` ladder.
|
|
28
|
+
|
|
29
|
+
The table is matched pragmatically against :func:`pandas.infer_freq` labels:
|
|
30
|
+
``T``/``min`` aliases containing 15 or 30, hourly ``H``/``h``, daily ``D``,
|
|
31
|
+
weekly ``W...``, monthly ``M``/``ME``/``MS``,
|
|
32
|
+
quarterly ``Q...`` and yearly ``Y``/``A``/``YE``/``YS``. An explicit user ``window_smooth`` always wins and
|
|
33
|
+
skips inference. The resolved window is finally clamped to the series length
|
|
34
|
+
(decrementing by two to stay odd) with a floor of 3, so Savitzky-Golay always
|
|
35
|
+
receives a valid window.
|
|
36
|
+
|
|
37
|
+
Defaults are merged with any user-supplied ``signal_params`` overrides. The derived
|
|
38
|
+
windows ``window_flat`` and ``window_noise`` are not top-level defaults: unless
|
|
39
|
+
explicitly overridden they derive from ``window_smooth``. Every stage downstream
|
|
40
|
+
assumes :func:`prep_signal_params` returns a fully-populated dict.
|
|
41
|
+
"""
|
|
42
|
+
|
|
43
|
+
import warnings
|
|
44
|
+
|
|
45
|
+
import numpy as np
|
|
46
|
+
import pandas as pd
|
|
47
|
+
|
|
48
|
+
_SIGNAL_PARAMS_DEFAULTS = {
|
|
49
|
+
'window_smooth': 15, # Savitzky-Golay smoothing window, in points.
|
|
50
|
+
'smooth_factor': 0.5, # Fraction of window_smooth spanned by window_flat: raise to widen it (smoother flat
|
|
51
|
+
# baseline, fewer flags), lower to narrow it (more sensitive); scaled to window_smooth so it stays proportional. Historical name: it scales window_flat, not smoothing; with the 2P+1 table it recovers P.
|
|
52
|
+
'noise_factor': 0.5, # Fraction of window_smooth spanned by window_noise: raise to widen it (smoother SNR estimate, fewer flags), lower to narrow it (more sensitive); scaled to window_smooth so it stays proportional.
|
|
53
|
+
'grouping_distance': 7, # Maximum gap, in index steps, for grouping nearby segments.
|
|
54
|
+
'min_trend_length': 3, # Minimum length, in steps, for an Up/Down segment to be retained.
|
|
55
|
+
'min_flat_noise_length': 1, # Minimum length, in steps, for a Flat/Noise segment to be retained.
|
|
56
|
+
'threshold_noise': 2.5, # SNR threshold (dB) below which a region is classified as noise.
|
|
57
|
+
'threshold_smooth': 0.001, # Derivative threshold as a fraction of the signal IQR, below which motion counts as flat.
|
|
58
|
+
'threshold_flat': 0.835, # Flat sensitivity as a fraction of the minimum non-zero rolling std.
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
# Inferred smoothing window per cadence label. See the module docstring for the table.
|
|
62
|
+
_WINDOW_BY_CADENCE = {
|
|
63
|
+
'15min': 193,
|
|
64
|
+
'30min': 97,
|
|
65
|
+
'H': 49,
|
|
66
|
+
'D': 15,
|
|
67
|
+
'W': 9,
|
|
68
|
+
'ME': 25,
|
|
69
|
+
'QE': 9,
|
|
70
|
+
'YE': 5,
|
|
71
|
+
}
|
|
72
|
+
_DEFAULT_WINDOW = _SIGNAL_PARAMS_DEFAULTS['window_smooth']
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def _clamp_window(window: int, n: int|None) -> int:
|
|
76
|
+
"""Shrink ``window`` to the series length, keeping it odd with a floor of 3."""
|
|
77
|
+
if n is None:
|
|
78
|
+
return window
|
|
79
|
+
while window > n:
|
|
80
|
+
window -= 2
|
|
81
|
+
return max(window, 3)
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def _as_datetime_index(index):
|
|
85
|
+
"""Return a ``DatetimeIndex`` view of ``index`` when it is date-like, else ``None``.
|
|
86
|
+
|
|
87
|
+
Numeric indexes are never coerced: integer/float values would otherwise be read
|
|
88
|
+
as epoch timestamps by :func:`pandas.to_datetime`. Only datetime dtypes and
|
|
89
|
+
genuinely parseable string/object labels are accepted.
|
|
90
|
+
"""
|
|
91
|
+
if isinstance(index, pd.Series):
|
|
92
|
+
dtype = index.dtype
|
|
93
|
+
else:
|
|
94
|
+
arr = np.asarray(index)
|
|
95
|
+
if np.issubdtype(arr.dtype, np.datetime64):
|
|
96
|
+
return pd.DatetimeIndex(arr)
|
|
97
|
+
dtype = arr.dtype
|
|
98
|
+
|
|
99
|
+
if pd.api.types.is_datetime64_any_dtype(dtype):
|
|
100
|
+
return pd.DatetimeIndex(index)
|
|
101
|
+
if pd.api.types.is_object_dtype(dtype) or pd.api.types.is_string_dtype(dtype):
|
|
102
|
+
with warnings.catch_warnings():
|
|
103
|
+
warnings.filterwarnings("ignore", message="Could not infer format.*")
|
|
104
|
+
parsed = pd.to_datetime(index, errors='coerce')
|
|
105
|
+
if parsed.notna().all():
|
|
106
|
+
return pd.DatetimeIndex(parsed)
|
|
107
|
+
return None
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
def _window_from_label(label: str|None) -> int|None:
|
|
111
|
+
"""Map a ``pandas.infer_freq`` label to its smoothing window, or ``None`` if unmapped."""
|
|
112
|
+
lab = str(label)
|
|
113
|
+
low = lab.lower()
|
|
114
|
+
|
|
115
|
+
# Sub-hourly: 'T'/'min' aliases (e.g. '15T', '30min'); other spans are unmapped.
|
|
116
|
+
if 'min' in low or low.endswith('t'):
|
|
117
|
+
if '15' in lab:
|
|
118
|
+
return _WINDOW_BY_CADENCE['15min']
|
|
119
|
+
if '30' in lab:
|
|
120
|
+
return _WINDOW_BY_CADENCE['30min']
|
|
121
|
+
return None
|
|
122
|
+
if low == 'h': # hourly ('H'/'h'); '5H' etc. stay unmapped
|
|
123
|
+
return _WINDOW_BY_CADENCE['H']
|
|
124
|
+
if low == 'd': # daily
|
|
125
|
+
return _WINDOW_BY_CADENCE['D']
|
|
126
|
+
if low.startswith('w'): # weekly ('W', 'W-SUN', ...)
|
|
127
|
+
return _WINDOW_BY_CADENCE['W']
|
|
128
|
+
if low.startswith('m'): # monthly ('M'/'ME'/'MS'); 'min' handled above
|
|
129
|
+
return _WINDOW_BY_CADENCE['ME']
|
|
130
|
+
if low.startswith('q'): # quarterly
|
|
131
|
+
return _WINDOW_BY_CADENCE['QE']
|
|
132
|
+
if low.startswith('y') or low.startswith('a'): # yearly ('Y'/'A'/'YE'/'YS')
|
|
133
|
+
return _WINDOW_BY_CADENCE['YE']
|
|
134
|
+
return None
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def infer_window_smooth(index, n: int|None=None) -> int:
|
|
138
|
+
"""
|
|
139
|
+
Infer a smoothing window from the sampling cadence of an index.
|
|
140
|
+
|
|
141
|
+
Converts ``index`` to a ``DatetimeIndex`` (date-like values only), asks
|
|
142
|
+
:func:`pandas.infer_freq` for its frequency label, and maps that label through
|
|
143
|
+
the cadence table. Anything unmapped — a non-datetime index, an irregular or
|
|
144
|
+
unparseable one, or an exotic frequency such as ``'45T'``/``'5H'``/``'14D'`` —
|
|
145
|
+
falls back to 15. Degenerate inputs (``None``, ragged sequences, or indexes
|
|
146
|
+
``infer_freq`` rejects) now raise instead of falling back. The result is clamped
|
|
147
|
+
to ``n`` when provided.
|
|
148
|
+
|
|
149
|
+
Args:
|
|
150
|
+
index: External index values (pandas Index/Series, or array-like).
|
|
151
|
+
n (int, optional): Series length used to clamp the inferred window.
|
|
152
|
+
|
|
153
|
+
Returns:
|
|
154
|
+
int: Inferred smoothing window (clamped to ``n`` when given).
|
|
155
|
+
"""
|
|
156
|
+
window = _DEFAULT_WINDOW
|
|
157
|
+
dt_index = _as_datetime_index(index)
|
|
158
|
+
if dt_index is not None and len(dt_index) >= 3:
|
|
159
|
+
freq = pd.infer_freq(dt_index)
|
|
160
|
+
label_window = _window_from_label(freq)
|
|
161
|
+
if label_window is not None:
|
|
162
|
+
window = label_window
|
|
163
|
+
return _clamp_window(window, n)
|
|
164
|
+
|
|
165
|
+
|
|
166
|
+
def prep_signal_params(signal_params: dict|None=None, index=None, n: int|None=None) -> dict:
|
|
167
|
+
"""
|
|
168
|
+
Merge user-supplied `signal_params` over the defaults and derive window sizes.
|
|
169
|
+
|
|
170
|
+
`window_smooth` is inferred from `index`'s cadence when the user does not
|
|
171
|
+
explicitly set it; an explicit value always wins. The resolved window is then
|
|
172
|
+
clamped to the series length. `window_flat` and `window_noise` are not
|
|
173
|
+
top-level defaults: unless explicitly overridden they derive from the clamped
|
|
174
|
+
`window_smooth`. Every stage downstream assumes this returns a fully-populated
|
|
175
|
+
dict.
|
|
176
|
+
|
|
177
|
+
Args:
|
|
178
|
+
signal_params (dict, optional): User overrides. Unknown keys are forwarded silently.
|
|
179
|
+
index (optional): External index; its cadence infers `window_smooth` when the
|
|
180
|
+
user does not supply one.
|
|
181
|
+
n (int, optional): Series length used to clamp `window_smooth`. Defaults to
|
|
182
|
+
`len(index)` when `index` is given.
|
|
183
|
+
|
|
184
|
+
Returns:
|
|
185
|
+
dict: Fully-populated signal_params with every key the stages read.
|
|
186
|
+
"""
|
|
187
|
+
user_params = signal_params or {}
|
|
188
|
+
resolved = {**_SIGNAL_PARAMS_DEFAULTS, **user_params}
|
|
189
|
+
|
|
190
|
+
if n is None and index is not None:
|
|
191
|
+
n = len(index)
|
|
192
|
+
|
|
193
|
+
if 'window_smooth' in user_params:
|
|
194
|
+
# Explicit value wins; still clamp it to a Savitzky-Golay-valid window.
|
|
195
|
+
resolved['window_smooth'] = _clamp_window(resolved['window_smooth'], n)
|
|
196
|
+
elif index is not None:
|
|
197
|
+
resolved['window_smooth'] = infer_window_smooth(index, n)
|
|
198
|
+
else:
|
|
199
|
+
resolved['window_smooth'] = _clamp_window(resolved['window_smooth'], n)
|
|
200
|
+
|
|
201
|
+
# Derive the factor-based windows *after* clamping, and only when the user did not set them explicitly.
|
|
202
|
+
resolved.setdefault('window_flat', int(resolved['window_smooth'] * resolved['smooth_factor']))
|
|
203
|
+
resolved.setdefault('window_noise', int(resolved['window_smooth'] * resolved['noise_factor']))
|
|
204
|
+
return resolved
|
|
@@ -1,44 +0,0 @@
|
|
|
1
|
-
"""**Signal-Parameter Preparation**
|
|
2
|
-
|
|
3
|
-
The signal-processing stages share a common set of constants — smoothing and
|
|
4
|
-
rolling windows, grouping distance, and the noise/flat thresholds. ``detect_trends``
|
|
5
|
-
is the single public entry point, so this module is the one place those constants
|
|
6
|
-
are defaulted before the pipeline runs.
|
|
7
|
-
|
|
8
|
-
Defaults are merged with any user-supplied ``signal_params`` overrides. The derived
|
|
9
|
-
windows ``window_flat`` and ``window_noise`` are not top-level defaults: unless
|
|
10
|
-
explicitly overridden they derive from ``window_smooth``. Every stage downstream
|
|
11
|
-
assumes :func:`prep_signal_params` returns a fully-populated dict.
|
|
12
|
-
"""
|
|
13
|
-
|
|
14
|
-
_SIGNAL_PARAMS_DEFAULTS = {
|
|
15
|
-
'window_smooth': 15, # Savitzky-Golay smoothing window, in points.
|
|
16
|
-
'smooth_factor': 0.5, # Fraction of window_smooth spanned by window_flat: raise to widen it (smoother flat baseline, fewer flags), lower to narrow it (more sensitive); scaled to window_smooth so it stays proportional.
|
|
17
|
-
'noise_factor': 0.5, # Fraction of window_smooth spanned by window_noise: raise to widen it (smoother SNR estimate, fewer flags), lower to narrow it (more sensitive); scaled to window_smooth so it stays proportional.
|
|
18
|
-
'grouping_distance': 7, # Maximum gap, in index steps, for grouping nearby segments.
|
|
19
|
-
'min_trend_length': 3, # Minimum length, in steps, for an Up/Down segment to be retained.
|
|
20
|
-
'min_flat_noise_length': 1, # Minimum length, in steps, for a Flat/Noise segment to be retained.
|
|
21
|
-
'threshold_noise': 2.5, # SNR threshold (dB) below which a region is classified as noise.
|
|
22
|
-
'threshold_smooth': 0.001, # Derivative threshold as a fraction of the signal IQR, below which motion counts as flat.
|
|
23
|
-
'threshold_flat': 0.835, # Flat sensitivity as a fraction of the minimum non-zero rolling std.
|
|
24
|
-
}
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
def prep_signal_params(signal_params: dict|None=None) -> dict:
|
|
28
|
-
"""
|
|
29
|
-
Merge user-supplied `signal_params` over the defaults and derive window sizes.
|
|
30
|
-
|
|
31
|
-
`window_flat` and `window_noise` are not top-level defaults: unless explicitly
|
|
32
|
-
overridden they derive from `window_smooth`. Every stage downstream assumes
|
|
33
|
-
this returns a fully-populated dict.
|
|
34
|
-
|
|
35
|
-
Args:
|
|
36
|
-
signal_params (dict, optional): User overrides. Unknown keys are forwarded silently.
|
|
37
|
-
|
|
38
|
-
Returns:
|
|
39
|
-
dict: Fully-populated signal_params with every key the stages read.
|
|
40
|
-
"""
|
|
41
|
-
resolved = {**_SIGNAL_PARAMS_DEFAULTS, **(signal_params or {})}
|
|
42
|
-
resolved.setdefault('window_flat', int(resolved['window_smooth'] * resolved['smooth_factor']))
|
|
43
|
-
resolved.setdefault('window_noise', int(resolved['window_smooth'] * resolved['noise_factor']))
|
|
44
|
-
return resolved
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{pytrendy-2.0.0.dev6 → pytrendy-2.0.0.dev8}/pytrendy/post_processing/segments_refine/__init__.py
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|