pytrendy 2.0.0.dev4__py3-none-any.whl → 2.0.0.dev5__py3-none-any.whl

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.
@@ -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.
@@ -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 |
@@ -6,20 +6,20 @@ pytrendy/io/data/series_synthetic.csv,sha256=NHsAKmNu5uWYkOXg_uAJ3xZKEEFaXYsjT4d
6
6
  pytrendy/io/data_loader.py,sha256=p49OVeFw-39fc0BDD32w8s90N0UZnO3gHz_1hby4evE,1136
7
7
  pytrendy/io/plot_pytrendy.py,sha256=u8DVDefHRj4i8qXfm4OGMBFH7OVitw6FpEfqHaMTlro,16943
8
8
  pytrendy/io/prepare_index.py,sha256=QTquO_iktcx6UKRduVfdT5oTBlHJtStGMJnniBG4f-Q,8345
9
- pytrendy/io/results_pytrendy.py,sha256=h5Frarg6FpCORHP3s7a7t85lBkv8A0n0OqXc3yFFyNw,8384
9
+ pytrendy/io/results_pytrendy.py,sha256=tEF3H2jfQaosqNJxC1PPtO1-mTwE1gdk9K48pDVTJ_s,7858
10
10
  pytrendy/post_processing/__init__.py,sha256=bvn1pcxRAoyq5C1P7v5gnb6HiPzteyxT3y9dOY8Pemc,2569
11
- pytrendy/post_processing/segments_analyse.py,sha256=qkZHWQTl1LRz0W81VQdvO9yPgDwbp7Gj4wFZeOE6Rw4,3188
11
+ pytrendy/post_processing/segments_analyse.py,sha256=5HbEpLh2MFoVAxJZvvE8f5L1zuGTMSmG7faHpbuL8Pw,3204
12
12
  pytrendy/post_processing/segments_get.py,sha256=A7fc2BPkEPTOUCDX7R3eX-6mWmQV8YKIS-I70ji7Ev0,2552
13
13
  pytrendy/post_processing/segments_refine/__init__.py,sha256=Mcv4xfV442j1TE3udmRRyTjKNFrSE8brcNlzWMJvkMc,3501
14
14
  pytrendy/post_processing/segments_refine/abrupt_shaving.py,sha256=5e0dS0yQ51wT2Hvogm0MdGHjq-3F7aG7jutygmu1VM4,7378
15
15
  pytrendy/post_processing/segments_refine/artifact_cleanup.py,sha256=1M3NyGmrcY2aTOdXamHsEzA5xfr5mTvlOUaaIdXj0wY,17471
16
16
  pytrendy/post_processing/segments_refine/gradual_expand_contract.py,sha256=dZiHa-wFonl85zG7-JhziUKGeLFyOAYI45PpdLX6HXE,7733
17
- pytrendy/post_processing/segments_refine/segment_grouping.py,sha256=FIfXzBF9ZnzDmbYjjpioU7mT14FucVNrvQtwGa1CZww,2649
17
+ pytrendy/post_processing/segments_refine/segment_grouping.py,sha256=72cYdc-l-QlRrvrue8VO_O6XChpSHZKMauZYOk0OUwk,2621
18
18
  pytrendy/post_processing/segments_refine/trend_classify.py,sha256=aJwutjfMz64t7fcOGqbsgKpSt5FDuEMWIHtls-s9TE4,3211
19
19
  pytrendy/post_processing/segments_refine/update_neighbours.py,sha256=4MqOEllUADv8W5nBwfGL3NZNlM9cEYwh3ohb3VWIWU8,3784
20
20
  pytrendy/process_signals.py,sha256=eE7gpnagkNuIcWDKxMvq8tdiv15XrK7rbOqcF_Tdg3c,11564
21
21
  pytrendy/simpledtw.py,sha256=tGsbnRgh4VqnA5XVxPCfYHnJXjvLlVHVGHQ4cGX4eUw,2945
22
- pytrendy-2.0.0.dev4.dist-info/METADATA,sha256=GzFyDr0G5jFu4rGPFb9MiOVwHSBjlDAVKKhXKt2BXVE,8684
23
- pytrendy-2.0.0.dev4.dist-info/WHEEL,sha256=EGEvSphFYqXKs23-kQBeyNoJP1nrT8ZJKQoi5p5DYL8,88
24
- pytrendy-2.0.0.dev4.dist-info/licenses/LICENSE,sha256=I00f93GihSG6Gqqw3qerxzO53oj_crz0sjynXCiHX_0,1079
25
- pytrendy-2.0.0.dev4.dist-info/RECORD,,
22
+ pytrendy-2.0.0.dev5.dist-info/METADATA,sha256=Cim7-_T6aFiqQDIET2O6zp3q8C4oHMkE7TiUGLeRI1w,8695
23
+ pytrendy-2.0.0.dev5.dist-info/WHEEL,sha256=EGEvSphFYqXKs23-kQBeyNoJP1nrT8ZJKQoi5p5DYL8,88
24
+ pytrendy-2.0.0.dev5.dist-info/licenses/LICENSE,sha256=I00f93GihSG6Gqqw3qerxzO53oj_crz0sjynXCiHX_0,1079
25
+ pytrendy-2.0.0.dev5.dist-info/RECORD,,