pytrendy 1.4.0.dev4__tar.gz → 1.4.0.dev5__tar.gz

{pytrendy-1.4.0.dev4 → pytrendy-1.4.0.dev5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytrendy
-Version: 1.4.0.dev4
+Version: 1.4.0.dev5
 Summary: Trend Detection in Python. Applicable for real-world industry use cases in time series.
 License: MIT License
          

{pytrendy-1.4.0.dev4 → pytrendy-1.4.0.dev5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pytrendy"
-version = "1.4.0.dev4"
+version = "1.4.0.dev5"
 description = "Trend Detection in Python. Applicable for real-world industry use cases in time series."
 authors = [
     { name = "Russell Sammut Bonnici", email = "r.sammutbonnici@gmail.com" },

{pytrendy-1.4.0.dev4 → pytrendy-1.4.0.dev5}/pytrendy/detect_trends.py

@@ -8,8 +8,17 @@ from .post_processing.segments_refine import refine_segments
 from .post_processing.segments_analyse import analyse_segments
 from .io.plot_pytrendy import plot_pytrendy
 from .io.results_pytrendy import PyTrendyResults
+from .io import prepare_index
 
-def detect_trends(df: pd.DataFrame, date_col: str, value_col: str, plot=True, method_params: dict=None, plot_params: dict=None, debug: bool=False ) -> PyTrendyResults:
+
+def detect_trends(df: pd.DataFrame, 
+                  value_col: str,
+                  date_col: str|None=None,
+                  plot: bool=True, 
+                  method_params: dict|None=None, 
+                  plot_params: dict|None=None,
+                  debug: bool=False
+                  ) -> PyTrendyResults:
     """
     This is the main function that runs trend detection end-to-end.
     
@@ -29,18 +38,17 @@ def detect_trends(df: pd.DataFrame, date_col: str, value_col: str, plot=True, me
     Args:
         df (pd.DataFrame):
             Input time series data containing at least the specified `date_col` and `value_col`.
-            The `date_col` must contain datetime-like values (daily frequency recommended).
-        date_col (str):
-            Name of the column representing timestamps. This column is converted to datetime and set as the index.
         value_col (str):
             Name of the column containing the primary signal to analyse for trend detection.
+        date_col (str|None):
+            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.
         plot (bool, optional):
             If `True`, generates a matplotlib plot showing the detected trend segments over the original signal.
             Defaults to `True`.
         method_params (dict, optional):
             Optional parameters to customize detection heuristics. Supported keys:
 
-            - **abrupt_padding** (`int`): Number of days to pad around abrupt transitions. Defaults to `0`.
+            - **abrupt_padding** (`int`): Number of days to pad after abrupt transitions. Defaults to `0`.
             - **gradual_padding** (`int`): Number of days to pad after gradual trend ends. Defaults to `0`.
             - **avoid_noise** (`bool`): Whether to avoid noisy segments in trend detection. Defaults to `True`.
         plot_params (dict, optional):
@@ -64,11 +72,17 @@ def detect_trends(df: pd.DataFrame, date_col: str, value_col: str, plot=True, me
             An object encapsulating the detected segments and associated metadata.
             Use this object to access segment statistics, rankings, and export utilities.
     """
-    df = df.copy()
-    df[date_col] = pd.to_datetime(df[date_col])
-    df.set_index(date_col, inplace=True)
-    df = df[[value_col]]
-    
+    # Reject the deprecated positional order detect_trends(df, date_col, value_col).
+    if date_col is not None and prepare_index.is_legacy_positional_order(df, value_col, date_col):
+        raise TypeError(
+            "detect_trends received arguments in the deprecated (date_col, value_col) order. "
+            "Pass value_col first: detect_trends(df, value_col, date_col=...)."
+        )
+
+    # Stage the DataFrame on an internal integer index, keeping the external index
+    # values and a lookup so boundaries can be remapped back later.
+    df, external_index, index_lookup, index_type = prepare_index.prepare_index(df, date_col, value_col)
+
     if method_params is None:
         method_params = {} # Avoid mutable default argument by accepting None and constructing a new dict here
 
@@ -93,7 +107,14 @@ def detect_trends(df: pd.DataFrame, date_col: str, value_col: str, plot=True, me
     segments = get_segments(df)
     segments = refine_segments(df, value_col, segments, method_params)
     segments = analyse_segments(df, value_col, segments)
-    if plot: plot_pytrendy(df, value_col, segments, plot_params=plot_params)
 
-    results = PyTrendyResults(segments)
-    return results
+    # Translate internal segment boundaries back to the user's external index values.
+    segments = prepare_index.remap_boundaries(segments, index_lookup)
+
+    if plot:
+        # Restore the external index for plotting before rendering the segments.
+        plot_df = prepare_index.prepare_plot_frame(df, date_col, external_index, index_type)
+        plot_pytrendy(df=plot_df, value_col=value_col, segments_enhanced=segments, index_type=index_type, plot_params=plot_params)
+
+    results = PyTrendyResults(segments=segments, index_type=index_type)
+    return results

{pytrendy-1.4.0.dev4 → pytrendy-1.4.0.dev5}/pytrendy/io/plot_pytrendy.py

@@ -1,11 +1,30 @@
 """**Visualize Detected Trends Over Time Series**"""
 
 import pandas as pd
+import numpy as np
 import matplotlib.pyplot as plt
 import matplotlib.dates as mdates
 import matplotlib.patches as mpatches
 
-def plot_pytrendy(df: pd.DataFrame, value_col: str, segments_enhanced: list[dict], suppress_show: bool = False, plot_params: dict = None) -> plt.Figure:
+
+def _safe_adjacent(index, pos, offset):
+    """
+    Safely get an adjacent index value with bounds checking.
+    
+    Args:
+        index: The index to access
+        pos: Current position in the index
+        offset: Offset from current position (+1 or -1)
+        
+    Returns:
+        The adjacent index value if within bounds, None otherwise
+    """
+    new_pos = pos + offset
+    if 0 <= new_pos < len(index):
+        return index[new_pos]
+    return None
+
+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:
     """
     Visualizes detected trend segments over the original time series signal.
     
@@ -19,6 +38,8 @@ def plot_pytrendy(df: pd.DataFrame, value_col: str, segments_enhanced: list[dict
             Name of the column containing the signal to plot.
         segments_enhanced (list):
             List of segment dictionaries containing keys like `'start'`, `'end'`, `'direction'`, `'trend_class'`, and `'change_rank'`.
+        index_type (str):
+            The type of index passed by the user. Different index types require different logic. Currently Accepted Index Types are: "date", "integer", "float".
         suppress_show (bool, optional):
             If True, suppresses the automatic display of the plot with plt.show(). Defaults to False.
         plot_params (dict, optional):
@@ -78,16 +99,29 @@ def plot_pytrendy(df: pd.DataFrame, value_col: str, segments_enhanced: list[dict
     # Plot the value line
     ax.plot(df.index, df[value_col], color='black', lw=1)
 
+
     # Add shaded regions with fill_between
     ymin, ymax = ax.get_ylim()  # get plot's visible y-range
     for i, seg in enumerate(segments_enhanced):
-        start = pd.to_datetime(seg['start'])
-        end = pd.to_datetime(seg['end'])
+        
+        if index_type == "date":
+            start = pd.to_datetime(seg['start'])
+            end = pd.to_datetime(seg['end'])
+        else:
+            start = seg['start']
+            end = seg['end']
+        
         color = color_map.get(seg['direction'], 'gray')
 
         # Get context on prev seg if possible
         prev_seg = segments_enhanced[i-1] if i-1 >= 0 else None
-        prev_neighbouring = prev_seg and (pd.to_datetime(prev_seg['end']) == (start - pd.Timedelta(days=1)))
+        if index_type == "date":
+            prev_neighbouring = prev_seg and (pd.to_datetime(prev_seg['end']) == (start - pd.Timedelta(days=1)))
+        elif index_type == 'string':
+            prev_neighbouring = prev_seg and (prev_seg['end'] == df.index[df.index.get_loc(start) - 1])
+        else:
+            prev_neighbouring = prev_seg and (prev_seg['end'] == (start - 1))
+
         is_prev_not_trend = prev_seg and (not ('trend_class' in prev_seg))
 
         # Current seg context
@@ -97,18 +131,32 @@ def plot_pytrendy(df: pd.DataFrame, value_col: str, segments_enhanced: list[dict
 
         # Get context on next seg if possible
         next_seg = segments_enhanced[i+1] if i+1 < len(segments_enhanced) else None
-        next_neighbouring = next_seg and (pd.to_datetime(next_seg['start']) == (end + pd.Timedelta(days=1)))
+        if index_type == 'date':
+            next_neighbouring = next_seg and (pd.to_datetime(next_seg['start']) == (end + pd.Timedelta(days=1)))
+        elif index_type == 'string':
+            end_pos = df.index.get_loc(end)
+            next_neighbouring = next_seg and (next_seg['start'] == _safe_adjacent(df.index, end_pos, 1))
+        else:
+            next_neighbouring = next_seg and (next_seg['start'] == (end + 1))
+        
         next_seg_abrupt = next_seg and (('trend_class' in next_seg) and (next_seg['trend_class'] == 'abrupt'))
         next_seg_noise = next_seg and (next_seg['direction'] == 'Noise')
 
         # Adjust starts when appropriate
         if is_abrupt or is_noise: 
-            start = start # Conditional logic for making abrupt visually tighter
+            pass  # Keep start as-is for abrupt/noise segments
         else: 
-            new_start = start - pd.Timedelta(days=1) # Everything else displaced left start
+            if index_type == 'date':
+                new_start = start - pd.Timedelta(days=1) # Everything else displaced left start
+            elif index_type == 'string':
+                start_pos = df.index.get_loc(start)
+                new_start = _safe_adjacent(df.index, start_pos, -1)
+            else:
+                new_start = start - 1 # Everything else displaced left start
 
             # Check validity of plot start adjustment
-            value_new_start = df.loc[new_start, value_col] if new_start in df.index else None
+            value_new_start = df.loc[new_start, value_col] if new_start is not None and new_start in df.index else None
+
             value = df.loc[start, value_col]
 
             valid_up_start = (value_new_start) and (seg['direction'] == 'Up') and (value_new_start < value)
@@ -117,20 +165,38 @@ def plot_pytrendy(df: pd.DataFrame, value_col: str, segments_enhanced: list[dict
                 start = new_start # Apply left displacement only if valid
             else: 
                 # if not displaced and prev is not trend, adjust by plotting (as prev has already been drawn)
-                if is_prev_not_trend and prev_neighbouring: 
-                    prev_end = pd.to_datetime(segments_enhanced[i-1]['end'])
-                    prev_new_end = (prev_end + pd.Timedelta(days=1)).strftime('%Y-%m-%d')
-                    mask = (df.index >= prev_end) & (df.index <= prev_new_end) 
-                    prev_color = color_map.get(segments_enhanced[i-1]['direction'], 'gray')
-                    ax.fill_between(df.index[mask], ymin, ymax, color=prev_color, alpha=default_params['alpha'])
-
+                if is_prev_not_trend and prev_neighbouring:
+                    if index_type == 'date':
+                        prev_end = pd.to_datetime(segments_enhanced[i-1]['end'])
+                        prev_new_end = (prev_end + pd.Timedelta(days=1)).strftime('%Y-%m-%d')
+                    elif index_type == 'string':
+                        prev_end = segments_enhanced[i-1]['end']
+                        prev_end_pos = df.index.get_loc(prev_end)
+                        prev_new_end = _safe_adjacent(df.index, prev_end_pos, 1)
+                    else:
+                        prev_end = segments_enhanced[i-1]['end']
+                        prev_new_end = prev_end + 1
+                    
+                    if prev_new_end is not None:
+                        if index_type == 'string':
+                            mask = (np.arange(len(df)) >= df.index.get_loc(prev_end)) & (np.arange(len(df)) <= df.index.get_loc(prev_new_end))
+                        else:
+                            mask = (df.index >= prev_end) & (df.index <= prev_new_end)
+                        prev_color = color_map.get(segments_enhanced[i-1]['direction'], 'gray')
+                        ax.fill_between(df.index[mask], ymin, ymax, color=prev_color, alpha=default_params['alpha'])
 
         # Adjust ends when appropriate
         if (next_seg_abrupt or next_seg_noise) and next_neighbouring:
-            new_end = end + pd.Timedelta(days=1)
+            if index_type == 'date':
+                new_end = end + pd.Timedelta(days=1)
+            elif index_type == 'string':
+                end_pos = df.index.get_loc(end)
+                new_end = _safe_adjacent(df.index, end_pos, 1)
+            else:
+                new_end = end + 1
             
             # Check validity of plot end adjustment
-            value_new_end = df.loc[new_end, value_col] if new_end in df.index else None
+            value_new_end = df.loc[new_end, value_col] if new_end is not None and new_end in df.index else None
             value = df.loc[end, value_col]
 
             valid_up_end = (value_new_end) and (seg['direction'] == 'Up') and (value_new_end > value)
@@ -141,16 +207,34 @@ def plot_pytrendy(df: pd.DataFrame, value_col: str, segments_enhanced: list[dict
             else: 
                 # if not displaced and next is noise, adjust for next plotting round
                 if next_seg_noise and next_neighbouring: 
-                    segments_enhanced[i+1]['start'] = (pd.to_datetime(segments_enhanced[i+1]['start']) - pd.Timedelta(days=1)).strftime('%Y-%m-%d')
+                    if index_type == 'date':
+                        segments_enhanced[i+1]['start'] = (pd.to_datetime(segments_enhanced[i+1]['start']) - pd.Timedelta(days=1)).strftime('%Y-%m-%d')
+                    elif index_type == 'string':
+                        next_start_pos = df.index.get_loc(segments_enhanced[i+1]['start'])
+                        segments_enhanced[i+1]['start'] = _safe_adjacent(df.index, next_start_pos, -1)
+                    else:
+                        segments_enhanced[i+1]['start'] = (segments_enhanced[i+1]['start'] - 1)
         else: 
-            end = end
+            pass  # Keep end as-is
+
+        if index_type == 'string':
+            mask = (np.arange(len(df)) >= df.index.get_loc(start)) & (np.arange(len(df)) <= df.index.get_loc(end))
+        else:
+            mask = (df.index >= start) & (df.index <= end) 
+
 
-        mask = (df.index >= start) & (df.index <= end) 
         ax.fill_between(df.index[mask], ymin, ymax, color=color, alpha=default_params['alpha'])
         
         # Add ranking if up/down trend
         if 'change_rank' in seg and seg['direction'] in ['Up', 'Down']:
-            mid_date = start + (end - start) / 2
+            
+            if index_type in ['string']:
+                midpoint = int((df.index.get_loc(end) - df.index.get_loc(start))/2)
+                mid_date = df.index[df.index.get_loc(start) + midpoint]
+            else:
+                mid_date = start + (end - start) / 2
+
+            
             y_pos = ymax - (ymax - ymin) * 0.05
             ax.text(mid_date, y_pos, str(seg['change_rank']), fontsize=12,
                     fontweight='bold', ha='center', va='top',
@@ -158,35 +242,60 @@ def plot_pytrendy(df: pd.DataFrame, value_col: str, segments_enhanced: list[dict
             
         # Add vertical line if next seg is same & touching
         if next_seg and next_neighbouring and next_seg['direction'] == seg['direction']:
-            line_date = pd.to_datetime(seg['end'])
+            if index_type == 'date':
+                line_date = pd.to_datetime(seg['end'])
+            else:
+                line_date = seg['end']
             ax.axvline(x=line_date, color=color[5:], linewidth=0.5)
 
     # Set limits
-    first_date = df.index.min()
-    last_date = df.index.max()
+    if index_type == 'string':
+        first_date = df.index[0]
+        last_date = df.index[-1]
+    else:
+        first_date = df.index.min()
+        last_date = df.index.max()
+
     ax.set_xlim(first_date, last_date)
     ax.set_ylim(ymin, ymax)
 
-    # Major ticks: every 7 days (with labels)
-    ax.xaxis.set_major_locator(mdates.WeekdayLocator(interval=1))
-    ax.xaxis.set_major_formatter(mdates.DateFormatter('%Y-%m-%d'))
+    if index_type == 'date':
+        # Major ticks: every 7 days (with labels)
+        ax.xaxis.set_major_locator(mdates.WeekdayLocator(interval=1))
+        ax.xaxis.set_major_formatter(mdates.DateFormatter('%Y-%m-%d'))
 
-    # Minor ticks: every day (no labels, just tick marks/grid)
-    ax.xaxis.set_minor_locator(mdates.DayLocator())
+        # Minor ticks: every day (no labels, just tick marks/grid)
+        ax.xaxis.set_minor_locator(mdates.DayLocator())
 
     # Rotate major tick labels
     plt.setp(ax.get_xticklabels(), rotation=90, ha='right')
 
     # Optional: show grid lines for both
-    grid_params = default_params['grid']
-    if grid_params['visible']:
-        ax.grid(True, **{k: v for k, v in grid_params.items() if k != 'visible'})
+    grid_cfg = default_params['grid']
+    if grid_cfg.get('visible', True):
+        ax.grid(True, which=grid_cfg.get('which', 'major'),
+                color=grid_cfg.get('color', 'gray'), alpha=grid_cfg.get('alpha', 0.3))
     else:
-        ax.grid(False, which='both')
+        ax.grid(False)
+
+    if index_type == 'string':
+        ticks = ax.get_xticks()
+        labels = [t.get_text() for t in ax.get_xticklabels()]
+        n = 10
+        ax.set_xticks(ticks[::n])
+        ax.set_xticklabels(labels[::n], rotation=90, ha='center')
+
 
     ax.set_title(default_params['title'], fontsize=20)
-    ax.set_xlabel(default_params['xlabel'])
-    ax.set_ylabel(default_params['ylabel'])
+
+    if index_type == 'date':
+        ax.set_xlabel(default_params.get('xlabel', 'Date'))
+    elif index_type == 'string':
+        ax.set_xlabel(default_params.get('xlabel', 'Label'))
+    else:
+        ax.set_xlabel(default_params.get('xlabel', 'Index'))
+
+    ax.set_ylabel(default_params.get('ylabel', 'Value'))
 
     # Create custom legend handles (colored boxes)
     legend_handles = [

pytrendy-1.4.0.dev5/pytrendy/io/prepare_index.py

@@ -0,0 +1,216 @@
+"""**Index Preparation for the Detection Pipeline**
+
+PyTrendy's pipeline operates on a positional integer index internally, regardless of
+the index the user supplies. This decouples the detection logic from any particular
+time axis (daily, weekly, or otherwise) and lets the same pipeline accept datetime,
+integer, float, or string indexes.
+
+The preparation is a two-way translation:
+
+1. **Inbound** — the user's index column (``date_col``) is inspected to determine its
+   type, its values are captured, and the working DataFrame is re-staged on an internal
+   integer index (``0..n-1``). A lookup table maps internal positions back to the
+   original external index values.
+
+2. **Outbound** — once segments are detected on the internal index, their boundaries are
+   remapped back to the external index values before the results are returned or plotted.
+
+The functions in this module encapsulate that translation so ``detect_trends`` stays
+focused on orchestrating the pipeline.
+"""
+
+import warnings
+from copy import deepcopy
+
+import numpy as np
+import pandas as pd
+
+
+def detect_index_type(values) -> str:
+    """
+    Detect the index type from a Series or Index of values.
+
+    Args:
+        values: A pandas Series or Index of index values.
+
+    Returns:
+        str: Index type (``'date'``, ``'datetime64'``, ``'integer'``, ``'float'``, or ``'string'``).
+    """
+    if pd.api.types.is_string_dtype(values):
+        with warnings.catch_warnings():
+            warnings.filterwarnings(
+                "ignore",
+                message="Could not infer format.*"
+            )
+            parsed = pd.to_datetime(values, errors="coerce")
+
+        if parsed.notna().all():
+            return "date"
+        else:
+            return "string"
+    elif pd.api.types.is_datetime64_any_dtype(values):
+        return "datetime64"
+    elif pd.api.types.is_integer_dtype(values):
+        return "integer"
+    elif pd.api.types.is_float_dtype(values):
+        return "float"
+    else:
+        raise NotImplementedError(f"unimplemented dtype {values.dtype}")
+
+
+def is_legacy_positional_order(df: pd.DataFrame, value_col: str, date_col: str) -> bool:
+    """
+    Detect the deprecated ``detect_trends(df, date_col, value_col)`` positional order.
+
+    Under the old API the first positional column was always date-like (it was passed
+    through ``pd.to_datetime``) and the second was the numeric value column. So if the
+    column currently bound as ``value_col`` is date-like while ``date_col`` is numeric,
+    the caller almost certainly used the legacy order.
+
+    Args:
+        df (pd.DataFrame): Input DataFrame.
+        value_col (str): Column currently bound as the value/signal column.
+        date_col (str): Column currently bound as the date/index column.
+
+    Returns:
+        bool: True if the arguments appear to be in the legacy (date_col, value_col) order.
+    """
+    value_dtype = df[value_col].dtype
+    date_dtype = df[date_col].dtype
+
+    value_is_datelike = pd.api.types.is_datetime64_any_dtype(value_dtype) or (
+        pd.api.types.is_string_dtype(value_dtype)
+        and pd.to_datetime(df[value_col], errors="coerce").notna().all()
+    )
+    date_is_numeric = pd.api.types.is_numeric_dtype(date_dtype)
+
+    return value_is_datelike and date_is_numeric
+
+
+def build_index_lookup(external_index) -> dict:
+    """
+    Build a lookup mapping internal integer positions to external index values.
+
+    Args:
+        external_index: The original index values captured before staging.
+
+    Returns:
+        dict: Mapping from internal position (``int``) to external index value.
+    """
+    internal_index = np.arange(len(external_index))
+    return dict(zip(internal_index, np.asarray(external_index)))
+
+
+def prepare_index(df: pd.DataFrame, date_col: str | None, value_col: str) -> tuple:
+    """
+    Prepare the internal index framework used by the pipeline.
+
+    Detects the index type, captures the external index values, builds the
+    internal integer index and its lookup, and stages the working DataFrame
+    on a dedicated scratch column so the user's columns are never clobbered.
+
+    Args:
+        df (pd.DataFrame): Input time series DataFrame.
+        date_col (str|None): Name of the column representing the external index.
+        value_col (str): Name of the signal column.
+
+    Returns:
+        tuple: ``(df, external_index, index_lookup, index_type)`` where ``df`` is
+        the internal-indexed working copy, ``external_index`` holds the original
+        index values, ``index_lookup`` maps internal to external index values, and
+        ``index_type`` is the detected index type.
+    """
+    df = df.copy()
+
+    if date_col is not None:
+        index_type = detect_index_type(df[date_col])
+        index_values = df[date_col]
+
+        # Sort sortable index types ascending so the internal positional index
+        # reflects chronological (date) / numeric order. Non-sortable types
+        # ('string') keep their given order.
+        if index_type in ('date', 'datetime64', 'integer', 'float'):
+            sort_key = pd.to_datetime(index_values) if index_type == 'date' else index_values
+            df = df.iloc[np.asarray(sort_key).argsort(kind='stable')].reset_index(drop=True)
+        external_index = df[date_col].copy()
+
+        if index_type == 'string':
+            warnings.warn(
+                f"Attempting to cast {date_col} to date failed, "
+                "treating as string lookup.",
+                UserWarning,
+                stacklevel=2,
+            )
+    else:
+        # No date column: fall back to the DataFrame's own index.
+        index_type = detect_index_type(df.index)
+        index_values = df.index
+
+        # Sort sortable index types ascending; non-sortable ('string') and the
+        # default integer index keep their given order.
+        if index_type in ('datetime64', 'integer', 'float'):
+            df = df.sort_index(kind='stable')
+        elif index_type == 'date':  # string-date index: sort chronologically, keep labels
+            order = np.asarray(pd.to_datetime(df.index)).argsort(kind='stable')
+            df = df.iloc[order]
+        external_index = np.asarray(df.index)
+
+    if index_type == 'float' and pd.isna(index_values).any():
+        warnings.warn(
+            "float index contains NaN values; they sort to the end and may "
+            "produce unexpected segment boundaries.",
+            UserWarning,
+            stacklevel=2,
+        )
+
+    index_lookup = build_index_lookup(external_index)
+
+    # Use a dedicated scratch column name to avoid clobbering user's columns
+    _pytrendy_idx = '_pytrendy_idx'
+    df[_pytrendy_idx] = np.arange(len(df))
+    df.set_index(_pytrendy_idx, inplace=True)
+    df = df[[value_col]]
+
+    return df, external_index, index_lookup, index_type
+
+
+def remap_boundaries(segments: list[dict], index_lookup: dict) -> list[dict]:
+    """
+    Remap internal segment boundaries back to external index values.
+
+    Args:
+        segments (list): Segment list with internal index boundaries.
+        index_lookup (dict): Mapping from internal to external index values.
+
+    Returns:
+        list: A new segment list with boundaries expressed in external index values.
+    """
+    remapped = deepcopy(segments)
+    for segment in remapped:
+        segment['start'] = index_lookup[segment['start']]
+        segment['end'] = index_lookup[segment['end']]
+    return remapped
+
+
+def prepare_plot_frame(df: pd.DataFrame, date_col: str | None, external_index, index_type: str) -> pd.DataFrame:
+    """
+    Restore the external index onto the working DataFrame for plotting.
+
+    Args:
+        df (pd.DataFrame): Internal-indexed working DataFrame.
+        date_col (str|None): Name of the external index column.
+        external_index: External index values captured before staging.
+        index_type (str): Detected index type.
+
+    Returns:
+        pd.DataFrame: DataFrame with the external index restored for plotting.
+    """
+    if index_type == 'date':
+        external_index = pd.to_datetime(external_index)
+
+    # Use a sentinel name when no date column was supplied, so the restored
+    # index has a meaningful label rather than a None-named column.
+    index_name = date_col if date_col is not None else '_index'
+    df[index_name] = np.asarray(external_index)
+    df.set_index(index_name, inplace=True)
+    return df

{pytrendy-1.4.0.dev4 → pytrendy-1.4.0.dev5}/pytrendy/io/results_pytrendy.py

@@ -14,17 +14,23 @@ class PyTrendyResults:
     enhanced metrics such as rankings and signal-to-noise ratios.
     """
 
-    def __init__(self, segments: list[dict]) -> None:
+    def __init__(self, segments: list[dict], index_type: str = 'date') -> None:
         """
         Initializes the results object with a list of segments.
 
         Args:
             segments (list):
                 List of dictionaries representing individual trend segments.
+            index_type (str):
+                The type of the index used for the segments (``'date'``, ``'datetime64'``,
+                ``'integer'``, ``'float'``, or ``'string'``). Used to render summaries with the
+                appropriate descriptor (e.g. ``'days'`` vs ``'index steps'``). Defaults to ``'date'``.
         """
         self.segments = segments
         self.trend_segments = [seg for seg in self.segments if 'trend_class' in seg] # Get segments that are trends (exclude flats and noise)
         
+        self.index_type = index_type
+
         self.set_best()
         self.set_df()
         self.set_summary()
@@ -70,7 +76,17 @@ class PyTrendyResults:
 
         # Set summary df (without extra details)
         df = pd.DataFrame(self.segments)
-        cols = ['time_index', 'direction', 'start', 'end', 'days', 'total_change', 'change_rank']
+
+        unit_descriptor = {
+            'date': 'days',
+            'integer': 'index steps',
+            'float': 'index steps',
+            'string': 'index steps',
+        }.get(self.index_type, 'days')
+
+        df = df.rename({'days' : unit_descriptor}, axis = 1)
+
+        cols = ['time_index', 'direction', 'start', 'end', unit_descriptor, 'total_change', 'change_rank']
         if len(changes) > 1:  #  only include trend_class if atleast one trend exists
             cols += ['trend_class']
         df = df[cols]
@@ -94,11 +110,17 @@ class PyTrendyResults:
         noise = self.summary['direction_counts']['Noise'] if 'Noise' in self.summary['direction_counts'] else 0 
         print(f'Detected: \n- {uptrends} Uptrends. \n- {downtrends} Downtrends.\n- {flats} Flats.\n- {noise} Noise.\n')
 
+        descriptor = 'dates'
+        if self.index_type in ['integer', 'float']:
+            descriptor = 'indexes'
+        elif self.index_type in ['string']:
+            descriptor = 'labels'
+
         if len(self.filter_segments(direction='Up/Down')) == 0:
             print('Detected no trends...')
             return
         else:
-            print(f'The best detected trend is {self.best["direction"]} between dates {self.best["start"]} - {self.best["end"]}\n')
+            print(f'The best detected trend is {self.best["direction"]} between {descriptor} {self.best["start"]} - {self.best["end"]}\n')
 
         print('Full Results:')
         print('-------------------------------------------------------------------------------\n', 

{pytrendy-1.4.0.dev4 → pytrendy-1.4.0.dev5}/pytrendy/post_processing/segments_analyse.py

@@ -53,7 +53,7 @@ def analyse_segments(df: pd.DataFrame, value_col: str, segments: list[dict]) ->
         segment_enhanced['pct_change'] = (float(val_end / val_start - 1) if val_start != 0 else np.nan)
 
         # Calculate days & cumulative total change
-        days = (pd.to_datetime(segment['end']) - pd.to_datetime(segment['start'])).days
+        days = segment['end'] - segment['start']
         if days == 0: 
             days = 1 # edge case for 1 day flat between noise spike & trend
         segment_enhanced['days'] = days # set days