plotille 6.0.0__py3-none-any.whl

plotille/_figure_data.py

@@ -0,0 +1,295 @@
+# The MIT License
+
+# Copyright (c) 2017 - 2025 Tammo Ippen, tammo.ippen@posteo.de
+
+# 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.
+
+"""Data container classes for plotille.
+
+Architecture Note:
+------------------
+All input data (X, Y values) is normalized to float immediately upon construction:
+
+- Numeric values (int, float) are converted to float
+- Datetime values are converted to timestamps (float)
+- Original type information is preserved in DataMetadata objects
+- This allows type-safe internal operations while maintaining a flexible
+  public API
+
+The normalization happens in each class's __init__ method using InputFormatter.
+Display formatting (axis labels, etc.) uses the metadata to format values
+correctly for the original type.
+"""
+
+from collections.abc import Sequence
+from typing import Literal, final
+
+from plotille._canvas import Canvas
+from plotille._colors import ColorDefinition
+from plotille._data_metadata import DataMetadata
+from plotille._input_formatter import InputFormatter
+
+from . import Colormap, _cmaps
+from ._util import DataValues, hist
+
+
+class Plot:
+    def __init__(
+        self,
+        X: DataValues,
+        Y: DataValues,
+        lc: ColorDefinition,
+        interp: Literal["linear"] | None,
+        label: str | None,
+        marker: str | None,
+        formatter: InputFormatter | None = None,
+    ) -> None:
+        if len(X) != len(Y):
+            raise ValueError("X and Y dim have to be the same.")
+        if interp not in ("linear", None):
+            raise ValueError('Only "linear" and None are allowed values for `interp`.')
+
+        self._formatter = formatter if formatter is not None else InputFormatter()
+        self.X_metadata = DataMetadata.from_sequence(X)
+        self.Y_metadata = DataMetadata.from_sequence(Y)
+        self.X = [self._formatter.convert(x) for x in X]
+        self.Y = [self._formatter.convert(y) for y in Y]
+
+        self.lc = lc
+        self.interp = interp
+        self.label = label
+        self.marker = marker
+
+    def width_vals(self) -> list[float]:
+        """Return X values as floats for limit calculation."""
+        return self.X
+
+    def height_vals(self) -> list[float]:
+        """Return Y values as floats for limit calculation."""
+        return self.Y
+
+    def write(self, canvas: Canvas, with_colors: bool, in_fmt: InputFormatter) -> None:
+        from_points = zip(self.X, self.Y, strict=True)
+        to_points = zip(self.X, self.Y, strict=True)
+
+        # remove first point of to_points
+        (x0, y0) = next(to_points)
+
+        color = self.lc if with_colors else None
+
+        # print first point
+        canvas.point(x0, y0, color=color, marker=self.marker)
+
+        # plot other points and lines
+        for (x0, y0), (x, y) in zip(from_points, to_points, strict=False):
+            canvas.point(x, y, color=color, marker=self.marker)
+            if self.interp == "linear":
+                # no marker for interpolated values
+                canvas.line(x0, y0, x, y, color=color)
+
+
+@final
+class Histogram:
+    def __init__(self, X: DataValues, bins: int, lc: ColorDefinition) -> None:
+        # Normalize data first
+        self._formatter = InputFormatter()
+        self.X_metadata = DataMetadata.from_sequence(X)
+        self.X = [self._formatter.convert(x) for x in X]
+        # Histogram Y values are always numeric (frequency counts)
+        self.Y_metadata = DataMetadata(is_datetime=False, timezone=None)
+
+        # Compute histogram on normalized data
+        frequencies, buckets = hist(self.X, bins)
+
+        # Store everything
+        self.bins = bins
+        self.frequencies = frequencies
+        self.buckets = buckets
+        self.lc = lc
+
+    def width_vals(self) -> list[float]:
+        """Return normalized X values as floats."""
+        return self.X
+
+    def height_vals(self) -> list[int]:
+        """Return histogram frequencies."""
+        return self.frequencies
+
+    def write(self, canvas: Canvas, with_colors: bool, in_fmt: InputFormatter) -> None:
+        # how fat will one bar of the histogram be
+        x_diff = canvas.dots_between(self.buckets[0], 0, self.buckets[1], 0)[0] or 1
+        bin_size = (self.buckets[1] - self.buckets[0]) / x_diff
+
+        color = self.lc if with_colors else None
+        for i in range(self.bins):
+            # for each bucket
+            if self.frequencies[i] > 0:
+                for j in range(x_diff):
+                    # print bar
+                    x_ = self.buckets[i] + j * bin_size
+
+                    if canvas.xmin <= x_ <= canvas.xmax:
+                        canvas.line(x_, 0, x_, self.frequencies[i], color=color)
+
+
+@final
+class Text:
+    def __init__(
+        self,
+        X: DataValues,
+        Y: DataValues,
+        texts: Sequence[str],
+        lc: ColorDefinition,
+        formatter: InputFormatter | None = None,
+    ) -> None:
+        if len(X) != len(Y) != len(texts):
+            raise ValueError("X, Y and texts dim have to be the same.")
+
+        self._formatter = formatter if formatter is not None else InputFormatter()
+        self.X_metadata = DataMetadata.from_sequence(X)
+        self.Y_metadata = DataMetadata.from_sequence(Y)
+        self.X = [self._formatter.convert(x) for x in X]
+        self.Y = [self._formatter.convert(y) for y in Y]
+        self.texts = texts
+        self.lc = lc
+
+    def width_vals(self) -> list[float]:
+        """Return X values as floats for limit calculation."""
+        return self.X
+
+    def height_vals(self) -> list[float]:
+        """Return Y values as floats for limit calculation."""
+        return self.Y
+
+    def write(self, canvas: Canvas, with_colors: bool, in_fmt: InputFormatter) -> None:
+        points = zip(self.X, self.Y, self.texts, strict=True)
+
+        color = self.lc if with_colors else None
+
+        # plot texts with color
+        for x, y, text in points:
+            canvas.text(x, y, text, color=color)
+
+
+class Span:
+    def __init__(
+        self,
+        xmin: float,
+        xmax: float,
+        ymin: float,
+        ymax: float,
+        lc: ColorDefinition | None = None,
+    ):
+        if not (0 <= xmin <= xmax <= 1):
+            raise ValueError(
+                "xmin has to be <= xmax and both have to be within [0, 1]."
+            )
+        if not (0 <= ymin <= ymax <= 1):
+            raise ValueError(
+                "ymin has to be <= ymax and both have to be within [0, 1]."
+            )
+        self.xmin: float = xmin
+        self.xmax: float = xmax
+        self.ymin: float = ymin
+        self.ymax: float = ymax
+        self.lc: ColorDefinition | None = lc
+
+    def write(self, canvas: Canvas, with_colors: bool) -> None:
+        color = self.lc if with_colors else None
+
+        # plot texts with color
+        xdelta = canvas.xmax_inside - canvas.xmin
+        assert xdelta > 0
+
+        ydelta = canvas.ymax_inside - canvas.ymin
+        assert ydelta > 0
+
+        canvas.rect(
+            canvas.xmin + self.xmin * xdelta,
+            canvas.ymin + self.ymin * ydelta,
+            canvas.xmin + self.xmax * xdelta,
+            canvas.ymin + self.ymax * ydelta,
+            color=color,
+        )
+
+
+HeatInput = Sequence[Sequence[float]] | Sequence[Sequence[Sequence[float]]]
+
+
+@final
+class Heat:
+    def __init__(self, X: HeatInput, cmap: str | Colormap | None = None):
+        """Initialize a Heat-class.
+
+        Parameters
+        ----------
+        X: array-like
+            The image data. Supported array shapes are:
+            - (M, N): an image with scalar data. The values are mapped
+                      to colors using a colormap. The values have to be in
+                      the 0-1 (float) range. Out of range, invalid type and
+                      None values are handled by the cmap.
+            - (M, N, 3): an image with RGB values (0-1 float or 0-255 int).
+
+            The first two dimensions (M, N) define the rows and columns of the image.
+
+        cmap: cmapstr or Colormap, default: 'viridis'
+            The Colormap instance or registered colormap name used
+            to map scalar data to colors. This parameter is ignored
+            for RGB data.
+        """
+        assert len(X)
+        assert cmap is None or isinstance(cmap, (str, _cmaps.Colormap))
+        len_first = len(X[0])
+        assert all(len(x) == len_first for x in X)
+        self._X: HeatInput = X
+
+        if cmap is None:
+            cmap = "viridis"
+
+        if isinstance(cmap, str):
+            cmap = _cmaps.cmaps[cmap]()
+        self.cmap = cmap
+
+    @property
+    def X(self) -> HeatInput:
+        return self._X
+
+    def write(self, canvas: Canvas) -> None:
+        assert len(self.X)
+        assert canvas.height == len(self.X)
+        assert canvas.width == len(self.X[0])
+
+        flat = [x for xs in self.X for x in xs]
+        try:
+            assert all(len(pixel) == 3 for pixel in flat)  # type: ignore[arg-type]
+            # assume rgb
+            if all(
+                isinstance(v, float) and 0 <= v <= 1
+                for pixel in flat
+                for v in pixel  # type: ignore[union-attr]
+            ):
+                # 0 - 1 values => make 0-255 int values
+                flat = [  # type: ignore[misc]
+                    (round(r * 255), round(g * 255), round(b * 255)) for r, g, b in flat
+                ]
+            canvas.image(flat)  # type: ignore[arg-type]
+        except TypeError:
+            # cannot call len on a float
+            canvas.image(self.cmap(flat))  # type: ignore[arg-type]

