pytrendclust 0.1.0__tar.gz

pytrendclust-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrey Ferubko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pytrendclust-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: pytrendclust
+Version: 0.1.0
+Summary: Trend clustering of time series with an adaptive number of clusters: split a series into rising, falling and flat runs with an exponentially growing penalty on change points
+Keywords: time-series,clustering,trend,change-point,segmentation,piecewise-linear,regression
+Author: Andrey Ferubko
+Author-email: Andrey Ferubko <ferubko1999@yandex.ru>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.1 ; extra == 'pandas'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/89605502155/pytrendclust
+Project-URL: Repository, https://github.com/89605502155/pytrendclust
+Project-URL: Documentation, https://github.com/89605502155/pytrendclust#readme
+Project-URL: Issues, https://github.com/89605502155/pytrendclust/issues
+Provides-Extra: pandas
+Description-Content-Type: text/markdown
+
+# pytrendclust
+
+[![PyPI](https://img.shields.io/pypi/v/pytrendclust)](https://pypi.org/project/pytrendclust/)
+[![Python](https://img.shields.io/pypi/pyversions/pytrendclust)](https://pypi.org/project/pytrendclust/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/89605502155/pytrendclust/blob/main/LICENSE)
+
+Source code: <https://github.com/89605502155/pytrendclust>
+
+Trend clustering of time series with an **adaptive number of clusters**.
+
+`pytrendclust` splits a series into consecutive runs that rise, fall or stay
+flat. You do not pass the number of clusters. It is chosen by a penalised
+least-squares criterion in which every extra change point costs exponentially
+more than the previous one. Real changes of direction are found, and noise is
+not mistaken for a trend.
+
+Typical use: keep only the most recent regime of a series as the training set
+for a regression model. For example, a series of RAM consumption first falls
+and then grows. Fitting a line to the whole history mixes two regimes; fitting
+it to the last cluster does not.
+
+```python
+from pytrendclust import TrendClusterer
+
+y = [10, 9, 8, 7, 6, 5, 4, 5, 6, 7]
+
+result = TrendClusterer().fit(y).result_
+print(result.summary())
+# 10 points, 1 change point(s), noise std 0.27
+#   #0: [0, 7)    7 pts  down  slope -1
+#   #1: [7, 10)    3 pts  up    slope +1
+
+t_recent, y_recent = result.select()       # points of the last (newest) cluster
+result.export("result.json")               # or "points.csv"
+```
+
+A "picket fence" `5, 6, 5, 6, ...` is one flat cluster, not ten tiny trends:
+
+```python
+>>> from pytrendclust import cluster_trends
+>>> cluster_trends([5, 6] * 5).summary()
+'10 points, 0 change point(s), noise std 1.211\n  #0: [0, 10)   10 pts  flat  slope +0.0303'
+>>> cluster_trends([5, 6] * 5, penalty="none").n_change_points   # no regularisation
+2
+
+```
+
+## Installation
+
+```bash
+pip install pytrendclust            # numpy only
+pip install "pytrendclust[pandas]"  # + DataFrame export
+```
+
+## Method
+
+For every possible number of change points `K`, a dynamic programme finds the
+exact partition into `K + 1` runs with the smallest total squared error of
+per-run least-squares lines, `SSE(K)`. The clusterer then picks
+
+```
+K* = argmin_K  SSE(K) + sigma² · pen(K)
+pen(K) = c · (exp(g·K) − 1) / (exp(g) − 1)
+```
+
+* `c` (`penalty_scale`): price of the first change point in noise variances.
+  The default is `5·ln(n)`.
+* `g` (`penalty_growth`, default 0.5): each next change point costs `e^g`
+  times more than the previous one. `g = 0` gives the classic linear penalty.
+* `sigma` (`noise_std`): noise level. By default it is estimated robustly
+  from second differences of the series, which cancel any linear trend. This
+  makes the result independent of units: bytes and gigabytes give the same
+  clusters.
+
+The search over `K` stops as soon as the penalty alone exceeds the best value
+found. The exponential penalty makes this happen after a few steps. The
+solution is the global optimum of the criterion; the test suite checks it
+against brute-force enumeration.
+
+Each cluster is labelled `up`, `down` or `flat` with a t-test on its slope:
+`|slope| / se(slope) < flat_threshold` (default 2) means `flat`.
+
+## API
+
+| Object | Purpose |
+|---|---|
+| `TrendClusterer(**params)` | set parameters; `fit(y, t=None)`, `fit_predict`, `get_params`, `set_params` |
+| `cluster_trends(y, t=None, **params)` | one-call shortcut returning the result |
+| `TrendClusteringResult` | `segments`, `change_points`, `labels`, `trends`, `fitted`, `last_segment`, `select()`, `indices()`, `criterion` |
+| export | `to_dict()`, `to_json(path)`, `to_csv(path)`, `to_dataframe()`, `export(path)`; `from_dict`, `from_json` |
+
+Parameters: `penalty` (`"exponential"`, `"linear"`, `"none"`, or a callable
+`f(K, n, sigma²)`), `penalty_scale`, `penalty_growth`, `min_size` (default 3),
+`max_change_points`, `noise_std`, `flat_threshold`.
+
+`result.criterion` lists `SSE(K)`, the penalty and their sum for every `K` the
+search evaluated. Use it to justify the chosen number of clusters.
+
+Complexity is `O(K · n²)` time and `O(K · n)` memory: about 0.4 s for 1000
+points and 6 s for 5000.
+
+## Кратко по-русски
+
+Трендовая кластеризация временного ряда с адаптивным числом классов. Ряд
+делится на участки роста, спада и плато. Число точек разладки выбирается
+автоматически: к ошибке модели добавляется штраф, растущий экспоненциально с
+каждой новой точкой. Так шумовые колебания («заборчик») не принимаются за смену
+тренда. `result.select()` возвращает точки последнего, самого свежего участка.
+На них обучается регрессия.
+
+## Development
+
+```bash
+git clone https://github.com/89605502155/pytrendclust.git
+cd pytrendclust
+uv sync --all-extras
+uv run pytest
+uv run ruff check src tests && uv run ruff format --check src tests
+uv run mypy
+uv build
+```
+
+## License
+
+MIT, see [LICENSE](https://github.com/89605502155/pytrendclust/blob/main/LICENSE).

pytrendclust-0.1.0/README.md

@@ -0,0 +1,125 @@
+# pytrendclust
+
+[![PyPI](https://img.shields.io/pypi/v/pytrendclust)](https://pypi.org/project/pytrendclust/)
+[![Python](https://img.shields.io/pypi/pyversions/pytrendclust)](https://pypi.org/project/pytrendclust/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/89605502155/pytrendclust/blob/main/LICENSE)
+
+Source code: <https://github.com/89605502155/pytrendclust>
+
+Trend clustering of time series with an **adaptive number of clusters**.
+
+`pytrendclust` splits a series into consecutive runs that rise, fall or stay
+flat. You do not pass the number of clusters. It is chosen by a penalised
+least-squares criterion in which every extra change point costs exponentially
+more than the previous one. Real changes of direction are found, and noise is
+not mistaken for a trend.
+
+Typical use: keep only the most recent regime of a series as the training set
+for a regression model. For example, a series of RAM consumption first falls
+and then grows. Fitting a line to the whole history mixes two regimes; fitting
+it to the last cluster does not.
+
+```python
+from pytrendclust import TrendClusterer
+
+y = [10, 9, 8, 7, 6, 5, 4, 5, 6, 7]
+
+result = TrendClusterer().fit(y).result_
+print(result.summary())
+# 10 points, 1 change point(s), noise std 0.27
+#   #0: [0, 7)    7 pts  down  slope -1
+#   #1: [7, 10)    3 pts  up    slope +1
+
+t_recent, y_recent = result.select()       # points of the last (newest) cluster
+result.export("result.json")               # or "points.csv"
+```
+
+A "picket fence" `5, 6, 5, 6, ...` is one flat cluster, not ten tiny trends:
+
+```python
+>>> from pytrendclust import cluster_trends
+>>> cluster_trends([5, 6] * 5).summary()
+'10 points, 0 change point(s), noise std 1.211\n  #0: [0, 10)   10 pts  flat  slope +0.0303'
+>>> cluster_trends([5, 6] * 5, penalty="none").n_change_points   # no regularisation
+2
+
+```
+
+## Installation
+
+```bash
+pip install pytrendclust            # numpy only
+pip install "pytrendclust[pandas]"  # + DataFrame export
+```
+
+## Method
+
+For every possible number of change points `K`, a dynamic programme finds the
+exact partition into `K + 1` runs with the smallest total squared error of
+per-run least-squares lines, `SSE(K)`. The clusterer then picks
+
+```
+K* = argmin_K  SSE(K) + sigma² · pen(K)
+pen(K) = c · (exp(g·K) − 1) / (exp(g) − 1)
+```
+
+* `c` (`penalty_scale`): price of the first change point in noise variances.
+  The default is `5·ln(n)`.
+* `g` (`penalty_growth`, default 0.5): each next change point costs `e^g`
+  times more than the previous one. `g = 0` gives the classic linear penalty.
+* `sigma` (`noise_std`): noise level. By default it is estimated robustly
+  from second differences of the series, which cancel any linear trend. This
+  makes the result independent of units: bytes and gigabytes give the same
+  clusters.
+
+The search over `K` stops as soon as the penalty alone exceeds the best value
+found. The exponential penalty makes this happen after a few steps. The
+solution is the global optimum of the criterion; the test suite checks it
+against brute-force enumeration.
+
+Each cluster is labelled `up`, `down` or `flat` with a t-test on its slope:
+`|slope| / se(slope) < flat_threshold` (default 2) means `flat`.
+
+## API
+
+| Object | Purpose |
+|---|---|
+| `TrendClusterer(**params)` | set parameters; `fit(y, t=None)`, `fit_predict`, `get_params`, `set_params` |
+| `cluster_trends(y, t=None, **params)` | one-call shortcut returning the result |
+| `TrendClusteringResult` | `segments`, `change_points`, `labels`, `trends`, `fitted`, `last_segment`, `select()`, `indices()`, `criterion` |
+| export | `to_dict()`, `to_json(path)`, `to_csv(path)`, `to_dataframe()`, `export(path)`; `from_dict`, `from_json` |
+
+Parameters: `penalty` (`"exponential"`, `"linear"`, `"none"`, or a callable
+`f(K, n, sigma²)`), `penalty_scale`, `penalty_growth`, `min_size` (default 3),
+`max_change_points`, `noise_std`, `flat_threshold`.
+
+`result.criterion` lists `SSE(K)`, the penalty and their sum for every `K` the
+search evaluated. Use it to justify the chosen number of clusters.
+
+Complexity is `O(K · n²)` time and `O(K · n)` memory: about 0.4 s for 1000
+points and 6 s for 5000.
+
+## Кратко по-русски
+
+Трендовая кластеризация временного ряда с адаптивным числом классов. Ряд
+делится на участки роста, спада и плато. Число точек разладки выбирается
+автоматически: к ошибке модели добавляется штраф, растущий экспоненциально с
+каждой новой точкой. Так шумовые колебания («заборчик») не принимаются за смену
+тренда. `result.select()` возвращает точки последнего, самого свежего участка.
+На них обучается регрессия.
+
+## Development
+
+```bash
+git clone https://github.com/89605502155/pytrendclust.git
+cd pytrendclust
+uv sync --all-extras
+uv run pytest
+uv run ruff check src tests && uv run ruff format --check src tests
+uv run mypy
+uv build
+```
+
+## License
+
+MIT, see [LICENSE](https://github.com/89605502155/pytrendclust/blob/main/LICENSE).

pytrendclust-0.1.0/pyproject.toml

@@ -0,0 +1,112 @@
+[project]
+name = "pytrendclust"
+version = "0.1.0"
+description = "Trend clustering of time series with an adaptive number of clusters: split a series into rising, falling and flat runs with an exponentially growing penalty on change points"
+readme = "README.md"
+authors = [
+    { name = "Andrey Ferubko", email = "ferubko1999@yandex.ru" }
+]
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "time-series",
+    "clustering",
+    "trend",
+    "change-point",
+    "segmentation",
+    "piecewise-linear",
+    "regression",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Typing :: Typed",
+]
+dependencies = [
+    "numpy>=1.26",
+]
+
+[project.optional-dependencies]
+pandas = [
+    "pandas>=2.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/89605502155/pytrendclust"
+Repository = "https://github.com/89605502155/pytrendclust"
+Documentation = "https://github.com/89605502155/pytrendclust#readme"
+Issues = "https://github.com/89605502155/pytrendclust/issues"
+
+[build-system]
+requires = ["uv_build>=0.11.9,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "hypothesis>=6.168.5",
+    "mypy>=2.4.0",
+    "pytest>=9.1.1",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.16.10",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "N", "UP", "B", "A", "C4", "EM", "ISC", "PIE", "PT", "RET", "SIM",
+          "TID", "T20", "PERF", "PL", "RUF", "S"]
+ignore = [
+    "PLR0913", # too many arguments: the constructor mirrors the documented parameters
+    "PLR2004", # magic values
+    "PLC0415", # imports inside functions keep optional dependencies optional
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101", "PLR2004", "PLC0415", "N802", "S311", "RUF001", "RUF003"]
+"examples/**" = ["T20", "S101", "RUF001", "RUF003"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["pytrendclust"]
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests", "src", "README.md"]
+addopts = ["-ra", "--strict-markers", "--strict-config", "--doctest-modules", "--doctest-glob=README.md", "--import-mode=importlib"]
+doctest_optionflags = ["NORMALIZE_WHITESPACE", "ELLIPSIS"]
+filterwarnings = ["error"]
+
+[tool.coverage.run]
+source = ["pytrendclust"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+exclude_also = ["if TYPE_CHECKING:"]
+
+[tool.mypy]
+python_version = "3.11"
+files = ["src/pytrendclust"]
+strict = true
+warn_unused_ignores = true
+
+[[tool.mypy.overrides]]
+module = ["pandas", "pandas.*"]
+ignore_missing_imports = true

pytrendclust-0.1.0/src/pytrendclust/__init__.py

@@ -0,0 +1,37 @@
+"""Trend clustering of time series with an adaptive number of clusters.
+
+Splits a series into consecutive rising, falling and flat runs, choosing the
+number of change points by a penalised least-squares criterion whose penalty
+grows exponentially with every extra change point.
+
+>>> from pytrendclust import cluster_trends
+>>> result = cluster_trends([10, 9, 8, 7, 6, 5, 4, 5, 6, 7])
+>>> result.last_segment.trend.value, result.indices().tolist()
+('up', [7, 8, 9])
+"""
+
+from pytrendclust.clusterer import TrendClusterer, cluster_trends
+from pytrendclust.penalty import (
+    PenaltyFunc,
+    default_scale,
+    estimate_noise_std,
+    exponential_penalty,
+    linear_penalty,
+)
+from pytrendclust.result import CriterionRow, Segment, Trend, TrendClusteringResult
+
+__all__ = [
+    "CriterionRow",
+    "PenaltyFunc",
+    "Segment",
+    "Trend",
+    "TrendClusterer",
+    "TrendClusteringResult",
+    "cluster_trends",
+    "default_scale",
+    "estimate_noise_std",
+    "exponential_penalty",
+    "linear_penalty",
+]
+
+__version__ = "0.1.0"

pytrendclust-0.1.0/src/pytrendclust/_cost.py

@@ -0,0 +1,70 @@
+"""Least-squares cost of fitting a straight line to a contiguous run of points.
+
+Prefix sums make the residual sum of squares (SSE) of any run ``[start, stop)``
+an O(1) computation, which is what keeps the dynamic programme in
+:mod:`pytrendclust._dp` affordable.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+from numpy.typing import NDArray
+
+FloatArray = NDArray[np.float64]
+IntArray = NDArray[np.int64]
+
+
+@dataclass(frozen=True, slots=True)
+class LineFit:
+    """Ordinary least-squares line ``y = intercept + slope * t`` over one run."""
+
+    slope: float
+    intercept: float
+    sse: float
+    #: Centred sum of squares of ``t``; zero when the run has a single point.
+    stt: float
+
+
+def fit_line(t: FloatArray, y: FloatArray) -> LineFit:
+    """Fit a straight line to ``(t, y)`` by ordinary least squares."""
+    t_mean = float(t.mean())
+    y_mean = float(y.mean())
+    dt = t - t_mean
+    dy = y - y_mean
+    stt = float(dt @ dt)
+    slope = float(dt @ dy) / stt if stt > 0.0 else 0.0
+    intercept = y_mean - slope * t_mean
+    residual = dy - slope * dt
+    return LineFit(slope=slope, intercept=intercept, sse=float(residual @ residual), stt=stt)
+
+
+class LinearCost:
+    """SSE of the best straight line on any run ``[start, stop)`` of a series."""
+
+    def __init__(self, t: FloatArray, y: FloatArray) -> None:
+        # Centring both axes keeps the prefix-sum differences well conditioned.
+        tc = t - t.mean()
+        yc = y - y.mean()
+        zero = np.zeros(1)
+        self._n = np.arange(len(y) + 1, dtype=np.float64)
+        self._st = np.concatenate([zero, np.cumsum(tc)])
+        self._sy = np.concatenate([zero, np.cumsum(yc)])
+        self._stt = np.concatenate([zero, np.cumsum(tc * tc)])
+        self._sty = np.concatenate([zero, np.cumsum(tc * yc)])
+        self._syy = np.concatenate([zero, np.cumsum(yc * yc)])
+        #: Total sum of squares of the series around its mean — the cost scale.
+        self.total_ss = float(self._syy[-1])
+
+    def sse(self, starts: IntArray, stop: int) -> FloatArray:
+        """SSE of the runs ``[s, stop)`` for every ``s`` in ``starts`` (vectorised)."""
+        n = self._n[stop] - self._n[starts]
+        st = self._st[stop] - self._st[starts]
+        sy = self._sy[stop] - self._sy[starts]
+        ctt = (self._stt[stop] - self._stt[starts]) - st * st / n
+        cty = (self._sty[stop] - self._sty[starts]) - st * sy / n
+        cyy = (self._syy[stop] - self._syy[starts]) - sy * sy / n
+        explained = np.divide(cty * cty, ctt, out=np.zeros_like(ctt), where=ctt > 0.0)
+        sse: FloatArray = np.maximum(cyy - explained, 0.0)
+        return sse

pytrendclust-0.1.0/src/pytrendclust/_dp.py

@@ -0,0 +1,80 @@
+"""Exact penalised segmentation by dynamic programming over the number of segments.
+
+For every number of change points ``K`` the programme finds the partition of the
+series into ``K + 1`` runs with the smallest total SSE (the "segment
+neighbourhood" recursion).  The penalty may be any non-decreasing function of
+``K`` — in particular an exponential one, which an additive per-segment
+recursion such as PELT cannot express.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+import numpy as np
+
+from pytrendclust._cost import IntArray, LinearCost
+from pytrendclust.result import CriterionRow
+
+
+@dataclass(frozen=True, slots=True)
+class Segmentation:
+    change_points: tuple[int, ...]
+    criterion: tuple[CriterionRow, ...]
+
+
+def segment(
+    cost: LinearCost,
+    n: int,
+    min_size: int,
+    max_change_points: int,
+    penalty: Callable[[int], float],
+) -> Segmentation:
+    """Return the change points minimising ``SSE(K) + penalty(K)``.
+
+    Change points are indices ``c`` such that a new segment starts at ``c``.
+    The search over ``K`` stops early once ``penalty(K)`` alone exceeds the best
+    objective seen so far: SSE is non-negative and the penalty non-decreasing,
+    so no larger ``K`` can win.
+    """
+    inf = np.inf
+    all_stops = np.arange(n + 1)
+    # best[j]: minimal SSE of splitting the prefix [0, j) into k + 1 segments.
+    best = np.full(n + 1, inf)
+    best[min_size:] = [cost.sse(np.array([0]), j)[0] for j in all_stops[min_size:]]
+    back: list[IntArray] = []
+    tie_tol = 1e-10 * cost.total_ss
+
+    criterion = [CriterionRow(0, float(best[n]), penalty(0))]
+    best_k, best_obj = 0, criterion[0].objective
+
+    for k in range(1, max_change_points + 1):
+        pen = penalty(k)
+        if pen >= best_obj:
+            break
+        new = np.full(n + 1, inf)
+        arg = np.zeros(n + 1, dtype=np.int64)
+        for j in range((k + 1) * min_size, n + 1):
+            starts = np.arange(k * min_size, j - min_size + 1)
+            total = best[starts] + cost.sse(starts, j)
+            # On ties take the latest start: a point lying on both lines (the
+            # vertex of a V) stays with the older regime, keeping the newest
+            # segment free of ambiguous points.
+            i = int(np.flatnonzero(total <= total.min() + tie_tol)[-1])
+            new[j] = total[i]
+            arg[j] = starts[i]
+        best = new
+        back.append(arg)
+        point = CriterionRow(k, float(best[n]), pen)
+        criterion.append(point)
+        # Strict improvement beyond rounding noise: ties go to fewer change points.
+        if point.objective < best_obj - tie_tol:
+            best_k, best_obj = k, point.objective
+
+    change_points: list[int] = []
+    j = n
+    for k in range(best_k, 0, -1):
+        j = int(back[k - 1][j])
+        change_points.append(j)
+    return Segmentation(tuple(reversed(change_points)), tuple(criterion))

pytrendclust-0.1.0/src/pytrendclust/clusterer.py

@@ -0,0 +1,310 @@
+"""Trend clustering of a time series with an adaptive number of clusters."""
+
+from __future__ import annotations
+
+import itertools
+import math
+from typing import Any, Literal
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from pytrendclust._cost import LinearCost, fit_line
+from pytrendclust._dp import segment
+from pytrendclust.penalty import (
+    PenaltyFunc,
+    default_scale,
+    estimate_noise_std,
+    exponential_penalty,
+    linear_penalty,
+)
+from pytrendclust.result import Segment, Trend, TrendClusteringResult
+
+PenaltyKind = Literal["exponential", "linear", "none"]
+
+# Floor of the noise scale relative to the series' spread: on a perfectly clean
+# series the noise estimate is 0, and a zero penalty would make every
+# segmentation with zero SSE a tie.
+_NOISE_FLOOR = 1e-6
+
+
+class TrendClusterer:
+    """Split a time series into consecutive trend clusters (rising, falling, flat).
+
+    Each cluster is a contiguous run of points with its own least-squares line.
+    The number of clusters is not given in advance: the clusterer minimises
+
+        SSE(K) + sigma**2 * penalty(K)
+
+    over the number of change points ``K``, where ``SSE(K)`` is the best total
+    squared error of a piecewise-linear fit with ``K`` change points and
+    ``sigma`` is the noise level.  The default exponential penalty makes every
+    extra change point dearer than the previous one, so noise such as a
+    "picket fence" (up, down, up, down, ...) is recognised as a single flat
+    cluster instead of ten tiny trends.
+
+    Parameters
+    ----------
+    penalty:
+        ``"exponential"`` (default) — the ``K``-th change point costs
+        ``penalty_scale * exp(penalty_growth * (K - 1))`` noise variances;
+        ``"linear"`` — every change point costs ``penalty_scale``;
+        ``"none"`` — no regularisation (only ``max_change_points`` limits K);
+        or a callable ``f(n_change_points, n_samples, noise_variance)`` returning
+        the penalty in the units of SSE, non-decreasing in ``n_change_points``.
+    penalty_scale:
+        Price of the first change point in noise variances.  Defaults to
+        ``5 * ln(n)`` (see :func:`~pytrendclust.default_scale`).  Larger means
+        fewer change points.
+    penalty_growth:
+        Exponential growth rate of the price of every next change point.
+    min_size:
+        Minimum number of points in a cluster; at least 2 (a line needs two
+        points, and three are needed before a line can be wrong).
+    max_change_points:
+        Hard upper bound on ``K``; ``None`` means only the penalty limits it.
+    noise_std:
+        Noise standard deviation in the units of the series.  ``None`` estimates
+        it robustly from second differences of the series.
+    flat_threshold:
+        A cluster is ``flat`` when ``|slope| / standard_error(slope)`` is below
+        this value (2 is roughly the 95 % significance level).
+
+    Examples
+    --------
+    >>> y = [10, 9, 8, 7, 6, 5, 4, 5, 6, 7]
+    >>> result = TrendClusterer().fit(y).result_
+    >>> result.change_points
+    [7]
+    >>> [s.trend.value for s in result.segments]
+    ['down', 'up']
+    >>> result.select()[1]
+    array([5., 6., 7.])
+    """
+
+    def __init__(
+        self,
+        *,
+        penalty: PenaltyKind | PenaltyFunc = "exponential",
+        penalty_scale: float | None = None,
+        penalty_growth: float = 0.5,
+        min_size: int = 3,
+        max_change_points: int | None = None,
+        noise_std: float | None = None,
+        flat_threshold: float = 2.0,
+    ) -> None:
+        self.penalty = penalty
+        self.penalty_scale = penalty_scale
+        self.penalty_growth = penalty_growth
+        self.min_size = min_size
+        self.max_change_points = max_change_points
+        self.noise_std = noise_std
+        self.flat_threshold = flat_threshold
+        self._validate()
+        self.result_: TrendClusteringResult | None = None
+
+    # -- parameters --------------------------------------------------------
+
+    _PARAM_NAMES = (
+        "penalty",
+        "penalty_scale",
+        "penalty_growth",
+        "min_size",
+        "max_change_points",
+        "noise_std",
+        "flat_threshold",
+    )
+
+    def get_params(self) -> dict[str, Any]:
+        """Current parameters, as accepted by the constructor and :meth:`set_params`."""
+        return {name: getattr(self, name) for name in self._PARAM_NAMES}
+
+    def set_params(self, **params: Any) -> TrendClusterer:
+        """Change parameters in place; returns ``self`` for chaining."""
+        unknown = set(params) - set(self._PARAM_NAMES)
+        if unknown:
+            msg = f"unknown parameter(s): {', '.join(sorted(unknown))}"
+            raise ValueError(msg)
+        old = self.get_params()
+        for name, value in params.items():
+            setattr(self, name, value)
+        try:
+            self._validate()
+        except (TypeError, ValueError):
+            for name, value in old.items():
+                setattr(self, name, value)
+            raise
+        return self
+
+    def __repr__(self) -> str:
+        args = ", ".join(f"{k}={v!r}" for k, v in self.get_params().items())
+        return f"{type(self).__name__}({args})"
+
+    def _validate(self) -> None:
+        if not callable(self.penalty) and self.penalty not in ("exponential", "linear", "none"):
+            msg = (
+                "penalty must be 'exponential', 'linear', 'none' or a callable, "
+                f"got {self.penalty!r}"
+            )
+            raise ValueError(msg)
+        if self.penalty_scale is not None and not (
+            math.isfinite(self.penalty_scale) and self.penalty_scale >= 0
+        ):
+            msg = f"penalty_scale must be a finite number >= 0, got {self.penalty_scale!r}"
+            raise ValueError(msg)
+        if not (math.isfinite(self.penalty_growth) and self.penalty_growth >= 0):
+            msg = f"penalty_growth must be a finite number >= 0, got {self.penalty_growth!r}"
+            raise ValueError(msg)
+        if isinstance(self.min_size, bool) or not isinstance(self.min_size, int):
+            msg = f"min_size must be an int, got {self.min_size!r}"
+            raise TypeError(msg)
+        if self.min_size < 2:
+            msg = f"min_size must be >= 2, got {self.min_size}"
+            raise ValueError(msg)
+        if self.max_change_points is not None and (
+            isinstance(self.max_change_points, bool)
+            or not isinstance(self.max_change_points, int)
+            or self.max_change_points < 0
+        ):
+            msg = f"max_change_points must be None or an int >= 0, got {self.max_change_points!r}"
+            raise ValueError(msg)
+        if self.noise_std is not None and not (
+            math.isfinite(self.noise_std) and self.noise_std >= 0
+        ):
+            msg = f"noise_std must be None or a finite number >= 0, got {self.noise_std!r}"
+            raise ValueError(msg)
+        if not (math.isfinite(self.flat_threshold) and self.flat_threshold >= 0):
+            msg = f"flat_threshold must be a finite number >= 0, got {self.flat_threshold!r}"
+            raise ValueError(msg)
+
+    # -- fitting -----------------------------------------------------------
+
+    def fit(self, y: ArrayLike, t: ArrayLike | None = None) -> TrendClusterer:
+        """Cluster the series ``y`` observed at times ``t`` (default ``0, 1, 2, ...``).
+
+        The result is stored in :attr:`result_`; returns ``self``.
+        """
+        y_arr, t_arr = _as_series(y, t)
+        n = len(y_arr)
+
+        sigma = self._noise_std(y_arr)
+        sigma2 = sigma * sigma
+        penalty = self._penalty_in_sse_units(n, sigma2)
+        largest_k = n // self.min_size - 1
+        if self.max_change_points is not None:
+            largest_k = min(largest_k, self.max_change_points)
+
+        seg = segment(LinearCost(t_arr, y_arr), n, self.min_size, max(largest_k, 0), penalty)
+
+        bounds = [0, *seg.change_points, n]
+        segments = tuple(
+            self._describe(index=i, start=start, stop=stop, t=t_arr, y=y_arr, sigma=sigma)
+            for i, (start, stop) in enumerate(itertools.pairwise(bounds))
+        )
+        self.result_ = TrendClusteringResult(
+            t=t_arr,
+            y=y_arr,
+            segments=segments,
+            noise_std=sigma,
+            criterion=seg.criterion,
+            params=self._exportable_params(),
+        )
+        return self
+
+    def fit_predict(self, y: ArrayLike, t: ArrayLike | None = None) -> NDArray[np.int64]:
+        """Fit and return the cluster (segment) index of every point."""
+        result = self.fit(y, t).result_
+        assert result is not None  # noqa: S101 - set by fit()
+        return result.labels
+
+    def _noise_std(self, y: NDArray[np.float64]) -> float:
+        sigma = estimate_noise_std(y) if self.noise_std is None else float(self.noise_std)
+        spread = float(np.ptp(y)) if len(y) else 0.0
+        return max(sigma, _NOISE_FLOOR * spread)
+
+    def _penalty_in_sse_units(self, n: int, sigma2: float) -> Any:
+        if callable(self.penalty):
+            func = self.penalty
+            return lambda k: float(func(k, n, sigma2))
+        if self.penalty == "none":
+            return lambda k: 0.0
+        scale = default_scale(n) if self.penalty_scale is None else self.penalty_scale
+        if self.penalty == "linear":
+            return lambda k: sigma2 * linear_penalty(k, scale)
+        growth = self.penalty_growth
+        return lambda k: sigma2 * exponential_penalty(k, scale, growth)
+
+    def _describe(
+        self,
+        *,
+        index: int,
+        start: int,
+        stop: int,
+        t: NDArray[np.float64],
+        y: NDArray[np.float64],
+        sigma: float,
+    ) -> Segment:
+        line = fit_line(t[start:stop], y[start:stop])
+        if line.stt == 0.0 or line.slope == 0.0:
+            t_stat = 0.0
+        elif sigma == 0.0:
+            t_stat = math.inf
+        else:
+            t_stat = abs(line.slope) * math.sqrt(line.stt) / sigma
+        if t_stat < self.flat_threshold:
+            trend = Trend.FLAT
+        else:
+            trend = Trend.UP if line.slope > 0 else Trend.DOWN
+        return Segment(
+            index=index,
+            start=start,
+            stop=stop,
+            trend=trend,
+            slope=line.slope,
+            intercept=line.intercept,
+            sse=line.sse,
+            t_statistic=t_stat,
+        )
+
+    def _exportable_params(self) -> dict[str, Any]:
+        params = self.get_params()
+        if callable(params["penalty"]):
+            params["penalty"] = getattr(params["penalty"], "__name__", repr(params["penalty"]))
+        return params
+
+
+def cluster_trends(
+    y: ArrayLike, t: ArrayLike | None = None, **params: Any
+) -> TrendClusteringResult:
+    """One-call shortcut: ``TrendClusterer(**params).fit(y, t).result_``."""
+    result = TrendClusterer(**params).fit(y, t).result_
+    assert result is not None  # noqa: S101 - set by fit()
+    return result
+
+
+def _as_series(
+    y: ArrayLike, t: ArrayLike | None
+) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+    y_arr = np.array(y, dtype=np.float64)
+    if y_arr.ndim != 1:
+        msg = f"y must be one-dimensional, got shape {y_arr.shape}"
+        raise ValueError(msg)
+    if len(y_arr) == 0:
+        msg = "y is empty"
+        raise ValueError(msg)
+    if not np.all(np.isfinite(y_arr)):
+        msg = "y contains NaN or infinite values"
+        raise ValueError(msg)
+    if t is None:
+        return y_arr, np.arange(len(y_arr), dtype=np.float64)
+    t_arr = np.array(t, dtype=np.float64)
+    if t_arr.shape != y_arr.shape:
+        msg = f"t and y must have the same shape, got {t_arr.shape} and {y_arr.shape}"
+        raise ValueError(msg)
+    if not np.all(np.isfinite(t_arr)):
+        msg = "t contains NaN or infinite values"
+        raise ValueError(msg)
+    if np.any(np.diff(t_arr) <= 0):
+        msg = "t must be strictly increasing"
+        raise ValueError(msg)
+    return y_arr, t_arr

pytrendclust-0.1.0/src/pytrendclust/penalty.py

@@ -0,0 +1,74 @@
+"""Penalties on the number of change points and the noise estimate they are scaled by.
+
+A penalty is measured in units of the noise variance ``sigma**2``: SSE grows with
+the square of the series' units, so a penalty in the same units makes the
+trade-off independent of whether memory is counted in bytes or gigabytes.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Callable
+
+import numpy as np
+from numpy.typing import NDArray
+
+#: ``penalty(n_change_points, n_samples, noise_variance) -> float``.
+#: A custom penalty must be non-decreasing in ``n_change_points``.
+PenaltyFunc = Callable[[int, int, float], float]
+
+# Consistency constant turning a median absolute deviation into a standard
+# deviation for Gaussian noise.
+_MAD_TO_STD = 1.482602218505602
+
+
+def default_scale(n_samples: int) -> float:
+    """Default price of the first change point, in noise variances: ``5 * ln(n)``.
+
+    Every extra segment costs three parameters — slope, intercept and the
+    position of its start — for which BIC would charge ``3 * ln(n)``.  BIC is
+    too liberal here: the start position is chosen as the best of ``n``
+    candidates, so on pure noise it finds a spurious short trend in ~7 % of
+    100-point series, against ~0.5 % with ``5 * ln(n)`` at the same detection
+    rate of real breaks.
+    """
+    return 5.0 * math.log(max(n_samples, 2))
+
+
+def exponential_penalty(n_change_points: int, scale: float, growth: float) -> float:
+    """``scale * (exp(growth * K) - 1) / (exp(growth) - 1)``, in noise variances.
+
+    The first change point costs exactly ``scale``; every next one costs
+    ``exp(growth)`` times more than the previous, so the model grows ever more
+    reluctant to add change points.  ``growth = 0`` degenerates to the linear
+    penalty ``scale * K``.
+    """
+    if n_change_points == 0:
+        return 0.0
+    if growth == 0.0:
+        return scale * n_change_points
+    return scale * math.expm1(growth * n_change_points) / math.expm1(growth)
+
+
+def linear_penalty(n_change_points: int, scale: float) -> float:
+    """Classic constant price per change point: ``scale * K``, in noise variances."""
+    return scale * n_change_points
+
+
+def estimate_noise_std(y: NDArray[np.float64]) -> float:
+    """Robust estimate of the noise standard deviation around a piecewise-linear trend.
+
+    Second differences cancel any linear trend, leaving ``eps[i] - 2 eps[i+1] +
+    eps[i+2]`` with variance ``6 sigma**2``; a few kinks between segments are
+    outliers that the median absolute deviation ignores.  Falls back to the plain
+    standard deviation of the second differences when more than half of them
+    coincide (for example, on a quantised series), and returns 0 for series too
+    short to tell.
+    """
+    if len(y) < 4:
+        return 0.0
+    d2 = np.diff(y, n=2)
+    mad = float(np.median(np.abs(d2 - np.median(d2))))
+    if mad > 0.0:
+        return _MAD_TO_STD * mad / math.sqrt(6.0)
+    return float(d2.std()) / math.sqrt(6.0)

pytrendclust-0.1.0/src/pytrendclust/result.py

@@ -0,0 +1,303 @@
+"""Result of a trend clustering and its export to dict, JSON, CSV and pandas."""
+
+from __future__ import annotations
+
+import csv
+import io
+import json
+from dataclasses import dataclass, field
+from enum import StrEnum
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+FORMAT_VERSION = 1
+
+
+class Trend(StrEnum):
+    """Direction of a segment's linear trend."""
+
+    UP = "up"
+    DOWN = "down"
+    FLAT = "flat"
+
+
+@dataclass(frozen=True, slots=True)
+class Segment:
+    """One trend cluster: a contiguous run of points ``[start, stop)`` and its line."""
+
+    index: int
+    start: int
+    stop: int
+    trend: Trend
+    slope: float
+    intercept: float
+    sse: float
+    #: ``|slope| / standard_error(slope)``; ``inf`` for a noise-free series.
+    t_statistic: float
+
+    @property
+    def n_points(self) -> int:
+        return self.stop - self.start
+
+    def predict(self, t: Any) -> NDArray[np.float64]:
+        """Value of the segment's line at time(s) ``t`` — also beyond the segment."""
+        return self.intercept + self.slope * np.asarray(t, dtype=np.float64)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "index": self.index,
+            "start": self.start,
+            "stop": self.stop,
+            "n_points": self.n_points,
+            "trend": self.trend.value,
+            "slope": self.slope,
+            "intercept": self.intercept,
+            "sse": self.sse,
+            "t_statistic": _json_float(self.t_statistic),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Segment:
+        return cls(
+            index=int(data["index"]),
+            start=int(data["start"]),
+            stop=int(data["stop"]),
+            trend=Trend(data["trend"]),
+            slope=float(data["slope"]),
+            intercept=float(data["intercept"]),
+            sse=float(data["sse"]),
+            t_statistic=float(data["t_statistic"]),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class CriterionRow:
+    """Penalised criterion for one candidate number of change points."""
+
+    n_change_points: int
+    sse: float
+    penalty: float
+
+    @property
+    def objective(self) -> float:
+        return self.sse + self.penalty
+
+
+@dataclass(frozen=True)
+class TrendClusteringResult:
+    """Which point belongs to which trend cluster, plus everything needed to audit it.
+
+    ``segments`` are ordered in time and cover the series without gaps;
+    ``segments[-1]`` is the most recent regime — the one to train a regression on.
+    """
+
+    t: NDArray[np.float64]
+    y: NDArray[np.float64]
+    segments: tuple[Segment, ...]
+    noise_std: float
+    #: Criterion for every number of change points the search evaluated.
+    criterion: tuple[CriterionRow, ...]
+    #: Parameters of the :class:`~pytrendclust.TrendClusterer` that produced this result.
+    params: dict[str, Any] = field(default_factory=dict)
+
+    # -- structure ---------------------------------------------------------
+
+    @property
+    def n_points(self) -> int:
+        return len(self.y)
+
+    @property
+    def n_segments(self) -> int:
+        return len(self.segments)
+
+    @property
+    def n_change_points(self) -> int:
+        return len(self.segments) - 1
+
+    @property
+    def change_points(self) -> list[int]:
+        """Indices where a new segment starts (the first segment's start, 0, excluded)."""
+        return [s.start for s in self.segments[1:]]
+
+    @property
+    def labels(self) -> NDArray[np.int64]:
+        """Segment index of every point."""
+        return np.repeat(
+            np.arange(self.n_segments, dtype=np.int64), [s.n_points for s in self.segments]
+        )
+
+    @property
+    def trends(self) -> list[Trend]:
+        """Trend of the segment every point belongs to."""
+        return [s.trend for s in self.segments for _ in range(s.n_points)]
+
+    @property
+    def fitted(self) -> NDArray[np.float64]:
+        """Piecewise-linear fit: every point's value on its own segment's line."""
+        return np.concatenate([s.predict(self.t[s.start : s.stop]) for s in self.segments])
+
+    @property
+    def last_segment(self) -> Segment:
+        """The most recent regime of the series."""
+        return self.segments[-1]
+
+    @property
+    def objective(self) -> float:
+        """Value of the penalised criterion at the chosen segmentation."""
+        chosen = self.n_change_points
+        return next(r.objective for r in self.criterion if r.n_change_points == chosen)
+
+    # -- selection ---------------------------------------------------------
+
+    def indices(self, segment: int = -1) -> NDArray[np.int64]:
+        """Indices of the points of one segment; the last one by default."""
+        s = self.segments[segment]
+        return np.arange(s.start, s.stop, dtype=np.int64)
+
+    def select(self, segment: int = -1) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+        """``(t, y)`` of one segment's points; the last (most recent) one by default."""
+        s = self.segments[segment]
+        return self.t[s.start : s.stop].copy(), self.y[s.start : s.stop].copy()
+
+    # -- export ------------------------------------------------------------
+
+    def to_dict(self, *, include_points: bool = True) -> dict[str, Any]:
+        """Plain-Python representation, round-trippable through :meth:`from_dict`."""
+        data: dict[str, Any] = {
+            "format_version": FORMAT_VERSION,
+            "n_points": self.n_points,
+            "n_segments": self.n_segments,
+            "n_change_points": self.n_change_points,
+            "change_points": self.change_points,
+            "noise_std": self.noise_std,
+            "objective": self.objective,
+            "params": self.params,
+            "segments": [s.to_dict() for s in self.segments],
+            "criterion": [
+                {
+                    "n_change_points": r.n_change_points,
+                    "sse": r.sse,
+                    "penalty": r.penalty,
+                    "objective": r.objective,
+                }
+                for r in self.criterion
+            ],
+        }
+        if include_points:
+            data["points"] = {"t": self.t.tolist(), "y": self.y.tolist()}
+        return data
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> TrendClusteringResult:
+        """Rebuild a result exported with ``to_dict(include_points=True)``."""
+        if data.get("format_version") != FORMAT_VERSION:
+            msg = f"unsupported format_version: {data.get('format_version')!r}"
+            raise ValueError(msg)
+        if "points" not in data:
+            msg = "the export has no points; export it with include_points=True"
+            raise ValueError(msg)
+        return cls(
+            t=np.asarray(data["points"]["t"], dtype=np.float64),
+            y=np.asarray(data["points"]["y"], dtype=np.float64),
+            segments=tuple(Segment.from_dict(s) for s in data["segments"]),
+            noise_std=float(data["noise_std"]),
+            criterion=tuple(
+                CriterionRow(int(r["n_change_points"]), float(r["sse"]), float(r["penalty"]))
+                for r in data["criterion"]
+            ),
+            params=dict(data["params"]),
+        )
+
+    def to_json(self, path: str | Path | None = None, *, indent: int | None = 2) -> str:
+        """Serialise to JSON; also write it to ``path`` when given."""
+        text = json.dumps(self.to_dict(), ensure_ascii=False, indent=indent)
+        if path is not None:
+            Path(path).write_text(text, encoding="utf-8")
+        return text
+
+    @classmethod
+    def from_json(cls, source: str | Path) -> TrendClusteringResult:
+        """Load a result from a JSON file path or a JSON string."""
+        text = str(source)
+        if not text.lstrip().startswith("{"):
+            text = Path(source).read_text(encoding="utf-8")
+        return cls.from_dict(json.loads(text))
+
+    def point_table(self) -> list[dict[str, Any]]:
+        """One row per point: index, t, y, segment, trend, fitted value, residual."""
+        labels = self.labels
+        trends = self.trends
+        fitted = self.fitted
+        return [
+            {
+                "index": i,
+                "t": float(self.t[i]),
+                "y": float(self.y[i]),
+                "segment": int(labels[i]),
+                "trend": trends[i].value,
+                "fitted": float(fitted[i]),
+                "residual": float(self.y[i] - fitted[i]),
+                "is_last_segment": bool(labels[i] == self.n_segments - 1),
+            }
+            for i in range(self.n_points)
+        ]
+
+    def to_csv(self, path: str | Path | None = None) -> str:
+        """Per-point table as CSV; also write it to ``path`` when given."""
+        rows = self.point_table()
+        buffer = io.StringIO()
+        writer = csv.DictWriter(buffer, fieldnames=list(rows[0]), lineterminator="\n")
+        writer.writeheader()
+        writer.writerows(rows)
+        text = buffer.getvalue()
+        if path is not None:
+            Path(path).write_text(text, encoding="utf-8")
+        return text
+
+    def to_dataframe(self) -> pd.DataFrame:
+        """Per-point table as a :class:`pandas.DataFrame` (needs ``pytrendclust[pandas]``)."""
+        try:
+            import pandas as pd
+        except ImportError as exc:
+            msg = "to_dataframe() needs pandas: pip install 'pytrendclust[pandas]'"
+            raise ImportError(msg) from exc
+        return pd.DataFrame(self.point_table())
+
+    def export(self, path: str | Path) -> None:
+        """Write the result to ``path``; the format follows the suffix (``.json``/``.csv``)."""
+        suffix = Path(path).suffix.lower()
+        if suffix == ".json":
+            self.to_json(path)
+        elif suffix == ".csv":
+            self.to_csv(path)
+        else:
+            msg = f"unsupported export format {suffix!r}; use .json or .csv"
+            raise ValueError(msg)
+
+    def summary(self) -> str:
+        """Human-readable one-line-per-segment description."""
+        lines = [
+            (
+                f"{self.n_points} points, {self.n_change_points} change point(s), "
+                f"noise std {self.noise_std:.4g}"
+            )
+        ]
+        lines.extend(
+            f"  #{s.index}: [{s.start}, {s.stop}) {s.n_points:>4} pts  "
+            f"{s.trend.value:<4}  slope {s.slope:+.4g}"
+            for s in self.segments
+        )
+        return "\n".join(lines)
+
+
+def _json_float(value: float) -> float | str:
+    """JSON has no infinity; spell it as a string that ``float()`` parses back."""
+    if np.isinf(value):
+        return "inf" if value > 0 else "-inf"
+    return value