pytrendy 2.0.0.dev4__tar.gz → 2.0.0.dev5__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 (25) hide show
  1. {pytrendy-2.0.0.dev4 → pytrendy-2.0.0.dev5}/PKG-INFO +12 -12
  2. {pytrendy-2.0.0.dev4 → pytrendy-2.0.0.dev5}/README.md +11 -11
  3. {pytrendy-2.0.0.dev4 → pytrendy-2.0.0.dev5}/pyproject.toml +1 -1
  4. {pytrendy-2.0.0.dev4 → pytrendy-2.0.0.dev5}/pytrendy/io/results_pytrendy.py +17 -26
  5. {pytrendy-2.0.0.dev4 → pytrendy-2.0.0.dev5}/pytrendy/post_processing/segments_analyse.py +7 -7
  6. {pytrendy-2.0.0.dev4 → pytrendy-2.0.0.dev5}/pytrendy/post_processing/segments_refine/segment_grouping.py +3 -7
  7. {pytrendy-2.0.0.dev4 → pytrendy-2.0.0.dev5}/LICENSE +0 -0
  8. {pytrendy-2.0.0.dev4 → pytrendy-2.0.0.dev5}/pytrendy/__init__.py +0 -0
  9. {pytrendy-2.0.0.dev4 → pytrendy-2.0.0.dev5}/pytrendy/detect_trends.py +0 -0
  10. {pytrendy-2.0.0.dev4 → pytrendy-2.0.0.dev5}/pytrendy/io/__init__.py +0 -0
  11. {pytrendy-2.0.0.dev4 → pytrendy-2.0.0.dev5}/pytrendy/io/data/classes_signals.csv +0 -0
  12. {pytrendy-2.0.0.dev4 → pytrendy-2.0.0.dev5}/pytrendy/io/data/series_synthetic.csv +0 -0
  13. {pytrendy-2.0.0.dev4 → pytrendy-2.0.0.dev5}/pytrendy/io/data_loader.py +0 -0
  14. {pytrendy-2.0.0.dev4 → pytrendy-2.0.0.dev5}/pytrendy/io/plot_pytrendy.py +0 -0
  15. {pytrendy-2.0.0.dev4 → pytrendy-2.0.0.dev5}/pytrendy/io/prepare_index.py +0 -0
  16. {pytrendy-2.0.0.dev4 → pytrendy-2.0.0.dev5}/pytrendy/post_processing/__init__.py +0 -0
  17. {pytrendy-2.0.0.dev4 → pytrendy-2.0.0.dev5}/pytrendy/post_processing/segments_get.py +0 -0
  18. {pytrendy-2.0.0.dev4 → pytrendy-2.0.0.dev5}/pytrendy/post_processing/segments_refine/__init__.py +0 -0
  19. {pytrendy-2.0.0.dev4 → pytrendy-2.0.0.dev5}/pytrendy/post_processing/segments_refine/abrupt_shaving.py +0 -0
  20. {pytrendy-2.0.0.dev4 → pytrendy-2.0.0.dev5}/pytrendy/post_processing/segments_refine/artifact_cleanup.py +0 -0
  21. {pytrendy-2.0.0.dev4 → pytrendy-2.0.0.dev5}/pytrendy/post_processing/segments_refine/gradual_expand_contract.py +0 -0
  22. {pytrendy-2.0.0.dev4 → pytrendy-2.0.0.dev5}/pytrendy/post_processing/segments_refine/trend_classify.py +0 -0
  23. {pytrendy-2.0.0.dev4 → pytrendy-2.0.0.dev5}/pytrendy/post_processing/segments_refine/update_neighbours.py +0 -0
  24. {pytrendy-2.0.0.dev4 → pytrendy-2.0.0.dev5}/pytrendy/process_signals.py +0 -0
  25. {pytrendy-2.0.0.dev4 → pytrendy-2.0.0.dev5}/pytrendy/simpledtw.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pytrendy
3
- Version: 2.0.0.dev4
3
+ Version: 2.0.0.dev5
4
4
  Summary: Trend Detection in Python. Applicable for real-world industry use cases in time series.
5
5
  License: MIT License
6
6
 
@@ -126,16 +126,16 @@ The best detected trend is Down between dates 2025-05-09 - 2025-06-17
126
126
 
127
127
  Full Results:
128
128
  -------------------------------------------------------------------------------
