leanplot 1.0.0__py3-none-any.whl

leanplot/__init__.py

@@ -0,0 +1,14 @@
+#  ------------------------------------------------------------------------------
+#  Copyright (c) 2026 Joel Kimmich
+#  ------------------------------------------------------------------------------
+#  License
+#      This file is part of LeanPlot, distributed under MIT license.
+#  ------------------------------------------------------------------------------
+#
+
+__all__ = []
+
+from leanplot.core import *
+from leanplot.core import __all__ as _core_all_
+
+__all__.extend(_core_all_)

leanplot/core/__init__.py

@@ -0,0 +1,38 @@
+#  ------------------------------------------------------------------------------
+#  Copyright (c) 2026 Joel Kimmich
+#  ------------------------------------------------------------------------------
+#  License
+#      This file is part of LeanPlot, distributed under MIT license.
+#  ------------------------------------------------------------------------------
+#
+
+from leanplot.core.bar import BarPlot, TimeBarPlot
+from leanplot.core.double_y import DoubleY
+from leanplot.core.functions import (
+    cm_to_inch,
+    custom_numeric_ticks_formatter,
+    format_date_x_axis,
+    is_numeric,
+    round_valid,
+)
+from leanplot.core.line import LinePlot, TimePlot
+from leanplot.core.mixin import PlotMixin
+
+__all__ = ["BarPlot", "TimeBarPlot"]
+__all__.extend(["DoubleY"])
+__all__.extend(
+    [
+        "is_numeric",
+        "cm_to_inch",
+        "custom_numeric_ticks_formatter",
+        "format_date_x_axis",
+        "round_valid",
+    ]
+)
+__all__.extend(["LinePlot", "TimePlot"])
+__all__.extend(["PlotMixin"])
+
+from .colors import *
+from .colors import __all__ as _colors_all_
+
+__all__.extend(_colors_all_)

leanplot/core/bar.py

@@ -0,0 +1,64 @@
+#  ------------------------------------------------------------------------------
+#  Copyright (c) 2026 Joel Kimmich
+#  ------------------------------------------------------------------------------
+#  License
+#      This file is part of LeanPlot, distributed under MIT license.
+#  ------------------------------------------------------------------------------
+#
+from datetime import timedelta
+
+import matplotlib.dates as mdates
+import numpy as np
+
+from leanplot.core.functions import format_date_x_axis, is_numeric
+from leanplot.core.mixin import PlotMixin
+
+
+class BarPlot(PlotMixin):
+    def __init__(self, bar_values, bar_positions=None, y_title="Heat / kWh", **kwargs):
+        assert len(bar_values) > 1
+        if bar_positions is None:
+            bar_positions = range(len(bar_values))
+        super().__init__(x=bar_positions, ys=bar_values, y_title=y_title, **kwargs)
+
+    @property
+    def bar_width(self):
+        if len(self.x) > 1:
+            diff = np.diff(self.x)
+            min_diff = np.min(diff)
+            return min_diff * 0.8
+        return 1
+
+    def plot(self):
+        self.ax.bar(self.x, self.ys, width=self.bar_width, color=next(self.next_color))
+        self.format()
+
+    def format(self):
+        super().format()
+        if is_numeric(self.x[0]):
+            self.ax.set_xlim(left=self.x[0] - self.bar_width / 0.8 / 2, right=self.x[-1] + self.bar_width / 0.8 / 2)
+        self.format_numeric_ticks()
+
+
+class TimeBarPlot(BarPlot):
+    def __init__(self, bar_values, bar_positions, y_title="Heat / kWh", **kwargs):
+        super().__init__(bar_values, bar_positions, y_title=y_title, **kwargs)
+
+    @property
+    def bar_width(self) -> float:
+        if len(self.x) > 1:
+            date_nums = mdates.date2num(self.x)
+            time_diffs = np.diff(date_nums)
+            min_diff = time_diffs[0]
+            return float(min_diff * 0.8)
+        else:
+            return 1 / 24
+
+    def format(self):
+        super().format()
+        format_date_x_axis(self.x[0], self.x[-1], self.ax, return_version=False)
+        self.ax.set_xlim(
+            left=self.x[0] - timedelta(days=self.bar_width / 0.8 / 2),
+            right=self.x[-1] + timedelta(days=self.bar_width / 0.8 / 2),
+        )
+        self.format_numeric_ticks()

