dataplot 0.1.6__py3-none-any.whl

dataplot/artist/qqplot.py

@@ -0,0 +1,92 @@
+"""
+Contains a plotter class: QQPlot.
+
+NOTE: this module is private. All functions and objects are available in the main
+`dataplot` namespace - use that instead.
+
+"""
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+from scipy import stats
+from validating import dataclass
+
+from .._typing import DistName
+from ..setting import PlotSettable
+from ..utils.math import get_quantile, linear_regression_1d
+from .base import Plotter
+
+if TYPE_CHECKING:
+    from ..container import AxesWrapper
+    from ..dataset import PlotDataSet
+
+__all__ = ["QQPlot"]
+
+
+@dataclass(validate_methods=True)
+class QQPlot(Plotter):
+    """
+    A plotter class that creates a Q-Q plot.
+
+    """
+
+    dist_or_sample: "DistName | np.ndarray | PlotDataSet"
+    dots: int
+    edge_precision: float
+    fmt: str
+
+    def paint(self, ax: "AxesWrapper", **_) -> None:
+        ax.set_default(
+            title="Quantile-Quantile Plot",
+            xlabel="quantiles",
+            ylabel="quantiles",
+        )
+        ax.load(self.settings)
+        self.__plot(ax)
+
+    def __plot(self, ax: "AxesWrapper") -> None:
+        xlabel, p, q1 = self._generate_dist()
+        q2 = get_quantile(self.data, p)
+        ax.ax.plot(q1, q2, self.fmt, zorder=2.1, label=f"{self.label} & {xlabel}")
+        self._plot_fitted_line(ax, q1, q2)
+
+    def _generate_dist(self) -> tuple[str, np.ndarray, np.ndarray]:
+        if not 0 <= self.edge_precision < 0.5:
+            raise ValueError(
+                "'edge_precision' should be on the interval [0, 0.5), got "
+                f"{self.edge_precision} instead"
+            )
+        p = np.linspace(self.edge_precision, 1 - self.edge_precision, self.dots)
+        if isinstance(x := self.dist_or_sample, str):
+            xlabel = x + "-distribution"
+            q = self._get_ppf(x, p)
+        elif isinstance(x, PlotSettable):
+            xlabel = x.formatted_label()
+            q = get_quantile(x.data, p)
+        elif isinstance(x, (list, np.ndarray)):
+            xlabel = "sample"
+            q = get_quantile(x, p)
+        else:
+            raise TypeError(
+                f"'dist_or_sample' can not be instance of {x.__class__.__name__!r}"
+            )
+        return xlabel, p, q
+
+    @staticmethod
+    def _plot_fitted_line(ax: "AxesWrapper", x: np.ndarray, y: np.ndarray) -> None:
+        a, b = linear_regression_1d(y, x)
+        l, r = x.min(), x.max()
+        ax.ax.plot(
+            [l, r], [a + l * b, a + r * b], "--", label=f"y = {a:.3f} + {b:.3f}x"
+        )
+
+    @staticmethod
+    def _get_ppf(dist: str, p: np.ndarray) -> np.ndarray:
+        match dist:
+            case "normal":
+                return stats.norm.ppf(p)
+            case "expon":
+                return stats.expon.ppf(p)
+            case _:
+                raise ValueError(f"no such distribution: {dist!r}")

dataplot/artist/scatterchart.py

@@ -0,0 +1,59 @@
+"""
+Contains a plotter class: ScatterChart.
+
+NOTE: this module is private. All functions and objects are available in the main
+`dataplot` namespace - use that instead.
+
+"""
+
+from typing import TYPE_CHECKING, Optional
+
+import numpy as np
+from validating import dataclass
+
+from ..setting import PlotSettable
+from .base import Plotter
+
+if TYPE_CHECKING:
+    from ..container import AxesWrapper
+    from ..dataset import PlotDataSet
+
+__all__ = ["ScatterChart"]
+
+
+@dataclass(validate_methods=True)
+class ScatterChart(Plotter):
+    """
+    A plotter class that creates a scatter chart.
+
+    """
+
+    xticks: Optional["np.ndarray | PlotDataSet"]
+    fmt: str
+    sorted: bool
+
+    def paint(self, ax: "AxesWrapper", **_) -> None:
+        ax.set_default(title="Scatter Chart")
+        ax.load(self.settings)
+        self.__plot(ax)
+
+    def __plot(self, ax: "AxesWrapper") -> None:
+        if isinstance(self.xticks, PlotSettable):
+            xticks = self.xticks.data
+        else:
+            xticks = self.xticks
+        if xticks is None:
+            xticks = range(len(self.data))
+        elif (len_t := len(xticks)) != (len_d := len(self.data)):
+            raise ValueError(
+                "x-ticks and data must have the same length, but have "
+                f"lengths {len_t} and {len_d}"
+            )
+
+        if self.sorted:
+            paired = sorted(zip(xticks, self.data, strict=True), key=lambda pair: pair[0])
+            xticks, data = zip(*paired, strict=True)
+        else:
+            data = self.data
+
+        ax.ax.plot(xticks, data, self.fmt, linestyle="None", label=self.label)