plotille/_graphs.py

@@ -0,0 +1,373 @@
+# The MIT License
+
+# Copyright (c) 2017 - 2025 Tammo Ippen, tammo.ippen@posteo.de
+
+# 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.
+
+import os
+from collections.abc import Sequence
+from datetime import timedelta
+from math import log
+from typing import Literal
+
+from ._colors import ColorDefinition, ColorMode, color
+from ._data_metadata import DataMetadata
+from ._figure import Figure
+from ._input_formatter import InputFormatter
+from ._util import DataValue, DataValues
+from ._util import hist as compute_hist
+
+
+def hist_aggregated(
+    counts: list[int],
+    bins: Sequence[float],
+    width: int = 80,
+    log_scale: bool = False,
+    linesep: str = os.linesep,
+    lc: ColorDefinition = None,
+    bg: ColorDefinition = None,
+    color_mode: ColorMode = "names",
+    meta: DataMetadata | None = None,
+) -> str:
+    """
+    Create histogram for aggregated data.
+
+    Parameters:
+        counts: List[int]         Counts for each bucket.
+        bins: List[float]         Limits for the bins for the provided counts: limits for
+                                  bin `i` are `[bins[i], bins[i+1])`.
+                                  Hence, `len(bins) == len(counts) + 1`.
+        width: int                The number of characters for the width (columns).
+        log_scale: bool           Scale the histogram with `log` function.
+        linesep: str              The requested line separator. default: os.linesep
+        lc: ColorDefinition       Give the line color.
+        bg: ColorDefinition       Give the background color.
+        color_mode: ColorMode     Specify color input mode; 'names' (default), 'byte' or
+                                  'rgb' see plotille.color.__docs__
+        meta: DataMetadata | None For conversion of datetime values.
+    Returns:
+        str: histogram over `X` from left to right.
+    """
+
+    def _scale(a: int) -> float | int:
+        if log_scale and a > 0:
+            return log(a)
+        return a
+
+    if meta is None:
+        meta = DataMetadata(is_datetime=False)
+
+    h = counts
+    b = bins
+
+    ipf = InputFormatter()
+    h_max = _scale(max(h)) or 1
+    max_ = b[-1]
+    min_ = b[0]
+    # bins are always normalized to float
+    delta = max_ - min_
+    delta_display = timedelta(seconds=delta) if meta.is_datetime else delta
+
+    bins_count = len(h)
+
+    canvas = ["        bucket       | {} {}".format("_" * width, "Total Counts")]
+    lasts = ["", "⠂", "⠆", "⠇", "⡇", "⡗", "⡷", "⡿"]
+    for i in range(bins_count):
+        height = int(width * 8 * _scale(h[i]) / h_max)
+        canvas += [
+            "[{}, {}) | {} {}".format(
+                ipf.fmt(
+                    meta.convert_for_display(b[i]),
+                    delta=delta_display,
+                    chars=8,
+                    left=True,
+                ),
+                ipf.fmt(
+                    meta.convert_for_display(b[i + 1]),
+                    delta=delta_display,
+                    chars=8,
+                    left=False,
+                ),
+                color(
+                    "⣿" * (height // 8) + lasts[height % 8],
+                    fg=lc,
+                    bg=bg,
+                    mode=color_mode,
+                )
+                + color(
+                    "\u2800" * (width - (height // 8) + int(height % 8 == 0)),
+                    bg=bg,
+                    mode=color_mode,
+                ),
+                h[i],
+            )
+        ]
+    canvas += ["‾" * (2 * 8 + 2 + 3 + width + 12)]
+    return linesep.join(canvas)
+
+
+def hist(
+    X: DataValues,
+    bins: int = 40,
+    width: int = 80,
+    log_scale: bool = False,
+    linesep: str = os.linesep,
+    lc: ColorDefinition = None,
+    bg: ColorDefinition = None,
+    color_mode: ColorMode = "names",
+) -> str:
+    """Create histogram over `X` from left to right
+
+    The values on the left are the center of the bucket, i.e. `(bin[i] + bin[i+1]) / 2`.
+    The values on the right are the total counts of this bucket.
+
+    Parameters:
+        X: List[float]       The items to count over.
+        bins: int            The number of bins to put X entries in (rows).
+        width: int           The number of characters for the width (columns).
+        log_scale: bool      Scale the histogram with `log` function.
+        linesep: str         The requested line separator. default: os.linesep
+        lc: ColorDefinition         Give the line color.
+        bg: ColorDefinition         Give the background color.
+        color_mode: ColorMode      Specify color input mode; 'names' (default), 'byte' or
+                             'rgb' see plotille.color.__docs__
+
+    Returns:
+        str: histogram over `X` from left to right.
+    """
+    # Normalize data to float before computing histogram
+    formatter = InputFormatter()
+    metadata = DataMetadata.from_sequence(X)
+    X_floats = [formatter.convert(x) for x in X]
+
+    counts, bins_list = compute_hist(X_floats, bins)
+
+    # bins_list are floats, use metadata for display
+    return hist_aggregated(
+        counts=counts,
+        bins=bins_list,
+        width=width,
+        log_scale=log_scale,
+        linesep=linesep,
+        lc=lc,
+        bg=bg,
+        color_mode=color_mode,
+        meta=metadata,
+    )
+
+
+def histogram(
+    X: DataValues,
+    bins: int = 160,
+    width: int = 80,
+    height: int = 40,
+    X_label: str = "X",
+    Y_label: str = "Counts",
+    linesep: str = os.linesep,
+    x_min: DataValue | None = None,
+    x_max: DataValue | None = None,
+    y_min: DataValue | None = None,
+    y_max: DataValue | None = None,
+    lc: ColorDefinition = None,
+    bg: ColorDefinition = None,
+    color_mode: ColorMode = "names",
+) -> str:
+    """Create histogram over `X`
+
+    In contrast to `hist`, this is the more `usual` histogram from bottom
+    to up. The X-axis represents the values in `X` and the Y-axis is the
+    corresponding frequency.
+
+    Parameters:
+        X: List[float]       The items to count over.
+        bins: int            The number of bins to put X entries in (columns).
+        height: int          The number of characters for the height (rows).
+        X_label: str         Label for X-axis.
+        Y_label: str         Label for Y-axis. max 8 characters.
+        linesep: str         The requested line separator. default: os.linesep
+        x_min, x_max: float  Limits for the displayed X values.
+        y_min, y_max: float  Limits for the displayed Y values.
+        lc: ColorDefinition         Give the line color.
+        bg: ColorDefinition         Give the background color.
+        color_mode: ColorMode      Specify color input mode; 'names' (default), 'byte' or
+                             'rgb' see plotille.color.__docs__
+
+    Returns:
+        str: histogram over `X`.
+    """
+    fig = Figure()
+    fig.width = width
+    fig.height = height
+    fig.x_label = X_label
+    fig.y_label = Y_label
+    fig.linesep = linesep
+    if x_min is not None:
+        fig.set_x_limits(min_=x_min)
+    if x_max is not None:
+        fig.set_x_limits(max_=x_max)
+    if y_min is not None:
+        fig.set_y_limits(min_=y_min)
+    if y_max is not None:
+        fig.set_y_limits(max_=y_max)
+    fig.background = bg
+    fig.color_mode = color_mode
+
+    if lc is None and bg is None:
+        fig.with_colors = False
+
+    fig.histogram(X, bins, lc)
+
+    return fig.show()
+
+
+def scatter(
+    X: DataValues,
+    Y: DataValues,
+    width: int = 80,
+    height: int = 40,
+    X_label: str = "X",
+    Y_label: str = "Y",
+    linesep: str = os.linesep,
+    x_min: DataValue | None = None,
+    x_max: DataValue | None = None,
+    y_min: DataValue | None = None,
+    y_max: DataValue | None = None,
+    lc: ColorDefinition = None,
+    bg: ColorDefinition = None,
+    color_mode: ColorMode = "names",
+    origin: bool = True,
+    marker: str | None = None,
+) -> str:
+    """Create scatter plot with X , Y values
+
+    Basically plotting without interpolation:
+        `plot(X, Y, ... , interp=None)`
+
+    Parameters:
+        X: List[float]       X values.
+        Y: List[float]       Y values. X and Y must have the same number of entries.
+        width: int           The number of characters for the width (columns) of the
+                             canvas.
+        height: int          The number of characters for the hight (rows) of the
+                             canvas.
+        X_label: str         Label for X-axis.
+        Y_label: str         Label for Y-axis. max 8 characters.
+        linesep: str         The requested line separator. default: os.linesep
+        x_min, x_max: float  Limits for the displayed X values.
+        y_min, y_max: float  Limits for the displayed Y values.
+        lc: ColorDefinition         Give the line color.
+        bg: ColorDefinition         Give the background color.
+        color_mode: ColorMode      Specify color input mode; 'names' (default), 'byte' or
+                             'rgb' see plotille.color.__docs__
+        origin: bool         Whether to print the origin. default: True
+        marker: str          Instead of braille dots set a marker char.
+
+    Returns:
+        str: scatter plot over `X`, `Y`.
+    """
+    return plot(
+        X,
+        Y,
+        width,
+        height,
+        X_label,
+        Y_label,
+        linesep,
+        None,
+        x_min,
+        x_max,
+        y_min,
+        y_max,
+        lc,
+        bg,
+        color_mode,
+        origin,
+        marker,
+    )
+
+
+def plot(
+    X: DataValues,
+    Y: DataValues,
+    width: int = 80,
+    height: int = 40,
+    X_label: str = "X",
+    Y_label: str = "Y",
+    linesep: str = os.linesep,
+    interp: Literal["linear"] | None = "linear",
+    x_min: DataValue | None = None,
+    x_max: DataValue | None = None,
+    y_min: DataValue | None = None,
+    y_max: DataValue | None = None,
+    lc: ColorDefinition = None,
+    bg: ColorDefinition = None,
+    color_mode: ColorMode = "names",
+    origin: bool = True,
+    marker: str | None = None,
+) -> str:
+    """Create plot with X , Y values and linear interpolation between points
+
+    Parameters:
+        X: List[float]         X values.
+        Y: List[float]         Y values. X and Y must have the same number of entries.
+        width: int             The number of characters for the width (columns) of the
+                               canvas.
+        height: int            The number of characters for the hight (rows) of the
+                               canvas.
+        X_label: str           Label for X-axis.
+        Y_label: str           Label for Y-axis. max 8 characters.
+        linesep: str           The requested line separator. default: os.linesep
+        interp: Optional[str]  Specify interpolation; values None, 'linear'
+        x_min, x_max: float    Limits for the displayed X values.
+        y_min, y_max: float    Limits for the displayed Y values.
+        lc: ColorDefinition           Give the line color.
+        bg: ColorDefinition           Give the background color.
+        color_mode: ColorMode        Specify color input mode; 'names' (default), 'byte' or
+                               'rgb' see plotille.color.__docs__
+        origin: bool           Whether to print the origin. default: True
+        marker: str            Instead of braille dots set a marker char for actual
+                               values.
+
+    Returns:
+        str: plot over `X`, `Y`.
+    """
+    fig = Figure()
+    fig.width = width
+    fig.height = height
+    fig.x_label = X_label
+    fig.y_label = Y_label
+    fig.linesep = linesep
+    fig.origin = origin
+    if x_min is not None:
+        fig.set_x_limits(min_=x_min)
+    if x_max is not None:
+        fig.set_x_limits(max_=x_max)
+    if y_min is not None:
+        fig.set_y_limits(min_=y_min)
+    if y_max is not None:
+        fig.set_y_limits(max_=y_max)
+    fig.background = bg
+    fig.color_mode = color_mode
+
+    if lc is None and bg is None:
+        fig.with_colors = False
+
+    fig.plot(X, Y, lc, interp, marker=marker)
+
+    return fig.show()