leanplot/core/colors/__init__.py

@@ -0,0 +1,11 @@
+#  ------------------------------------------------------------------------------
+#  Copyright (c) 2026 Joel Kimmich
+#  ------------------------------------------------------------------------------
+#  License
+#      This file is part of LeanPlot, distributed under MIT license.
+#  ------------------------------------------------------------------------------
+#
+
+from leanplot.core.colors.categorical import ColorPalette
+
+__all__ = ["ColorPalette"]

leanplot/core/colors/categorical.py

@@ -0,0 +1,72 @@
+#  ------------------------------------------------------------------------------
+#  Copyright (c) 2026 Joel Kimmich
+#  ------------------------------------------------------------------------------
+#  License
+#      This file is part of LeanPlot, distributed under MIT license.
+#  ------------------------------------------------------------------------------
+#
+
+import cmcrameri.cm as cmc
+
+
+class ColorPalette:
+    """
+    Provide a categorical color palette from a pre-defined categorical colormap.
+
+    Parameters
+    ----------
+    colormap_name : str, default="batlow"
+        Base name of the colormap defined in `cmcrameri.cm`, without the categorical suffix
+        (for example "batlow", "grayC", "oslo"). The categorical variant is accessed by appending "S".
+    number_of_colors : int, default=5
+        Number of categorical colors to use from the colormap.
+    """
+
+    def __init__(self, colormap_name: str = "oslo", number_of_colors: int = 5) -> None:
+        self.colormap_name = colormap_name
+        self.number_of_colors = number_of_colors
+
+    @property
+    def colors(self) -> list[tuple[float, float, float]]:
+        """
+        Return categorical colors from the predefined categorical colormap.
+
+        Returns
+        -------
+        list[tuple[float, float, float]]
+            List of RGB color tuples with values in the range [0, 1].
+
+        Raises
+        ------
+        AttributeError
+            If the categorical colormap `f"{colormap_name}S"` is not defined in `cmcrameri.cm`.
+        ValueError
+            If `number_of_colors` exceeds the number of colors available in the categorical colormap.
+        """
+        categorical_colormap = getattr(cmc, f"{self.colormap_name}S")
+        available_colors = categorical_colormap.colors
+        if self.number_of_colors > len(available_colors):
+            raise ValueError(
+                f"Requested {self.number_of_colors} colors, but colormap "
+                f"'{self.colormap_name}S' only provides {len(available_colors)} colors."
+            )
+        return [tuple(color[:3]) for color in available_colors[: self.number_of_colors]]
+
+    @staticmethod
+    def available_categorical_colormap_names() -> list[str]:
+        """
+        Return the base names of all colormaps in `cmcrameri.cm` that provide a categorical variant.
+
+        Returns
+        -------
+        list[str]
+            Sorted list of base colormap names (without the categorical "S" suffix and without
+            reversed "_r" variants) for which `f"{name}S"` exists in `cmcrameri.cm`.
+        """
+        categorical_suffix = "S"
+        reversed_suffix = "_r"
+        base_names = []
+        for attribute_name in dir(cmc):
+            if attribute_name.endswith(categorical_suffix) and not attribute_name.endswith(reversed_suffix):
+                base_names.append(attribute_name[: -len(categorical_suffix)])
+        return sorted(base_names)

leanplot/core/double_y.py