dataplot/container.py

@@ -0,0 +1,203 @@
+"""
+Contains container classes: FigWrapper and AxesWrapper.
+
+NOTE: this module is private. All functions and objects are available in the main
+`dataplot` namespace - use that instead.
+
+"""
+
+import logging
+from typing import TYPE_CHECKING, Any, Self, Unpack
+
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.figure import Figure
+from matplotlib.pyplot import Axes
+from validating import attr, dataclass
+
+from ._typing import AxesSettingDict, FigureSettingDict, SettingKey
+from .setting import PlotSettable
+
+if TYPE_CHECKING:
+    from .artist import Artist
+
+__all__ = ["FigWrapper", "AxesWrapper"]
+
+
+@dataclass(validate_methods=True)
+class AxesWrapper(PlotSettable):
+    """
+    Serves as a wrapper for creating and customizing axes in matplotlib.
+
+    Note that this should NEVER be instantiated directly, but always
+    through the invoking of `FigWrapper.axes`.
+
+    """
+
+    ax: Axes
+
+    def set_axes(self, **kwargs: Unpack[AxesSettingDict]) -> None:
+        """
+        Set the settings of axes.
+
+        Parameters
+        ----------
+        title : str, optional
+            Title of axes. Please note that there's another parameter with
+            the same name in `.set_figure()`.
+        xlabel : str, optional
+            Label for the x-axis.
+        ylabel : str, optional
+            Label for the y-axis.
+        alpha : float, optional
+            Controls the transparency of the plotted elements. It takes a float
+            value between 0 and 1, where 0 means completely transparent and 1
+            means completely opaque.
+        grid : bool, optional
+            Determines whether to show the grids or not.
+        grid_alpha : float, optional
+            Controls the transparency of the grid.
+        fontdict : FontDict, optional
+            A dictionary controlling the appearance of the title text.
+        legend_loc : LegendLoc, optional
+            Location of the legend.
+
+        """
+        self._set(inplace=True, **kwargs)
+
+    def exit(self) -> None:
+        """
+        Set various properties for the axes. This should be called only
+        by `FigWrapper.__exit__()`.
+
+        """
+        self.ax.set_xlabel(self.settings.xlabel)
+        self.ax.set_ylabel(self.settings.ylabel)
+        if len(self.ax.get_legend_handles_labels()[0]):
+            self.ax.legend(loc=self.settings.legend_loc)
+        if self.get_setting("grid", True):
+            alpha = self.get_setting("alpha", 1.0)
+            self.ax.grid(alpha=self.get_setting("grid_alpha", alpha / 2))
+        else:
+            self.ax.grid(False)
+        self.ax.set_title(self.settings.title, **self.get_setting("fontdict", {}))
+
+
+@dataclass(validate_methods=True)
+class FigWrapper(PlotSettable):
+    """
+    A wrapper of figure.
+
+    Note that this should NEVER be instantiated directly, but always through the
+    module-level function `dataplot.figure()`.
+
+    """
+
+    nrows: int = 1
+    ncols: int = 1
+    active: bool = attr(repr=False, default=True)
+    entered: bool = attr(init=False, repr=False, default=False)
+    fig: Figure = attr(init=False, repr=False)
+    axes: list[AxesWrapper] = attr(init=False, repr=False)
+    artists: "list[Artist]" = attr(default_factory=list, init=False, repr=False)
+
+    def __enter__(self) -> Self:
+        """
+        Create subplots and set the style.
+
+        Returns
+        -------
+        Self
+            An instance of self.
+
+        """
+        if not self.active:
+            return self
+        if self.entered:
+            raise DoubleEnteredError(
+                f"can't enter an instance of {self.__class__.__name__!r} for twice; "
+                "please do all the operations in one single context manager"
+            )
+
+        self.set_default(
+            style="seaborn-v0_8-darkgrid",
+            figsize=(10 * self.ncols, 5 * self.nrows),
+            subplots_adjust={"hspace": 0.5},
+            fontdict={"fontsize": "x-large"},
+        )
+        plt.style.use(self.settings.style)
+        self.fig, axes = plt.subplots(self.nrows, self.ncols)
+        self.axes: list[AxesWrapper] = [AxesWrapper(x) for x in np.reshape(axes, -1)]
+        self.entered = True
+        return self
+
+    def __exit__(self, *args) -> None:
+        """
+        Set various properties for the figure and paint it.
+
+        """
+        if not self.active:
+            return
+
+        if len(self.axes) > 1:
+            self.fig.suptitle(self.settings.title, **self.settings.fontdict)
+        else:
+            self.axes[0].ax.set_title(self.settings.title, **self.settings.fontdict)
+
+        self.fig.set_size_inches(*self.settings.figsize)
+        self.fig.subplots_adjust(**self.settings.subplots_adjust)
+        self.fig.set_dpi(self.get_setting("dpi", 100))
+
+        for ax in self.axes:
+            ax.exit()
+            if not ax.ax.has_data():
+                self.fig.delaxes(ax.ax)
+
+        plt.show()
+        plt.close(self.fig)
+        plt.style.use("default")
+
+        self.entered = False
+
+    def __repr__(self) -> str:
+        with self as fig:
+            for artist, ax in zip(self.artists, fig.axes[: len(self.artists)]):
+                artist.paint(ax)
+        return f"<{self.__class__.__name__}(nrows={self.nrows}, ncols={self.ncols})>"
+
+    def set_figure(self, **kwargs: Unpack[FigureSettingDict]) -> None:
+        """
+        Set the settings of figure.
+
+        Parameters
+        ----------
+        title : str, optional
+            Title of figure. Please note that there's another parameter with
+            the same name in `.set_axis()`.
+        dpi : float, optional
+            Sets the resolution of figure in dots-per-inch.
+        style : StyleName, optional
+            A style specification.
+        figsize : tuple[int, int], optional
+            Figure size, this takes a tuple of two integers that specifies the
+            width and height of the figure in inches.
+        fontdict : FontDict, optional
+            A dictionary controlling the appearance of the title text.
+        subplots_adjust : SubplotDict, optional
+            Adjusts the subplot layout parameters including: left, right, bottom,
+            top, wspace, and hspace. See `SubplotDict` for more details.
+
+        """
+        self._set(inplace=True, **kwargs)
+
+    def setting_check(self, key: SettingKey, value: Any) -> None:
+        if self.entered and key == "style":
+            logging.warning(
+                "setting the '%s' of a figure has no effect unless it's done "
+                "before invoking context manager",
+                key,
+            )
+
+
+class DoubleEnteredError(Exception):
+    """Raised when entering a Figwrapper for twice."""

