plotilleresample 0.4__tar.gz → 1.0__tar.gz

plotilleresample-1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Carlos A. Planchón
+
+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.

plotilleresample-1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: plotilleresample
+Version: 1.0
+Summary: Python module to resample datasets before plotting with Plotille.
+Author-email: "Carlos A. Planchón" <carlosandresplanchonprestes@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/carlosplanchon/plotilleresample
+Keywords: plotting,ascii,math,resample
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Terminals
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# plotilleresample
+![plotilleresample banner](assets/banner-v2.jpg)
+
+*Python module to resample datasets before plotting with Plotille.*
+
+[![CI](https://github.com/carlosplanchon/plotilleresample/actions/workflows/ci.yml/badge.svg)](https://github.com/carlosplanchon/plotilleresample/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/plotilleresample.svg)](https://pypi.org/project/plotilleresample/)
+[![Python versions](https://img.shields.io/pypi/pyversions/plotilleresample.svg)](https://pypi.org/project/plotilleresample/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Why resample?
+
+Plotille rasterizes to a terminal canvas of braille dots: `width * 2` columns by `height * 4` rows. Feeding it far more points than that costs interpolation time on detail the canvas cannot show. Plotille rasterizes; plotilleresample decides what information deserves to reach the rasterizer:
+
+| Function               | Strategy           | Best for                          |
+| ---------------------- | ------------------ | --------------------------------- |
+| `resample_plot`        | uniform stride     | smooth lines, cheapest reduction  |
+| `resample_plot_minmax` | min/max per bucket | peaks, oscillations, time series  |
+| `resample_plot_lttb`   | largest triangle per bucket | shape-faithful single line |
+| `resample_plot_minmax_lttb` | minmax preselection + LTTB | shape-faithful line, large inputs |
+| `resample_scatter`     | uniform stride     | large scatter inputs              |
+
+The uniform stride keeps one point every N: fast and predictable, but a narrow peak that falls between two kept points disappears from the plot. `resample_plot_minmax` instead makes one bucket per braille dot column and keeps the minimum and the maximum Y of each bucket, so the envelope of the signal — spikes included — always survives:
+
+```python
+X = list(range(10000))
+Y = [0.0] * 10000
+Y[33] = 1000.0  # a narrow spike
+
+_, y_stride = plotilleresample.resample_plot(X, Y)
+_, y_minmax = plotilleresample.resample_plot_minmax(X, Y)
+
+1000.0 in y_stride  # False: the spike vanished
+1000.0 in y_minmax  # True: the envelope survives
+```
+
+`resample_plot_lttb` implements Largest-Triangle-Three-Buckets (Steinarsson, 2013): it always keeps the first and the last point and picks the most shape-representative point of each bucket, giving a single clean line that looks like the original. It keeps one point per bucket, so — unlike min/max — one of two opposing extremes falling in the same bucket can be dropped: shape fidelity instead of envelope guarantee.
+
+`resample_plot_minmax_lttb` is the hybrid (MinMaxLTTB, Van der Donckt et al., 2023; the plotly-resampler default): on large inputs a minmax pass preselects the per bucket extremes and LTTB runs over those candidates only. Visually close to pure LTTB and faster, with a gap that grows with input size — about 1.6x end to end at 100,000 points, and about 3.4x on the resampling pass alone at 1,000,000 — and the true extremes are always among the candidates.
+
+All four plot resamplers work in sample order — they bucket by index, so X is expected to be already sorted, as in a time series (`resample_scatter` makes no ordering assumption). They keep at most `width * 4` points and `resample_scatter` keeps at most `width * 2 * height`, so plotille only receives what the canvas can actually display.
+
+## Benchmark
+
+End to end times: building the plot string with plotille alone versus resampling first. Measured with `benchmarks/bench.py` (canvas 80x40, best of 3) on Python 3.14, Linux, Intel Core i5-1135G7:
+
+| Points  | plotille alone | stride + plotille | minmax + plotille | lttb + plotille | mmlttb + plotille |
+| ------- | -------------- | ----------------- | ----------------- | --------------- | ----------------- |
+| 10,000  | 202 ms         | 23 ms             | 22 ms             | 27 ms           | 24 ms             |
+| 100,000 | 1.75 s         | 39 ms             | 52 ms             | 90 ms           | 56 ms             |
+
+Reproduce it from the repository root with:
+
+```
+uv run --group bench benchmarks/bench.py
+```
+
+The resampling-pass figure quoted in Why resample? (pure LTTB vs MinMaxLTTB at 1,000,000 points) has its own script:
+
+```
+uv run benchmarks/bench_resamplers.py
+```
+
+## Installation
+### Install with UV:
+```
+uv add plotilleresample
+```
+### Install with pip:
+```
+pip install plotilleresample
+```
+
+plotilleresample has no runtime dependencies — not even plotille: it only reduces sequences. To run the example below, install plotille as well (`uv add plotille` or `pip install plotille`).
+
+## Usage
+```python
+import math
+
+import plotille
+
+from plotilleresample import resample_plot_minmax_lttb
+
+r = 100_000
+X = list(range(r))
+Y = [math.sin(i / 500) * 100 for i in range(r)]
+
+X, Y = resample_plot_minmax_lttb(X, Y, width=80, height=40)
+print(plotille.plot(X, Y, width=80, height=40))
+```
+
+The full interactive demo, running every resampler on the same dataset, lives in [`examples/demo.py`](examples/demo.py).

plotilleresample-1.0/README.md

@@ -0,0 +1,92 @@
+# plotilleresample
+![plotilleresample banner](assets/banner-v2.jpg)
+
+*Python module to resample datasets before plotting with Plotille.*
+
+[![CI](https://github.com/carlosplanchon/plotilleresample/actions/workflows/ci.yml/badge.svg)](https://github.com/carlosplanchon/plotilleresample/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/plotilleresample.svg)](https://pypi.org/project/plotilleresample/)
+[![Python versions](https://img.shields.io/pypi/pyversions/plotilleresample.svg)](https://pypi.org/project/plotilleresample/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Why resample?
+
+Plotille rasterizes to a terminal canvas of braille dots: `width * 2` columns by `height * 4` rows. Feeding it far more points than that costs interpolation time on detail the canvas cannot show. Plotille rasterizes; plotilleresample decides what information deserves to reach the rasterizer:
+
+| Function               | Strategy           | Best for                          |
+| ---------------------- | ------------------ | --------------------------------- |
+| `resample_plot`        | uniform stride     | smooth lines, cheapest reduction  |
+| `resample_plot_minmax` | min/max per bucket | peaks, oscillations, time series  |
+| `resample_plot_lttb`   | largest triangle per bucket | shape-faithful single line |
+| `resample_plot_minmax_lttb` | minmax preselection + LTTB | shape-faithful line, large inputs |
+| `resample_scatter`     | uniform stride     | large scatter inputs              |
+
+The uniform stride keeps one point every N: fast and predictable, but a narrow peak that falls between two kept points disappears from the plot. `resample_plot_minmax` instead makes one bucket per braille dot column and keeps the minimum and the maximum Y of each bucket, so the envelope of the signal — spikes included — always survives:
+
+```python
+X = list(range(10000))
+Y = [0.0] * 10000
+Y[33] = 1000.0  # a narrow spike
+
+_, y_stride = plotilleresample.resample_plot(X, Y)
+_, y_minmax = plotilleresample.resample_plot_minmax(X, Y)
+
+1000.0 in y_stride  # False: the spike vanished
+1000.0 in y_minmax  # True: the envelope survives
+```
+
+`resample_plot_lttb` implements Largest-Triangle-Three-Buckets (Steinarsson, 2013): it always keeps the first and the last point and picks the most shape-representative point of each bucket, giving a single clean line that looks like the original. It keeps one point per bucket, so — unlike min/max — one of two opposing extremes falling in the same bucket can be dropped: shape fidelity instead of envelope guarantee.
+
+`resample_plot_minmax_lttb` is the hybrid (MinMaxLTTB, Van der Donckt et al., 2023; the plotly-resampler default): on large inputs a minmax pass preselects the per bucket extremes and LTTB runs over those candidates only. Visually close to pure LTTB and faster, with a gap that grows with input size — about 1.6x end to end at 100,000 points, and about 3.4x on the resampling pass alone at 1,000,000 — and the true extremes are always among the candidates.
+
+All four plot resamplers work in sample order — they bucket by index, so X is expected to be already sorted, as in a time series (`resample_scatter` makes no ordering assumption). They keep at most `width * 4` points and `resample_scatter` keeps at most `width * 2 * height`, so plotille only receives what the canvas can actually display.
+
+## Benchmark
+
+End to end times: building the plot string with plotille alone versus resampling first. Measured with `benchmarks/bench.py` (canvas 80x40, best of 3) on Python 3.14, Linux, Intel Core i5-1135G7:
+
+| Points  | plotille alone | stride + plotille | minmax + plotille | lttb + plotille | mmlttb + plotille |
+| ------- | -------------- | ----------------- | ----------------- | --------------- | ----------------- |
+| 10,000  | 202 ms         | 23 ms             | 22 ms             | 27 ms           | 24 ms             |
+| 100,000 | 1.75 s         | 39 ms             | 52 ms             | 90 ms           | 56 ms             |
+
+Reproduce it from the repository root with:
+
+```
+uv run --group bench benchmarks/bench.py
+```
+
+The resampling-pass figure quoted in Why resample? (pure LTTB vs MinMaxLTTB at 1,000,000 points) has its own script:
+
+```
+uv run benchmarks/bench_resamplers.py
+```
+
+## Installation
+### Install with UV:
+```
+uv add plotilleresample
+```
+### Install with pip:
+```
+pip install plotilleresample
+```
+
+plotilleresample has no runtime dependencies — not even plotille: it only reduces sequences. To run the example below, install plotille as well (`uv add plotille` or `pip install plotille`).
+
+## Usage
+```python
+import math
+
+import plotille
+
+from plotilleresample import resample_plot_minmax_lttb
+
+r = 100_000
+X = list(range(r))
+Y = [math.sin(i / 500) * 100 for i in range(r)]
+
+X, Y = resample_plot_minmax_lttb(X, Y, width=80, height=40)
+print(plotille.plot(X, Y, width=80, height=40))
+```
+
+The full interactive demo, running every resampler on the same dataset, lives in [`examples/demo.py`](examples/demo.py).

plotilleresample-1.0/plotilleresample/__init__.py

@@ -0,0 +1,15 @@
+#!/usr/bin/env python3
+
+from plotilleresample.plotilleresample import resample_plot
+from plotilleresample.plotilleresample import resample_plot_lttb
+from plotilleresample.plotilleresample import resample_plot_minmax
+from plotilleresample.plotilleresample import resample_plot_minmax_lttb
+from plotilleresample.plotilleresample import resample_scatter
+
+__all__ = [
+    "resample_plot",
+    "resample_plot_lttb",
+    "resample_plot_minmax",
+    "resample_plot_minmax_lttb",
+    "resample_scatter",
+    ]

plotilleresample-1.0/plotilleresample/plotilleresample.py

@@ -0,0 +1,284 @@
+#!/usr/bin/env python3
+
+from collections.abc import Sequence
+from math import ceil
+
+# Historically chosen to reduce Nyquist/undersampling-related artifacts.
+plot_multiplier = 4
+
+# Preselection ratio for resample_plot_minmax_lttb, as in plotly-resampler.
+minmax_ratio = 4
+
+
+def _check_input(
+    X: Sequence[float],
+    Y: Sequence[float],
+    width: int
+        ) -> None:
+    if len(X) != len(Y):
+        raise ValueError(
+            "X and Y must have the same number of entries: "
+            f"{len(X)} != {len(Y)}"
+            )
+
+    if width <= 0:
+        raise ValueError(f"width must be positive: {width}")
+
+
+def _minmax_indices(
+    Y: Sequence[float],
+    buckets: int
+        ) -> list[int]:
+    n = len(Y)
+
+    idxs = []
+    for b in range(buckets):
+        start = b * n // buckets
+        stop = (b + 1) * n // buckets
+
+        i_min = i_max = start
+        for i in range(start + 1, stop):
+            if Y[i] < Y[i_min]:
+                i_min = i
+            elif Y[i] > Y[i_max]:
+                i_max = i
+
+        # In index order so a sorted X stays sorted.
+        idxs.extend(sorted({i_min, i_max}))
+
+    return idxs
+
+
+def _lttb(
+    X: Sequence[float],
+    Y: Sequence[float],
+    n_out: int
+        ) -> tuple[list[float], list[float]]:
+    n = len(X)
+
+    # First and last point always survive; one point per bucket
+    # in between, for exactly n_out points.
+    m = n_out - 2
+
+    new_X = [X[0]]
+    new_Y = [Y[0]]
+
+    a = 0
+    for b in range(m):
+        start = 1 + b * (n - 2) // m
+        stop = 1 + (b + 1) * (n - 2) // m
+
+        # A is the previously selected point; C is the average of
+        # the next bucket (the last point for the final bucket).
+        if b + 1 < m:
+            next_stop = 1 + (b + 2) * (n - 2) // m
+            span = next_stop - stop
+            c_x = sum(X[stop:next_stop]) / span
+            c_y = sum(Y[stop:next_stop]) / span
+        else:
+            c_x = X[n - 1]
+            c_y = Y[n - 1]
+
+        a_x = X[a]
+        a_y = Y[a]
+
+        best = start
+        best_area = -1.0
+        for i in range(start, stop):
+            area = abs(
+                (a_x - c_x) * (Y[i] - a_y)
+                - (a_x - X[i]) * (c_y - a_y)
+                )
+            if area > best_area:
+                best_area = area
+                best = i
+
+        new_X.append(X[best])
+        new_Y.append(Y[best])
+        a = best
+
+    new_X.append(X[n - 1])
+    new_Y.append(Y[n - 1])
+
+    return new_X, new_Y
+
+
+def resample_plot(
+    X: Sequence[float],
+    Y: Sequence[float],
+    width: int = 80,
+    height: int = 40
+        ) -> tuple[Sequence[float], Sequence[float]]:
+    """
+    Works in sample order: X is expected to be already sorted,
+    as in a time series.
+
+    :param X: Sequence[float]: X values.
+    :param Y: Sequence[float]: Y values.
+    :param width: int: Width of the plot. (Default value = 80)
+    :param height: int: Unused; kept for signature symmetry
+        with resample_scatter. (Default value = 40)
+
+    """
+    _check_input(X, Y, width)
+
+    if len(X) > width * plot_multiplier:
+        step = ceil(len(X) / (width * plot_multiplier))
+
+        X = [
+            X[i] for i in range(
+                0, len(X), step
+                )
+            ]
+        Y = [
+            Y[i] for i in range(
+                0, len(Y), step
+                )
+            ]
+
+    return X, Y
+
+
+def resample_plot_minmax(
+    X: Sequence[float],
+    Y: Sequence[float],
+    width: int = 80,
+    height: int = 40
+        ) -> tuple[Sequence[float], Sequence[float]]:
+    """
+    Like resample_plot, but it keeps the minimum and the maximum
+    Y of each bucket, so peaks in high frequency data survive
+    the resampling. Buckets are formed in sample order: X is
+    expected to be already sorted, as in a time series.
+
+    :param X: Sequence[float]: X values.
+    :param Y: Sequence[float]: Y values.
+    :param width: int: Width of the plot. (Default value = 80)
+    :param height: int: Unused; kept for signature symmetry
+        with resample_scatter. (Default value = 40)
+
+    """
+    _check_input(X, Y, width)
+
+    if len(X) > width * plot_multiplier:
+        # One bucket per braille dot column (2 per char); min and max
+        # per bucket keep the output at most width * plot_multiplier.
+        idxs = _minmax_indices(Y, width * plot_multiplier // 2)
+
+        X = [X[i] for i in idxs]
+        Y = [Y[i] for i in idxs]
+
+    return X, Y
+
+
+def resample_plot_lttb(
+    X: Sequence[float],
+    Y: Sequence[float],
+    width: int = 80,
+    height: int = 40
+        ) -> tuple[Sequence[float], Sequence[float]]:
+    """
+    Like resample_plot, but it applies Largest-Triangle-Three-Buckets
+    (Steinarsson, 2013): it always keeps the first and the last point
+    and picks the most shape-representative point of each bucket, so
+    the reduced line looks like the original. Unlike
+    resample_plot_minmax it keeps one point per bucket, so one of two
+    opposing extremes falling in the same bucket can be dropped.
+    Buckets are formed in sample order: X is expected to be already
+    sorted, as in a time series.
+
+    :param X: Sequence[float]: X values.
+    :param Y: Sequence[float]: Y values.
+    :param width: int: Width of the plot. (Default value = 80)
+    :param height: int: Unused; kept for signature symmetry
+        with resample_scatter. (Default value = 40)
+
+    """
+    _check_input(X, Y, width)
+
+    if len(X) > width * plot_multiplier:
+        X, Y = _lttb(X, Y, width * plot_multiplier)
+
+    return X, Y
+
+
+def resample_plot_minmax_lttb(
+    X: Sequence[float],
+    Y: Sequence[float],
+    width: int = 80,
+    height: int = 40
+        ) -> tuple[Sequence[float], Sequence[float]]:
+    """
+    Like resample_plot_lttb, but on large inputs it first preselects
+    the per bucket extremes with a minmax pass at minmax_ratio finer
+    granularity and runs LTTB over those candidates (MinMaxLTTB,
+    Van der Donckt et al., 2023; the plotly-resampler default).
+    Faster than pure LTTB, with a gap that grows with input size;
+    the true extremes are always among the candidates, and the
+    result stays visually close to pure LTTB. Buckets are
+    formed in sample order: X is expected to be already sorted,
+    as in a time series.
+
+    :param X: Sequence[float]: X values.
+    :param Y: Sequence[float]: Y values.
+    :param width: int: Width of the plot. (Default value = 80)
+    :param height: int: Unused; kept for signature symmetry
+        with resample_scatter. (Default value = 40)
+
+    """
+    _check_input(X, Y, width)
+
+    n_out = width * plot_multiplier
+    if len(X) > n_out:
+        if len(X) > n_out * minmax_ratio:
+            idxs = _minmax_indices(Y, n_out * minmax_ratio // 2)
+
+            # LTTB anchors on the endpoints, so force them in.
+            if idxs[0] != 0:
+                idxs.insert(0, 0)
+            if idxs[-1] != len(X) - 1:
+                idxs.append(len(X) - 1)
+
+            X = [X[i] for i in idxs]
+            Y = [Y[i] for i in idxs]
+
+        X, Y = _lttb(X, Y, n_out)
+
+    return X, Y
+
+
+def resample_scatter(
+    X: Sequence[float],
+    Y: Sequence[float],
+    width: int = 80,
+    height: int = 40
+        ) -> tuple[Sequence[float], Sequence[float]]:
+    """
+
+    :param X: Sequence[float]: X values.
+    :param Y: Sequence[float]: Y values.
+    :param width: int: Width of the plot. (Default value = 80)
+    :param height: int: Height of the plot. (Default value = 40)
+
+    """
+    _check_input(X, Y, width)
+
+    if height <= 0:
+        raise ValueError(f"height must be positive: {height}")
+
+    scatter_multiplier = width * 2 * height
+    if len(X) > scatter_multiplier:
+        step = ceil(len(X) / scatter_multiplier)
+
+        X = [
+            X[i] for i in range(
+                0, len(X), step
+                )
+            ]
+        Y = [
+            Y[i] for i in range(
+                0, len(Y), step
+                )
+            ]
+
+    return X, Y

plotilleresample-1.0/plotilleresample.egg-info/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: plotilleresample
+Version: 1.0
+Summary: Python module to resample datasets before plotting with Plotille.
+Author-email: "Carlos A. Planchón" <carlosandresplanchonprestes@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/carlosplanchon/plotilleresample
+Keywords: plotting,ascii,math,resample
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Terminals
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# plotilleresample
+![plotilleresample banner](assets/banner-v2.jpg)
+
+*Python module to resample datasets before plotting with Plotille.*
+
+[![CI](https://github.com/carlosplanchon/plotilleresample/actions/workflows/ci.yml/badge.svg)](https://github.com/carlosplanchon/plotilleresample/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/plotilleresample.svg)](https://pypi.org/project/plotilleresample/)
+[![Python versions](https://img.shields.io/pypi/pyversions/plotilleresample.svg)](https://pypi.org/project/plotilleresample/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Why resample?
+
+Plotille rasterizes to a terminal canvas of braille dots: `width * 2` columns by `height * 4` rows. Feeding it far more points than that costs interpolation time on detail the canvas cannot show. Plotille rasterizes; plotilleresample decides what information deserves to reach the rasterizer:
+
+| Function               | Strategy           | Best for                          |
+| ---------------------- | ------------------ | --------------------------------- |
+| `resample_plot`        | uniform stride     | smooth lines, cheapest reduction  |
+| `resample_plot_minmax` | min/max per bucket | peaks, oscillations, time series  |
+| `resample_plot_lttb`   | largest triangle per bucket | shape-faithful single line |
+| `resample_plot_minmax_lttb` | minmax preselection + LTTB | shape-faithful line, large inputs |
+| `resample_scatter`     | uniform stride     | large scatter inputs              |
+
+The uniform stride keeps one point every N: fast and predictable, but a narrow peak that falls between two kept points disappears from the plot. `resample_plot_minmax` instead makes one bucket per braille dot column and keeps the minimum and the maximum Y of each bucket, so the envelope of the signal — spikes included — always survives:
+
+```python
+X = list(range(10000))
+Y = [0.0] * 10000
+Y[33] = 1000.0  # a narrow spike
+
+_, y_stride = plotilleresample.resample_plot(X, Y)
+_, y_minmax = plotilleresample.resample_plot_minmax(X, Y)
+
+1000.0 in y_stride  # False: the spike vanished
+1000.0 in y_minmax  # True: the envelope survives
+```
+
+`resample_plot_lttb` implements Largest-Triangle-Three-Buckets (Steinarsson, 2013): it always keeps the first and the last point and picks the most shape-representative point of each bucket, giving a single clean line that looks like the original. It keeps one point per bucket, so — unlike min/max — one of two opposing extremes falling in the same bucket can be dropped: shape fidelity instead of envelope guarantee.
+
+`resample_plot_minmax_lttb` is the hybrid (MinMaxLTTB, Van der Donckt et al., 2023; the plotly-resampler default): on large inputs a minmax pass preselects the per bucket extremes and LTTB runs over those candidates only. Visually close to pure LTTB and faster, with a gap that grows with input size — about 1.6x end to end at 100,000 points, and about 3.4x on the resampling pass alone at 1,000,000 — and the true extremes are always among the candidates.
+
+All four plot resamplers work in sample order — they bucket by index, so X is expected to be already sorted, as in a time series (`resample_scatter` makes no ordering assumption). They keep at most `width * 4` points and `resample_scatter` keeps at most `width * 2 * height`, so plotille only receives what the canvas can actually display.
+
+## Benchmark
+
+End to end times: building the plot string with plotille alone versus resampling first. Measured with `benchmarks/bench.py` (canvas 80x40, best of 3) on Python 3.14, Linux, Intel Core i5-1135G7:
+
+| Points  | plotille alone | stride + plotille | minmax + plotille | lttb + plotille | mmlttb + plotille |
+| ------- | -------------- | ----------------- | ----------------- | --------------- | ----------------- |
+| 10,000  | 202 ms         | 23 ms             | 22 ms             | 27 ms           | 24 ms             |
+| 100,000 | 1.75 s         | 39 ms             | 52 ms             | 90 ms           | 56 ms             |
+
+Reproduce it from the repository root with:
+
+```
+uv run --group bench benchmarks/bench.py
+```
+
+The resampling-pass figure quoted in Why resample? (pure LTTB vs MinMaxLTTB at 1,000,000 points) has its own script:
+
+```
+uv run benchmarks/bench_resamplers.py
+```
+
+## Installation
+### Install with UV:
+```
+uv add plotilleresample
+```
+### Install with pip:
+```
+pip install plotilleresample
+```
+
+plotilleresample has no runtime dependencies — not even plotille: it only reduces sequences. To run the example below, install plotille as well (`uv add plotille` or `pip install plotille`).
+
+## Usage
+```python
+import math
+
+import plotille
+
+from plotilleresample import resample_plot_minmax_lttb
+
+r = 100_000
+X = list(range(r))
+Y = [math.sin(i / 500) * 100 for i in range(r)]
+
+X, Y = resample_plot_minmax_lttb(X, Y, width=80, height=40)
+print(plotille.plot(X, Y, width=80, height=40))
+```
+
+The full interactive demo, running every resampler on the same dataset, lives in [`examples/demo.py`](examples/demo.py).

{plotilleresample-0.4 → plotilleresample-1.0}/plotilleresample.egg-info/SOURCES.txt

@@ -1,8 +1,10 @@
+LICENSE
 README.md
-setup.py
+pyproject.toml
 plotilleresample/__init__.py
 plotilleresample/plotilleresample.py
 plotilleresample.egg-info/PKG-INFO
 plotilleresample.egg-info/SOURCES.txt
 plotilleresample.egg-info/dependency_links.txt
-plotilleresample.egg-info/top_level.txt
+plotilleresample.egg-info/top_level.txt
+tests/test_plotilleresample.py

plotilleresample-1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=77.0.3", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "plotilleresample"
+version = "1.0"
+description = "Python module to resample datasets before plotting with Plotille."
+readme = "README.md"
+
+license = "MIT"
+license-files = ["LICENSE"]
+
+authors = [
+    {name = "Carlos A. Planchón", email = "carlosandresplanchonprestes@gmail.com"}
+]
+keywords = ["plotting", "ascii", "math", "resample"]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Topic :: Scientific/Engineering :: Visualization",
+    "Topic :: Terminals",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14"
+
+]
+requires-python = ">=3.10"
+
+[project.urls]
+Homepage = "https://github.com/carlosplanchon/plotilleresample"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["plotilleresample*"]
+
+[dependency-groups]
+dev = ["pytest>=8"]
+bench = ["plotille"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff.lint]
+# Select the classic default ruleset explicitly (pyflakes + a pycodestyle
+# subset) so linting stays deterministic across ruff releases. ruff 0.16
+# widened its implicit default, which broke `uvx ruff check` in CI.
+select = ["E4", "E7", "E9", "F"]

plotilleresample-1.0/tests/test_plotilleresample.py

@@ -0,0 +1,240 @@
+#!/usr/bin/env python3
+
+"""
+Tests for plotilleresample.
+
+Run with pytest, or directly:
+    python tests/test_plotilleresample.py
+"""
+
+import math
+import sys
+
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from plotilleresample import resample_plot
+from plotilleresample import resample_plot_lttb
+from plotilleresample import resample_plot_minmax
+from plotilleresample import resample_plot_minmax_lttb
+from plotilleresample import resample_scatter
+
+
+def test_resample_plot_size():
+    r = 10000
+    X = list(range(r))
+    Y = [math.sin(i / 100) * 100 for i in range(r)]
+    xp, yp = resample_plot(X, Y, 80, 40)
+    assert len(xp) == len(yp)
+    assert len(xp) <= 80 * 4
+
+
+def test_resample_scatter_size():
+    for r in (9000, 10000):
+        xs, ys = resample_scatter(list(range(r)), list(range(r)), 80, 40)
+        assert len(xs) == len(ys)
+        assert len(xs) <= 80 * 2 * 40
+
+
+def test_minmax_passthrough_short_input():
+    X = [1.0, 2.0]
+    Y = [3.0, 4.0]
+    assert resample_plot_minmax(X, Y, 80, 40) == (X, Y)
+    assert resample_plot_minmax([], [], 80, 40) == ([], [])
+
+
+def test_minmax_size_within_target():
+    r = 10000
+    X = list(range(r))
+    Y = [math.sin(i / 100) * 100 for i in range(r)]
+    xm, ym = resample_plot_minmax(X, Y, 80, 40)
+    assert len(xm) == len(ym)
+    assert len(xm) <= 80 * 4
+
+
+def test_minmax_x_stays_sorted():
+    r = 10000
+    X = list(range(r))
+    Y = [math.sin(i / 7) * 100 for i in range(r)]
+    xm, _ = resample_plot_minmax(X, Y, 80, 40)
+    assert all(a <= b for a, b in zip(xm, xm[1:]))
+
+
+def test_minmax_preserves_envelope():
+    r = 10000
+    X = list(range(r))
+    Y = [math.sin(i / 100) * 100 for i in range(r)]
+    _, ym = resample_plot_minmax(X, Y, 80, 40)
+    assert max(ym) == max(Y)
+    assert min(ym) == min(Y)
+
+
+def test_spike_survives_minmax_but_not_stride():
+    # A flat signal with one spike placed off the stride grid:
+    # resample_plot with 10000 points and width 80 keeps indices
+    # 0, 32, 64, ... (step = ceil(10000 / 320) = 32), so the spike
+    # at index 33 is dropped. The minmax bucket containing index 33
+    # keeps it as the bucket maximum.
+    r = 10000
+    X = list(range(r))
+    Y = [0.0] * r
+    Y[33] = 1000.0
+
+    _, y_stride = resample_plot(X, Y, 80, 40)
+    _, y_minmax = resample_plot_minmax(X, Y, 80, 40)
+
+    assert 1000.0 not in y_stride
+    assert 1000.0 in y_minmax
+
+
+def test_minmax_constant_data_dedups():
+    # min and max coincide in every bucket -> one point per bucket.
+    r = 10000
+    X = list(range(r))
+    Y = [5.0] * r
+    xm, ym = resample_plot_minmax(X, Y, 80, 40)
+    assert len(xm) == 80 * 4 // 2
+    assert set(ym) == {5.0}
+
+
+def test_lttb_size_exact():
+    r = 10000
+    X = list(range(r))
+    Y = [math.sin(i / 100) * 100 for i in range(r)]
+    xl, yl = resample_plot_lttb(X, Y, 80, 40)
+    assert len(xl) == len(yl) == 80 * 4
+
+
+def test_lttb_passthrough_short_input():
+    X = [1.0, 2.0]
+    Y = [3.0, 4.0]
+    assert resample_plot_lttb(X, Y, 80, 40) == (X, Y)
+    assert resample_plot_lttb([], [], 80, 40) == ([], [])
+
+
+def test_lttb_keeps_endpoints_and_sorted_x():
+    r = 10000
+    X = list(range(r))
+    Y = [math.sin(i / 7) * 100 for i in range(r)]
+    xl, yl = resample_plot_lttb(X, Y, 80, 40)
+    assert xl[0] == X[0] and yl[0] == Y[0]
+    assert xl[-1] == X[-1] and yl[-1] == Y[-1]
+    assert all(a <= b for a, b in zip(xl, xl[1:]))
+
+
+def test_lttb_keeps_a_solitary_spike():
+    r = 10000
+    X = list(range(r))
+    Y = [0.0] * r
+    Y[33] = 1000.0
+    _, yl = resample_plot_lttb(X, Y, 80, 40)
+    assert 1000.0 in yl
+
+
+def test_lttb_drops_one_of_two_opposing_extremes():
+    # The documented trade-off: with a peak and a valley falling in
+    # the same bucket, LTTB keeps exactly one shape point while
+    # minmax keeps both extremes.
+    r = 10000
+    X = list(range(r))
+    Y = [0.0] * r
+    Y[33] = 1000.0
+    Y[40] = -1000.0
+
+    _, yl = resample_plot_lttb(X, Y, 80, 40)
+    _, ym = resample_plot_minmax(X, Y, 80, 40)
+
+    assert (1000.0 in yl) != (-1000.0 in yl)
+    assert 1000.0 in ym and -1000.0 in ym
+
+
+def test_minmax_lttb_size_endpoints_and_sorted_x():
+    r = 10000
+    X = list(range(r))
+    Y = [math.sin(i / 100) * 100 for i in range(r)]
+    xh, yh = resample_plot_minmax_lttb(X, Y, 80, 40)
+    assert len(xh) == len(yh) == 80 * 4
+    assert xh[0] == X[0] and yh[0] == Y[0]
+    assert xh[-1] == X[-1] and yh[-1] == Y[-1]
+    assert all(a <= b for a, b in zip(xh, xh[1:]))
+
+
+def test_minmax_lttb_passthrough_short_input():
+    X = [1.0, 2.0]
+    Y = [3.0, 4.0]
+    assert resample_plot_minmax_lttb(X, Y, 80, 40) == (X, Y)
+    assert resample_plot_minmax_lttb([], [], 80, 40) == ([], [])
+
+
+def test_minmax_lttb_keeps_a_solitary_spike():
+    r = 10000
+    X = list(range(r))
+    Y = [0.0] * r
+    Y[33] = 1000.0
+    _, yh = resample_plot_minmax_lttb(X, Y, 80, 40)
+    assert 1000.0 in yh
+
+
+def test_minmax_lttb_matches_pure_lttb_below_ratio_threshold():
+    # With n_out < len(X) <= n_out * minmax_ratio there is no
+    # preselection, so hybrid and pure LTTB must return the same points.
+    r = 1000
+    X = list(range(r))
+    Y = [math.sin(i / 7) * 100 for i in range(r)]
+    assert (
+        resample_plot_minmax_lttb(X, Y, 80, 40)
+        == resample_plot_lttb(X, Y, 80, 40)
+        )
+
+
+def _raises_value_error(fn, *args):
+    try:
+        fn(*args)
+    except ValueError:
+        return True
+    return False
+
+
+def test_length_mismatch_raises():
+    X = list(range(1000))
+    Y = list(range(500))
+    for fn in (
+        resample_plot, resample_plot_lttb, resample_plot_minmax,
+        resample_plot_minmax_lttb, resample_scatter,
+            ):
+        assert _raises_value_error(fn, X, Y, 80, 40), fn.__name__
+    # Fail fast even when the input is below the resampling threshold.
+    assert _raises_value_error(resample_plot, [1.0], [1.0, 2.0], 80, 40)
+
+
+def test_non_positive_width_raises():
+    X = list(range(1000))
+    for fn in (
+        resample_plot, resample_plot_lttb, resample_plot_minmax,
+        resample_plot_minmax_lttb, resample_scatter,
+            ):
+        for w in (0, -5):
+            assert _raises_value_error(fn, X, X, w, 40), fn.__name__
+
+
+def test_non_positive_height_raises_only_in_scatter():
+    X = list(range(1000))
+    for h in (0, -5):
+        assert _raises_value_error(resample_scatter, X, X, 80, h)
+        # height is unused in the plot resamplers, so it stays permissive.
+        assert not _raises_value_error(resample_plot, X, X, 80, h)
+        assert not _raises_value_error(resample_plot_lttb, X, X, 80, h)
+        assert not _raises_value_error(resample_plot_minmax, X, X, 80, h)
+        assert not _raises_value_error(resample_plot_minmax_lttb, X, X, 80, h)
+
+
+if __name__ == "__main__":
+    tests = [
+        fn for name, fn in sorted(globals().items())
+        if name.startswith("test_")
+        ]
+    for fn in tests:
+        fn()
+        print(f"{fn.__name__} OK")
+    print(f"--- {len(tests)} tests OK ---")

plotilleresample-0.4/PKG-INFO

@@ -1,81 +0,0 @@
-Metadata-Version: 2.1
-Name: plotilleresample
-Version: 0.4
-Summary: Python3 module to resample datasetsbefore plotting with Plotille.
-Home-page: https://github.com/carlosplanchon/plotilleresample
-Author: Carlos A. Planchón
-Author-email: bubbledoloresuruguay2@gmail.com
-License: GPL3
-Download-URL: https://github.com/carlosplanchon/plotilleresample/archive/v0.4.tar.gz
-Description: # plotilleresample
-        *Python3 module to resample datasets before plotting with Plotille.*
-        
-        # Rationale
-        I want to optimize plot and scatter function of plotille.
-        
-        ## Installation
-        ### Install with pip
-        ```
-        pip3 install -U servusresample
-        ```
-        
-        ## Usage
-        ```
-        #!/usr/bin/env python3
-        
-        import plotille
-        
-        import plotilledimreduction
-        
-        import math
-        
-        from shutil import get_terminal_size
-        
-        from vtclear import clear_screen
-        
-        import numpy as np
-        
-        
-        w = get_terminal_size().columns - 20
-        h = get_terminal_size().lines - 7
-        
-        r = 10000
-        res = np.random.normal(size=r)
-        
-        # Here I'm testing stuffs with histograms.
-        # input("Histogram:")
-        # print(plotille.histogram(res, bins=w*2, width=w, height=h))
-        
-        X = [i for i in range(r)]
-        Y = [math.sin(i / 100) * 100 for i in range(r)]
-        
-        print(" · Scatter...")
-        xs, ys = plotilledimreduction.dim_reduction_scatter(X, Y, w, h)
-        print(" · Plot...")
-        xp, yp = plotilledimreduction.dim_reduction_plot(X, Y, w, h)
-        print(" --- READY ---")
-        
-        print(f"Len plot.x {len(xp)}")
-        
-        print(f"Len scatter.x {len(xs)}")
-        
-        input("Plot:")
-        clear_screen()
-        print(plotille.plot(xp, yp, w, h))
-        
-        input("Scatter:")
-        clear_screen()
-        print(plotille.plot(xs, ys, w, h))
-        ```
-        
-Keywords: plotting,ascii,math,resample
-Platform: UNKNOWN
-Classifier: Intended Audience :: Developers
-Classifier: Topic :: Software Development :: Build Tools
-Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.4
-Classifier: Programming Language :: Python :: 3.5
-Classifier: Programming Language :: Python :: 3.6
-Classifier: Programming Language :: Python :: 3.7
-Description-Content-Type: text/markdown

plotilleresample-0.4/README.md

@@ -1,60 +0,0 @@
-# plotilleresample
-*Python3 module to resample datasets before plotting with Plotille.*
-
-# Rationale
-I want to optimize plot and scatter function of plotille.
-
-## Installation
-### Install with pip
-```
-pip3 install -U servusresample
-```
-
-## Usage
-```
-#!/usr/bin/env python3
-
-import plotille
-
-import plotilledimreduction
-
-import math
-
-from shutil import get_terminal_size
-
-from vtclear import clear_screen
-
-import numpy as np
-
-
-w = get_terminal_size().columns - 20
-h = get_terminal_size().lines - 7
-
-r = 10000
-res = np.random.normal(size=r)
-
-# Here I'm testing stuffs with histograms.
-# input("Histogram:")
-# print(plotille.histogram(res, bins=w*2, width=w, height=h))
-
-X = [i for i in range(r)]
-Y = [math.sin(i / 100) * 100 for i in range(r)]
-
-print(" · Scatter...")
-xs, ys = plotilledimreduction.dim_reduction_scatter(X, Y, w, h)
-print(" · Plot...")
-xp, yp = plotilledimreduction.dim_reduction_plot(X, Y, w, h)
-print(" --- READY ---")
-
-print(f"Len plot.x {len(xp)}")
-
-print(f"Len scatter.x {len(xs)}")
-
-input("Plot:")
-clear_screen()
-print(plotille.plot(xp, yp, w, h))
-
-input("Scatter:")
-clear_screen()
-print(plotille.plot(xs, ys, w, h))
-```

plotilleresample-0.4/plotilleresample/__init__.py

@@ -1,4 +0,0 @@
-#!/usr/bin/env python3
-
-from plotilleresample.plotilleresample import resample_plot
-from plotilleresample.plotilleresample import resample_scatter

plotilleresample-0.4/plotilleresample/plotilleresample.py

@@ -1,75 +0,0 @@
-#!/usr/bin/env python3
-
-from typing import List, Tuple
-
-# This value is used to avoid Nyquist related problems.
-plot_multiplier = 4
-
-list_val = List[int]
-
-
-def resample_plot(
-    X: list_val,
-    Y: list_val,
-    width: int = 80,
-    height: int = 40
-        ) -> Tuple[list_val, list_val]:
-    """
-
-    :param X: list_val: List of X values.
-    :param Y: list_val: List of Y values.
-    :param width: int: Width of the plot. (Default value = 80)
-    :param height: int: Height of the plot. (Default value = 40)
-
-    """
-    if len(X) > width * plot_multiplier:
-        step = round(len(X) / width / plot_multiplier)
-        print(step)
-
-        if step != 0:
-            X = [
-                X[i] for i in range(
-                    0, len(X), step
-                    )
-                ]
-            Y = [
-                Y[i] for i in range(
-                    0, len(Y), step
-                    )
-                ]
-
-    return X, Y
-
-
-def resample_scatter(
-    X: list_val,
-    Y: list_val,
-    width: int = 80,
-    height: int = 40
-        ) -> Tuple[list_val, list_val]:
-    """
-
-    :param X: list_val: List of X values.
-    :param Y: list_val: List of Y values.
-    :param width: int: Width of the plot. (Default value = 80)
-    :param height: int: Height of the plot. (Default value = 40)
-
-    """
-    scatter_multiplier = width * 2 * height
-    if len(X) > scatter_multiplier:
-        step = round(len(X) / scatter_multiplier)
-        print(step)
-
-        if step != 0:
-            X = [
-                X[i] for i in range(
-                    0, len(X), step
-                    )
-                ]
-            Y = [
-                Y[i] for i in range(
-                    0, len(Y), step
-                    )
-                ]
-
-    return X, Y

plotilleresample-0.4/plotilleresample.egg-info/PKG-INFO

@@ -1,81 +0,0 @@
-Metadata-Version: 2.1
-Name: plotilleresample
-Version: 0.4
-Summary: Python3 module to resample datasetsbefore plotting with Plotille.
-Home-page: https://github.com/carlosplanchon/plotilleresample
-Author: Carlos A. Planchón
-Author-email: bubbledoloresuruguay2@gmail.com
-License: GPL3
-Download-URL: https://github.com/carlosplanchon/plotilleresample/archive/v0.4.tar.gz
-Description: # plotilleresample
-        *Python3 module to resample datasets before plotting with Plotille.*
-        
-        # Rationale
-        I want to optimize plot and scatter function of plotille.
-        
-        ## Installation
-        ### Install with pip
-        ```
-        pip3 install -U servusresample
-        ```
-        
-        ## Usage
-        ```
-        #!/usr/bin/env python3
-        
-        import plotille
-        
-        import plotilledimreduction
-        
-        import math
-        
-        from shutil import get_terminal_size
-        
-        from vtclear import clear_screen
-        
-        import numpy as np
-        
-        
-        w = get_terminal_size().columns - 20
-        h = get_terminal_size().lines - 7
-        
-        r = 10000
-        res = np.random.normal(size=r)
-        
-        # Here I'm testing stuffs with histograms.
-        # input("Histogram:")
-        # print(plotille.histogram(res, bins=w*2, width=w, height=h))
-        
-        X = [i for i in range(r)]
-        Y = [math.sin(i / 100) * 100 for i in range(r)]
-        
-        print(" · Scatter...")
-        xs, ys = plotilledimreduction.dim_reduction_scatter(X, Y, w, h)
-        print(" · Plot...")
-        xp, yp = plotilledimreduction.dim_reduction_plot(X, Y, w, h)
-        print(" --- READY ---")
-        
-        print(f"Len plot.x {len(xp)}")
-        
-        print(f"Len scatter.x {len(xs)}")
-        
-        input("Plot:")
-        clear_screen()
-        print(plotille.plot(xp, yp, w, h))
-        
-        input("Scatter:")
-        clear_screen()
-        print(plotille.plot(xs, ys, w, h))
-        ```
-        
-Keywords: plotting,ascii,math,resample
-Platform: UNKNOWN
-Classifier: Intended Audience :: Developers
-Classifier: Topic :: Software Development :: Build Tools
-Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.4
-Classifier: Programming Language :: Python :: 3.5
-Classifier: Programming Language :: Python :: 3.6
-Classifier: Programming Language :: Python :: 3.7
-Description-Content-Type: text/markdown

plotilleresample-0.4/setup.py

@@ -1,34 +0,0 @@
-#!/usr/bin/env python3
-
-from setuptools import setup
-
-
-with open("README.md", "r") as f:
-    readme = f.read()
-
-setup(
-    name="plotilleresample",
-    packages=["plotilleresample"],
-    version="0.4",
-    license="GPL3",
-    description="Python3 module to resample datasets"
-            "before plotting with Plotille.",
-    long_description=readme,
-    long_description_content_type="text/markdown",
-    author="Carlos A. Planchón",
-    author_email="bubbledoloresuruguay2@gmail.com",
-    url="https://github.com/carlosplanchon/plotilleresample",
-    download_url="https://github.com/carlosplanchon/"
-        "plotilleresample/archive/v0.4.tar.gz",
-    keywords=["plotting", "ascii", "math", "resample"],
-    classifiers=[
-        "Intended Audience :: Developers",
-        "Topic :: Software Development :: Build Tools",
-        "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
-        "Programming Language :: Python :: 3",
-        "Programming Language :: Python :: 3.4",
-        "Programming Language :: Python :: 3.5",
-        "Programming Language :: Python :: 3.6",
-        "Programming Language :: Python :: 3.7",
-    ],
-)