@@ -0,0 +1,219 @@
+#  ------------------------------------------------------------------------------
+#  Copyright (c) 2026 Joel Kimmich
+#  ------------------------------------------------------------------------------
+#  License
+#      This file is part of LeanPlot, distributed under MIT license.
+#  ------------------------------------------------------------------------------
+#
+
+#  ------------------------------------------------------------------------------
+#  Copyright (c) 2026 Joel Kimmich
+#  ------------------------------------------------------------------------------
+#  License
+#      This file is part of LeanPlot, distributed under MIT license.
+#  ------------------------------------------------------------------------------
+#
+import numpy as np
+
+from leanplot.core.mixin import PlotMixin
+
+
+class DoubleY(PlotMixin):
+    def __init__(
+        self,
+        x,
+        ys_left: list,
+        ys_right: list,
+        labels_left=None,
+        labels_right=None,
+        y_title_left="Heat Flux / W",
+        y_title_right="Temperature / K",
+        marker_size=6,
+        **kwargs,
+    ):
+        if not isinstance(ys_left, list):
+            ys_left = [ys_left]
+        if not isinstance(ys_right, list):
+            ys_right = [ys_right]
+        ys_left = [np.array(y) for y in ys_left]
+        ys_right = [np.array(y) for y in ys_right]
+
+        super().__init__(x=np.array(x), ys=ys_left, y_title=y_title_left, marker_size=marker_size, **kwargs)
+
+        self.ys_left = ys_left
+        self.ys_right = ys_right
+        self.y_title_right = y_title_right
+
+        self.ax_right = self.ax.twinx()
+
+        if labels_left is None:
+            labels_left = [None] * len(ys_left)
+        if labels_right is None:
+            labels_right = [None] * len(ys_right)
+        if not isinstance(labels_left, list):
+            labels_left = [labels_left]
+        if not isinstance(labels_right, list):
+            labels_right = [labels_right]
+
+        self.labels_left = labels_left
+        self.labels_right = labels_right
+
+    @property
+    def ax_left(self):
+        return self.ax
+
+    def scale_right_axis(self):
+        """
+        Scales the right axis so that the major ticks matches the left one.
+        """
+        left_ticks = self.ax.get_yticks()
+        num_ticks = len(left_ticks)
+
+        # Get right axis data range
+        right_data_min, right_data_max = self.ax_right.get_ylim()
+        right_range = right_data_max - right_data_min
+
+        # Generate nice spacings: [1,2,5] * 10^n
+        nice_spacings = []
+        for n in range(-10, 10):
+            for base in [1, 2, 3, 4, 5, 6]:
+                nice_spacings.append(base * 10**n)
+
+        # Find the minimum spacing that can cover the data range with num_ticks-1 intervals
+        target_spacing = right_range / (num_ticks - 1)
+        right_tick_spacing = min([s for s in nice_spacings if s >= target_spacing])
+
+        # Calculate new right axis limits based on nice spacing
+        right_min = np.floor(right_data_min / right_tick_spacing) * right_tick_spacing
+        right_max = right_min + (num_ticks - 1) * right_tick_spacing
+
+        # Create right axis ticks
+        right_ticks = np.linspace(right_min, right_max, num_ticks)
+
+        self.ax_right.set_ylim(right_min, right_max)
+        self.ax_right.set_yticks(right_ticks)
+
+    def plot(self):
+
+        for i, y in enumerate(self.ys_left):
+            self._add_line_and_label(
+                self.ax.plot(
+                    self.x,
+                    y,
+                    label=self.labels_left[i],
+                    color=next(self.next_color),
+                    marker=next(self.next_marker),
+                    markersize=self.marker_size,
+                    linestyle="None",
+                ),
+                self.labels_left[i],
+            )
+
+        for i, y in enumerate(self.ys_right):
+            self._add_line_and_label(
+                self.ax_right.plot(
+                    self.x,
+                    y,
+                    label=self.labels_right[i],
+                    color=next(self.next_color),
+                    marker=next(self.next_marker),
+                    markersize=self.marker_size,
+                    linestyle="None",
+                ),
+                self.labels_right[i],
+            )
+
+        self.format()
+
+    def format(self):
+        if self.x_title is not None:
+            self.ax.set_xlabel(self.x_title)
+        if self.y_title is not None:
+            self.ax.set_ylabel(self.y_title)
+        if self.y_title_right is not None:
+            self.ax_right.set_ylabel(self.y_title_right)
+
+        self.ax.grid(True)
+
+        if not isinstance(self.x[0], str):
+            dx = self.x[1] - self.x[0] if len(self.x) > 1 else 0
+            self.ax.set_xlim(left=self.x[0] - dx / 2, right=self.x[-1] + dx / 2)
+
+        if self.x_is_datetime:
+            self.formate_x_datetime(self.x[0] - dx / 2, self.x[-1] + dx / 2)
+
+        self.format_numeric_ticks()
+
+
+class DoubleYSeparated(DoubleY):
+    def __init__(
+        self,
+        x,
+        ys_left: list,
+        ys_right: list,
+        labels=None,
+        y_title_left="Heat Flux / W",
+        y_title_right="Temperature / K",
+        marker_size=6,
+        same_marker=False,
+    ):
+        super().__init__(
+            x, ys_left, ys_right, y_title_left=y_title_left, y_title_right=y_title_right, marker_size=marker_size
+        )
+
+        if labels is None:
+            labels = [None] * len(ys_left)
+        if not isinstance(labels, list):
+            labels = [labels]
+        self.labels = labels
+        self.same_marker = same_marker
+
+    def plot(self):
+
+        for i, (y_left, y_right) in enumerate(zip(self.ys_left, self.ys_right)):
+            marker = next(self.next_marker)
+
+            self._add_line(
+                self.ax.plot(
+                    self.x,
+                    y_left,
+                    color="black",
+                    marker=marker,
+                    markersize=self.marker_size,
+                    linestyle="None",
+                )
+            )
+
+            if not self.same_marker:
+                marker = next(self.next_marker)
+
+            self._add_line(
+                self.ax_right.plot(
+                    self.x,
+                    y_right,
+                    color=self.colors[0],
+                    marker=marker,
+                    markersize=self.marker_size,
+                    linestyle="None",
+                )
+            )
+
+            if self.labels[i] is not None and not self.same_marker:
+                self.ax.plot(
+                    [],
+                    [],
+                    color="black",
+                    marker=marker,
+                    linestyle="None",
+                    markersize=self.marker_size,
+                    label=self.labels[i],
+                )
+
+        self.format()
+
+    def format(self):
+        super().format()
+        self.ax.yaxis.label.set_color("black")
+        self.ax.tick_params(axis="y", colors="black")
+        self.ax_right.yaxis.label.set_color(self.colors[0])
+        self.ax_right.tick_params(axis="y", colors=self.colors[0])