dataplot/core.py

@@ -0,0 +1,202 @@
+"""
+Contains the core of dataplot: figure(), data(), show(), etc.
+
+NOTE: this module is private. All functions and objects are available in the main
+`dataplot` namespace - use that instead.
+
+"""
+
+import dis
+import re
+import sys
+from math import ceil, sqrt
+from typing import TYPE_CHECKING, Any, Optional, Unpack
+
+import numpy as np
+
+from ._typing import FigureSettingDict
+from .container import FigWrapper
+from .dataset import PlotDataSet, PlotDataSets
+
+if TYPE_CHECKING:
+    from .artist import Artist
+
+
+__all__ = ["data", "figure"]
+
+
+def _infer_var_names(*values: Any) -> list[Optional[str]]:
+    try:
+        search_frame = sys._getframe(1)
+    except ValueError:
+        return [None] * len(values)
+
+    labels: list[Optional[str]] = []
+    try:
+        for value in values:
+            name = None
+            current = search_frame
+            while current is not None and name is None:
+                local_items = list(current.f_locals.items())
+                global_items = list(current.f_globals.items())
+                name = next((k for k, v in local_items if v is value), None)
+                if name is None:
+                    name = next((k for k, v in global_items if v is value), None)
+                current = current.f_back
+            labels.append(name)
+    finally:
+        del search_frame
+    return labels
+
+
+def _infer_assigned_name() -> Optional[str]:
+    """Try inferring assignment target name from call-site."""
+    try:
+        frame = sys._getframe(2)
+    except ValueError:
+        return None
+
+    # Bytecode inspection works in REPL/notebook contexts where source code file
+    # is unavailable.
+    try:
+        instructions = list(dis.get_instructions(frame.f_code))
+        store_index = next(
+            (
+                i
+                for i, ins in enumerate(instructions)
+                if ins.offset > frame.f_lasti
+                and ins.opname in {"STORE_NAME", "STORE_FAST", "STORE_GLOBAL"}
+            ),
+            None,
+        )
+        if store_index is not None:
+            # `a = b = data(...)` compiles to STORE_* b then STORE_* a;
+            # returning the last one better matches user expectation.
+            last_store = store_index
+            while last_store + 1 < len(instructions) and instructions[
+                last_store + 1
+            ].opname in {"STORE_NAME", "STORE_FAST", "STORE_GLOBAL"}:
+                last_store += 1
+            return str(instructions[last_store].argval)
+    except Exception:
+        pass
+
+    try:
+        context = frame.f_code.co_filename
+        lineno = frame.f_lineno
+        with open(context, "r", encoding="utf-8") as f:
+            lines = f.readlines()
+        line = lines[lineno - 1].strip()
+    except (OSError, IndexError):
+        return None
+    finally:
+        del frame
+
+    if "=" not in line:
+        return None
+    lhs = line.split("=", 1)[0].strip()
+    if not lhs:
+        return None
+    m = re.match(r"([A-Za-z_][A-Za-z0-9_]*)", lhs)
+    return m.group(1) if m else None
+
+
+def data(*x: Any, label: Optional[str | list[str]] = None) -> PlotDataSet:
+    """
+    Initializes a dataset interface which provides methods for mathematical
+    operations and plotting.
+
+    Parameters
+    ----------
+    *x : np.ndarray | Any
+        Input values, this takes one or multiple arrays, with each array
+        representing a dataset.
+    label : str | list[str], optional
+        Label(s) of the data, this takes either a single string or a list of strings.
+        If a list, should be the same length as the number of input arrays, with
+        each element corresponding to a specific array in `x`. If set to None,
+        use "x{i}" (i = 1, 2. 3, ...) as the label(s). By default None.
+
+    Returns
+    -------
+    PlotDataSet
+        Provides methods for mathematical operations and plotting.
+
+    """
+    if not x:
+        raise ValueError("at least one dataset should be provided")
+
+    if len(x) > 1:
+        if label is None:
+            label = [
+                lb if lb is not None else f"x{i}"
+                for i, lb in enumerate(_infer_var_names(*x), start=1)
+            ]
+        elif isinstance(label, str):
+            raise ValueError(
+                "for multiple datasets, please provide labels as a list of strings"
+            )
+        elif len(label) != len(x):
+            raise ValueError(
+                f"label should have the same length as x ({len(x)}), got {len(label)}"
+            )
+        datas = [PlotDataSet(np.array(d), lb) for d, lb in zip(x, label)]
+        return PlotDataSets(*datas)
+
+    if isinstance(label, list):
+        raise ValueError(
+            "it seems not necessary to provide a list of labels, since "
+            "the data has only one dimension"
+        )
+    if label is None:
+        label = _infer_assigned_name() or _infer_var_names(x[0])[0] or "x1"
+    return PlotDataSet(np.array(x[0]), label=label)
+
+
+def figure(
+    artist: "Artist | list[Artist]",
+    nrows: int | None = None,
+    ncols: int | None = None,
+    **kwargs: Unpack[FigureSettingDict],
+) -> FigWrapper:
+    """
+    Provides a context manager interface (`__enter__` and `__exit__` methods) for
+    creating a figure with subplots and setting various properties for the figure.
+
+    Parameters
+    ----------
+    artist : Artist | list[Artist]
+        Artist or list of artists.
+    nrows : int, optional
+        Determines how many subplots can be arranged vertically in the figure,
+        If None, will be automatically set according to ``len(artist)``. By default
+        None.
+    ncols : int, optional
+        Determines how many subplots can be arranged horizontally in the figure.
+        If None, will be automatically set according to ``len(artist)``. By default
+        None.
+    **kwargs : **FigureSettingDict
+        Specifies the figure settings, see `FigWrapper.set_figure()` for more details.
+
+    Returns
+    -------
+    FigWrapper
+        A wrapper of figure.
+
+    """
+    if not isinstance(artist, list):
+        artist = [artist]
+    len_a = max(len(artist), 1)
+    if nrows is None and ncols is None:
+        ncols = int(sqrt(len_a))
+        nrows = ceil(len_a / ncols)
+    elif ncols is None:
+        nrows = min(nrows, len_a)
+        ncols = ceil(len_a / ncols)
+    else:
+        ncols = min(ncols, len_a)
+        nrows = ceil(len_a / ncols)
+    figw = FigWrapper(nrows=nrows, ncols=ncols)
+    figw.set_figure(**kwargs)
+    figw.artists = artist
+    return figw