129
- direction start end days total_change change_rank trend_class
130
- time_index
131
- 1 Up 2025-01-02 2025-01-24 22 14.013348 5 gradual
132
- 2 Down 2025-01-25 2025-02-05 11 -13.564214 6 gradual
133
- 3 Flat 2025-02-06 2025-02-09 3 -1.168831 8 NaN
134
- 4 Up 2025-02-10 2025-03-17 35 26.190476 3 gradual
135
- 5 Down 2025-03-18 2025-04-01 14 -22.721861 4 gradual
136
- 6 Up 2025-04-02 2025-05-08 36 72.611833 2 gradual
137
- 7 Down 2025-05-09 2025-06-17 39 -73.253968 1 gradual
138
- 8 Flat 2025-06-18 2025-06-30 12 3.910534 7 NaN
129
+ direction start end steps total_change change_rank trend_class
130
+ time_index
131
+ 1 Up 2025-01-02 2025-01-24 22 14.013348 5 gradual
132
+ 2 Down 2025-01-25 2025-02-05 11 -13.564214 6 gradual
133
+ 3 Flat 2025-02-06 2025-02-09 3 -1.168831 8 NaN
134
+ 4 Up 2025-02-10 2025-03-17 35 26.190476 3 gradual
135
+ 5 Down 2025-03-18 2025-04-01 14 -22.721861 4 gradual
136
+ 6 Up 2025-04-02 2025-05-08 36 72.611833 2 gradual
137
+ 7 Down 2025-05-09 2025-06-17 39 -73.253968 1 gradual
138
+ 8 Flat 2025-06-18 2025-06-30 12 3.910534 7 NaN
139
139
  -------------------------------------------------------------------------------
140
140
  ```
141
141
 
@@ -144,7 +144,7 @@ Explore the strongest uptrends:
144
144
  results.filter_segments(direction='Up', sort_by='change_rank')[:3]
145
145
  ```
146
146
 
147
- | time_index | direction | start | end | trend_class | pct_change | days | total_change | SNR | change_rank |
147
+ | time_index | direction | start | end | trend_class | pct_change | steps | total_change | SNR | change_rank |
148
148
  |---|---|---|---|---|---|---|---|---|---|
149
149
  | 7 | Up | 2025-04-02 | 2025-05-08 | gradual | 367.50% | 36 | 72.61 | 21.70 | 2 |
150
150
  | 4 | Up | 2025-02-10 | 2025-03-17 | gradual | 179.93% | 35 | 26.19 | 18.61 | 3 |
@@ -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,7 +80,7 @@ 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 | pct_change | days | total_change | SNR | change_rank |
83
+ | time_index | direction | start | end | trend_class | pct_change | steps | total_change | SNR | change_rank |
84
84
  |---|---|---|---|---|---|---|---|---|---|
85
85
  | 7 | Up | 2025-04-02 | 2025-05-08 | gradual | 367.50% | 36 | 72.61 | 21.70 | 2 |
86
86
  | 4 | Up | 2025-02-10 | 2025-03-17 | gradual | 179.93% | 35 | 26.19 | 18.61 | 3 |
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "pytrendy"
3
- version = "2.0.0.dev4"
3
+ version = "2.0.0.dev5"
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" },
@@ -23,8 +23,8 @@ class PyTrendyResults:
23
23
  List of dictionaries representing individual trend segments.
24
24
  index_type (str):
25
25
  The type of the index used for the segments (``'date'``, ``'datetime64'``,
26
- ``'integer'``, ``'float'``, or ``'string'``). Used to render summaries with the
27
- appropriate descriptor (e.g. ``'days'`` vs ``'index steps'``). Defaults to ``'date'``.
26
+ ``'integer'``, ``'float'``, or ``'string'``). Used to label segment boundaries
27
+ in ``print_summary`` (e.g. ``'dates'`` vs ``'indexes'``). Defaults to ``'date'``.
28
28
  """
29
29
  self.segments = segments
30
30
  self.trend_segments = [seg for seg in self.segments if 'trend_class' in seg] # Get segments that are trends (exclude flats and noise)
@@ -37,11 +37,11 @@ class PyTrendyResults:
37
37
 
38
38
  def set_best(self) -> None:
39
39
  """