leanplot/core/functions.py

@@ -0,0 +1,145 @@
+#  ------------------------------------------------------------------------------
+#  Copyright (c) 2026 Joel Kimmich
+#  ------------------------------------------------------------------------------
+#  License
+#      This file is part of LeanPlot, distributed under MIT license.
+#  ------------------------------------------------------------------------------
+#
+from datetime import datetime, timedelta
+
+import matplotlib.dates as mdates
+import numpy as np
+
+
+def is_numeric(value):
+    """
+    Checks if value is a numeric value.
+
+    Parameters
+    ----------
+    value : Any
+        Value to check.
+
+    Returns
+    -------
+    bool
+        True if value is numeric, False otherwise
+    """
+    list_of_numerics = [float, int, np.number]  # add numeric data types here if necessary
+    for numeric in list_of_numerics:
+        if isinstance(value, numeric):
+            return True
+    return False
+
+
+def cm_to_inch(value):
+    return value / 2.54
+
+
+def custom_numeric_ticks_formatter(x, pos):
+    """
+    Format numbers/ticks to match ISO 80000.
+
+    Parameters
+    ----------
+    x : float | int
+        The number to format.
+    pos
+
+    Returns
+    -------
+    str :
+        The formatted number with a short protected space as thousands separator and a "," as decimal.
+    """
+    if abs(x) >= 1000:
+        s = f"{x:,.0f}".replace(",", "\u202f").replace(".", ",")
+        return s
+    else:
+        return f"{x:g}".replace(".", ",")
+
+
+def format_date_x_axis(start_date: datetime, end_date: datetime, ax, return_version: bool = True) -> str | None:
+    """
+    Formats the ticks of an axis as date.
+
+    Depending on the date range it parses the time/date to days, weeks, months and years with matching minor ticks.
+
+    Parameters
+    ----------
+    start_date : datetime
+        The start date of the axis.
+    end_date : datetime
+        The end date of the axis.
+    ax : matplotlib.axis.Axis
+        The axis to format.
+    return_version : bool
+        Whether to return the version of the axis or not.
+
+    Returns
+    -------
+    str | None :
+        The formatted Axis if return_version is True, otherwise None.
+    """
+    time_delta = end_date - start_date
+    if time_delta <= timedelta(days=3):
+        version = "day"
+        ax.xaxis.set_major_locator(mdates.HourLocator(byhour=(0, 6, 12, 18)))
+        ax.xaxis.set_minor_locator(mdates.HourLocator())
+        ax.xaxis.set_major_formatter(mdates.DateFormatter("%d.%m. %-H Uhr"))
+    elif time_delta <= timedelta(days=10):
+        version = "week"
+        ax.xaxis.set_major_locator(mdates.DayLocator())
+        ax.xaxis.set_minor_locator(mdates.HourLocator(byhour=(0, 6, 12, 18)))
+        ax.xaxis.set_major_formatter(mdates.DateFormatter("%d.%m."))
+    elif time_delta <= timedelta(days=80):
+        version = "month"
+        ax.xaxis.set_major_locator(mdates.DayLocator(bymonthday=(1, 7, 15, 23)))
+        ax.xaxis.set_minor_locator(mdates.DayLocator())
+        ax.xaxis.set_major_formatter(mdates.DateFormatter("%d.%m."))
+    else:
+        version = "year"
+        ax.xaxis.set_major_locator(mdates.MonthLocator())
+        ax.xaxis.set_minor_locator(mdates.DayLocator(bymonthday=(1, 7, 14, 21, 28)))
+        ax.xaxis.set_major_formatter(mdates.DateFormatter("%-m."))
+    ax.grid(True)
+    ax.tick_params(axis="x", which="minor", bottom=True)
+    ax.set_xlim(left=start_date)
+    ax.set_xlim(right=end_date)
+    if return_version:
+        return version
+
+
+def round_valid(number: float | int, valid_digits: int, return_str: bool = False):
+    if np.isnan(number):
+        if return_str:
+            return "NaN"
+        return np.nan
+    if number == np.inf:
+        if return_str:
+            return "Infinity"
+        return np.inf
+    if number == -np.inf:
+        if return_str:
+            return "-Infinity"
+        return -np.inf
+    if int(number) == 0:
+        # number < 1
+        if number == 0:
+            if return_str:
+                return "0"
+            return 0
+        counter = 0
+        while int(number) == 0:
+            number = number * 10
+            counter += 1
+        if return_str:
+            format_str = f"{{:{counter + 1 + valid_digits}.{valid_digits + counter - 1}f}}"
+            return format_str.format(np.round(number, valid_digits) / 10**counter)
+        return np.round(np.round(number, valid_digits) / 10**counter, counter + valid_digits - 1)
+    else:
+        ten_digits = int(np.log10(abs(number))) + 1
+        if ten_digits >= valid_digits:
+            number = int(number)
+        if return_str:
+            return f"{np.round(number, valid_digits - ten_digits)}"
+        return np.round(number, valid_digits - ten_digits)

