leanplot 1.0.0__tar.gz

leanplot-1.0.0/LICENSE.txt

@@ -0,0 +1,16 @@
+MIT License
+
+Copyright (c) 2026 Joel Kimmich
+
+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.

leanplot-1.0.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: leanplot
+Version: 1.0.0
+Summary: Provides some classes for fast matplotlib plotting based on ISO 80000.
+Author-email: Joel Kimmich <software@igte.uni-stuttgart.de>
+License-Expression: MIT
+Project-URL: Homepage, https://codeberg.org/IGTE/leanplot
+Project-URL: Documentation, https://codeberg.org/IGTE/leanplot
+Project-URL: Repository, https://codeberg.org/IGTE/leanplot
+Project-URL: Issues, https://codeberg.org/IGTE/leanplot/issues
+Project-URL: Changelog, https://codeberg.org/IGTE/leanplot/CHANGELOG.rst
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+Classifier: Topic :: Documentation
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Utilities
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: Unix
+Classifier: Operating System :: MacOS
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: matplotlib>=3.10.0
+Requires-Dist: numpy>=2.0.0
+Requires-Dist: cmcrameri
+Provides-Extra: dev
+Requires-Dist: ruff>=0.15.8; extra == "dev"
+Requires-Dist: build>=1.4.2; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+[//]: # (<h1 align="center">)
+
+[//]: # (<img src="somePath" alt="LeanPlot Logo" height="65">)
+
+[//]: # (</h1><br>)
+
+# LeanPlot
+
+[![PyPI - Version](https://shields.io/pypi/v/leanplot)](https://pypi.org/project/leanplot/)
+[![PyPI - License](https://shields.io/pypi/l/leanplot)](https://pypi.org/project/leanplot/)
+[![Typing](https://shields.io/pypi/types/leanplot)](https://pypi.org/project/leanplot/)
+
+LeanPlot is a baseline plotting tool for formatted matplotlib plots based on ISO 80000 using "," as decimal and a 
+short protected space as thousands separator. Also, it makes it easy to plot over time with correct formatting.
+
+The result can always be manipulated like any other matplotlib axes and figures.
+
+## Installation
+
+```bash
+pip install leanplot
+```
+
+## License
+
+See LICENSE.txt for the license.

leanplot-1.0.0/README.md

@@ -0,0 +1,26 @@
+[//]: # (<h1 align="center">)
+
+[//]: # (<img src="somePath" alt="LeanPlot Logo" height="65">)
+
+[//]: # (</h1><br>)
+
+# LeanPlot
+
+[![PyPI - Version](https://shields.io/pypi/v/leanplot)](https://pypi.org/project/leanplot/)
+[![PyPI - License](https://shields.io/pypi/l/leanplot)](https://pypi.org/project/leanplot/)
+[![Typing](https://shields.io/pypi/types/leanplot)](https://pypi.org/project/leanplot/)
+
+LeanPlot is a baseline plotting tool for formatted matplotlib plots based on ISO 80000 using "," as decimal and a 
+short protected space as thousands separator. Also, it makes it easy to plot over time with correct formatting.
+
+The result can always be manipulated like any other matplotlib axes and figures.
+
+## Installation
+
+```bash
+pip install leanplot
+```
+
+## License
+
+See LICENSE.txt for the license.

leanplot-1.0.0/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-1.0.0/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-1.0.0/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-1.0.0/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-1.0.0/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-1.0.0/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-1.0.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)