40
- Identifies the best trend segment based on its total cumulative change, selecting the one with the lowest change rank.
41
-
42
- - `results.best` returns best based on `total_change` (cumulative sum of differences).
43
- - Identifies the best trend segment based on steepness and duration.
44
- - The segment with the lowest `change_rank` is selected as the best.
40
+ Selects the best trend segment by lowest ``change_rank``.
41
+
42
+ Sets ``self.best`` to the trend segment with the lowest ``change_rank`` (derived from
43
+ each segment's cumulative ``total_change``). Sets ``self.best`` to ``None`` when no
44
+ trend segments exist.
45
45
  """
46
46
  if len(self.trend_segments) == 0:
47
47
  self.best = None
@@ -50,10 +50,11 @@ class PyTrendyResults:
50
50
 
51
51
  def set_summary(self) -> None:
52
52
  """
53
- Computes and stores summary statistics for trend segments, including a tabular overview and counts by direction.
53
+ Computes and stores summary statistics for trend segments.
54
54
 
55
- - Computes summary statistics and stores a compact `DataFrame` of segments.
56
- - Includes counts by direction and trend class, highest total change, and a tabular view.
55
+ Sets ``self.summary`` to counts by direction and trend class, plus the highest total
56
+ change. Sets ``self.df_summary`` to a tabular overview of the segments, indexed by
57
+ ``time_index``.
57
58
  """
58
59
  summary = {}
59
60
 
@@ -77,16 +78,7 @@ class PyTrendyResults:
77
78
  # Set summary df (without extra details)
78
79
  df = pd.DataFrame(self.segments)
79
80
 
80
- unit_descriptor = {
81
- 'date': 'days',
82
- 'integer': 'index steps',
83
- 'float': 'index steps',
84
- 'string': 'index steps',
85
- }.get(self.index_type, 'days')
86
-
87
- df = df.rename({'days' : unit_descriptor}, axis = 1)
88
-
89
- cols = ['time_index', 'direction', 'start', 'end', unit_descriptor, 'total_change', 'change_rank']
81
+ cols = ['time_index', 'direction', 'start', 'end', 'steps', 'total_change', 'change_rank']
90
82
  if len(changes) > 1: # only include trend_class if atleast one trend exists
91
83
  cols += ['trend_class']
92
84
  df = df[cols]
@@ -129,11 +121,11 @@ class PyTrendyResults:
129
121
 
130
122
  def set_df(self) -> pd.DataFrame | None:
131
123
  """
132
- Converts a list of trend segments into a pandas DataFrame for easier downstream analysis and data representation.
124
+ Converts the segment list into a pandas ``DataFrame`` for downstream analysis and export.
133
125
 
134
- - Converts the segment list into a pandas `DataFrame`.
135
- - Useful for downstream analysis and export.
136
- - Alternative data representation to segments. In `dataframe` rather than `dict`
126
+ Returns:
127
+ pd.DataFrame | None: An empty ``DataFrame`` when there are no segments; otherwise
128
+ ``None``, with ``self.df`` set as a side effect.
137
129
  """
138
130
  # Exit if nothing to report on
139
131
  if len(self.segments) == 0:
@@ -156,8 +148,7 @@ class PyTrendyResults:
156
148
  Output format. `'df'` returns a DataFrame, `'dict'` returns a list of dictionaries.
157
149
 
158
150
  Returns:
159
- Union[`list`, `pd.DataFrame`]: Filtered and sorted segments in the specified format.
160
-
151
+ list | pd.DataFrame: Filtered and sorted segments in the specified format.
161
152
  """
162
153
  segments = self.segments
163
154
  if len(segments) == 0:
@@ -19,7 +19,7 @@ def analyse_segments(df: pd.DataFrame, value_col: str, segments: list[dict]) ->
19
19
 
20
20
  - Percent change (based on start/end values)
21
21
 
22
- - Duration in days
22
+ - Duration in index steps
23
23
 
24
24
  - Cumulative total change (sum of diffs)
25
25
 
@@ -40,7 +40,7 @@ def analyse_segments(df: pd.DataFrame, value_col: str, segments: list[dict]) ->
40
40
  Returns:
41
41
  list:
42
42
  A list of enhanced segment dictionaries with additional keys:
43
- - `'total_change'`, `'pct_change'`, `'mltp_change'`, `'days'`, `'SNR'`, `'change_rank'`
43
+ - `'total_change'`, `'pct_change'`, `'mltp_change'`, `'steps'`, `'SNR'`, `'change_rank'`
44
44
  """
45
45
  segments_enhanced = []
46
46
  for segment in segments:
@@ -53,11 +53,11 @@ def analyse_segments(df: pd.DataFrame, value_col: str, segments: list[dict]) ->
53
53
  segment_enhanced['pct_change'] = (float(val_end / val_start - 1) if val_start != 0 else np.nan)
54
54
  segment_enhanced['mltp_change'] = (float(val_end / val_start) if val_start != 0 else np.nan)
55
55
 
56
- # Calculate days & cumulative total change
57
- days = segment['end'] - segment['start']
58
- if days == 0:
59
- days = 1 # edge case for 1 day flat between noise spike & trend
60
- segment_enhanced['days'] = days # set days
56
+ # Calculate steps & cumulative total change
57
+ steps = segment['end'] - segment['start']
58
+ if steps == 0:
59
+ steps = 1 # edge case for 1 step flat between noise spike & trend
60
+ segment_enhanced['steps'] = steps # set steps
61
61
 
62
62
  # Calculate cumulative total change
63
63
  segment_enhanced['total_change'] = float(df_segment[value_col].diff().sum())
@@ -12,13 +12,9 @@ def group_segments(segments: list[dict]) -> list[dict]:
12
12
  """
13
13
  Groups consecutive segments with the same direction if their gap is small.
14
14
 
15
- Segments are grouped if:
16
-
17
- - They share the same `'direction'`
18
- - Their gap is ≤ `GROUPING_DISTANCE`
19
- - They are not classified as `'abrupt'`
20
-
21
- This reduces fragmentation caused by short, noisy segments.
15
+ Segments are grouped when they share the same direction, their gap is ≤
16
+ ``GROUPING_DISTANCE``, and neither is classified as abrupt. This reduces fragmentation
17
+ caused by short, noisy segments.
22
18
 
23
19
  Args:
24
20
  segments (list): List of segment dictionaries.
File without changes