leanplot/core/line.py

@@ -0,0 +1,135 @@
+#  ------------------------------------------------------------------------------
+#  Copyright (c) 2026 Joel Kimmich
+#  ------------------------------------------------------------------------------
+#  License
+#      This file is part of LeanPlot, distributed under MIT license.
+#  ------------------------------------------------------------------------------
+#
+import numpy as np
+
+from leanplot.core.mixin import PlotMixin
+
+
+class LinePlot(PlotMixin):
+    def __init__(
+        self,
+        x,
+        ys: list | np.ndarray,
+        labels=None,
+        y_scale=1,
+        y_title="Values",
+        linewidth=1.8,
+        x_title=None,
+        width_mm=160,
+        height_mm=90,
+    ):
+        if not isinstance(ys, list):
+            if not (isinstance(ys, np.ndarray) and len(ys.shape) > 1 and ys.shape[0] > 1 and ys.shape[1] > 1):
+                ys = [np.array(ys)]
+        else:
+            if len(ys) == len(x):
+                ys = [np.array(ys)]
+        ys = [np.array(y) for y in ys]
+        super().__init__(x=np.array(x), ys=ys, y_title=y_title, x_title=x_title, width_mm=width_mm, height_mm=height_mm)
+
+        if labels is None:
+            labels = [None] * len(ys)
+        if not isinstance(labels, list):
+            labels = [labels]
+        self.labels = labels
+
+        self.y_scale = y_scale
+        self.line_width = linewidth
+
+    def plot(self, x=None, ys=None, labels=None):
+        if x is None:
+            x = self.x
+        if ys is None:
+            ys = self.ys
+        if labels is None:
+            labels = self.labels
+        if not isinstance(labels, list):
+            labels = [labels]
+        for i, y in enumerate(ys):
+            self._add_line(
+                self.ax.plot(
+                    x,
+                    np.array(y) * self.y_scale,
+                    label=labels[i],
+                    color=next(self.next_color),
+                    linewidth=self.line_width,
+                    linestyle=next(self.next_line_style),
+                )
+            )
+        self.format()
+
+    def add_points(self, x, ys, labels=None):
+        """
+        Add points to the plot (e.g. measurement data to interpolated lines)
+
+        The ys values are not scaled with self.y_scale!
+
+        Parameters
+        ----------
+        x : float | int | np.ndarray | list
+            x values
+        ys : float | int | np.ndarray | list
+            y values. If two-dimensional several point plots are added with different colors.
+        labels : list | str, optional
+            The labels of the point groups, accordingly
+        """
+        if not isinstance(x, np.ndarray):
+            x = np.array(x)
+        if not isinstance(ys, np.ndarray):
+            ys = np.array(ys)
+        ys = np.atleast_2d(ys)
+        if labels is None:
+            labels = [None] * len(ys)
+        if not isinstance(labels, list):
+            labels = [labels]
+        assert len(labels) == len(ys)
+
+        for i, y in enumerate(ys):
+            self._add_line_and_label(
+                self.ax.plot(
+                    x,
+                    np.array(y),
+                    label=labels[i],
+                    color=next(self.next_color),
+                    linestyle="none",
+                    marker=next(self.next_marker),
+                ),
+                labels[i],
+            )
+        self.format()
+
+    def plot_marker(self):
+        for i, y in enumerate(self.ys):
+            self.ax.plot(
+                self.x,
+                np.array(y) * self.y_scale,
+                label=self.labels[i],
+                color=next(self.next_color),
+                marker=next(self.next_marker),
+            )
+        self.format()
+
+    def plot_stack(self):
+        self.ax.stackplot(
+            self.x,
+            *[y * self.y_scale for y in self.ys],
+            labels=self.labels,
+            colors=self.colors,
+        )
+        self.format()
+
+    def format(self):
+        super().format()
+        self.format_numeric_ticks()
+
+
+class TimePlot(LinePlot):
+    def format(self):
+        super().format()
+        self.formate_x_datetime()
+        self.format_numeric_ticks()