dataplot 0.1.6__py3-none-any.whl

dataplot/__init__.py

@@ -0,0 +1,34 @@
+"""
+# dataplot
+Provides plotting tools useful in datascience.
+
+## See Also
+### Github repository
+* https://github.com/Chitaoji/dataplot/
+
+### PyPI project
+* https://pypi.org/project/dataplot/
+
+## License
+This project falls under the BSD 3-Clause License.
+
+"""
+
+import lazyr
+
+with lazyr.setverbose(0):
+    lazyr.register("pandas")
+    lazyr.register("scipy.stats")
+    lazyr.register("seaborn")
+
+from . import container, core, dataset, setting
+from .container import *
+from .core import *
+from .dataset import *
+from .setting import *
+
+__all__: list[str] = []
+__all__.extend(core.__all__)
+__all__.extend(setting.__all__)
+__all__.extend(container.__all__)
+__all__.extend(dataset.__all__)

dataplot/_typing.py

@@ -0,0 +1,211 @@
+"""
+Contains typing classes.
+
+NOTE: this module is not intended to be imported at runtime.
+
+"""
+
+from typing import TYPE_CHECKING, Literal, NotRequired, Optional, TypedDict, TypeVar
+
+if TYPE_CHECKING:
+    from .setting import PlotSettable
+
+
+PlotSettableVar = TypeVar("PlotSettableVar", bound="PlotSettable")
+DefaultVar = TypeVar("DefaultVar")
+StyleName = Literal[
+    "Solarize_Light2",
+    "_classic_test_patch",
+    "_mpl-gallery",
+    "_mpl-gallery-nogrid",
+    "bmh",
+    "classic",
+    "dark_background",
+    "fast",
+    "fivethirtyeight",
+    "ggplot",
+    "grayscale",
+    "seaborn-v0_8",
+    "seaborn-v0_8-bright",
+    "seaborn-v0_8-colorblind",
+    "seaborn-v0_8-dark",
+    "seaborn-v0_8-dark-palette",
+    "seaborn-v0_8-darkgrid",
+    "seaborn-v0_8-deep",
+    "seaborn-v0_8-muted",
+    "seaborn-v0_8-notebook",
+    "seaborn-v0_8-paper",
+    "seaborn-v0_8-pastel",
+    "seaborn-v0_8-poster",
+    "seaborn-v0_8-talk",
+    "seaborn-v0_8-ticks",
+    "seaborn-v0_8-white",
+    "seaborn-v0_8-whitegrid",
+    "tableau-colorblind10",
+]
+LegendLoc = Literal[
+    "best",
+    "upper right",
+    "upper left",
+    "lower left",
+    "lower right",
+    "right",
+    "center left",
+    "center right",
+    "lower center",
+    "upper center",
+    "center",
+]
+FontSize = Literal[
+    "xx-small", "x-small", "small", "medium", "large", "x-large", "xx-large"
+]
+FontWeight = Literal[
+    "ultralight",
+    "light",
+    "normal",
+    "regular",
+    "book",
+    "medium",
+    "roman",
+    "semibold",
+    "demibold",
+    "demi",
+    "bold",
+    "heavy",
+    "extra bold",
+    "black",
+]
+FontStyleName = Literal["normal", "italic", "oblique"]
+ColorId = (
+    Literal["b", "g", "r", "c", "m", "y", "k", "w"]
+    | Literal["C0", "C1", "C2", "C3", "C4", "C5", "C6", "C7", "C8", "C9"]
+)
+VerticalAlignment = Literal["baseline", "bottom", "center", "center_baseline", "top"]
+HorizontalAlignment = Literal["left", "center", "right"]
+DistName = Literal["normal", "expon"]
+SettingKey = Literal[
+    "title",
+    "xlabel",
+    "ylabel",
+    "alpha",
+    "dpi",
+    "grid",
+    "grid_alpha",
+    "style",
+    "figsize",
+    "fontdict",
+    "legend_loc",
+    "subplots_adjust",
+]
+ResampleRule = Literal["head", "tail", "random"]
+
+
+class SettingDict(TypedDict):
+    """
+    Dict of keyword-arguments for `._set()`.
+
+    """
+
+    title: NotRequired[Optional[str]]
+    xlabel: NotRequired[Optional[str]]
+    ylabel: NotRequired[Optional[str]]
+    alpha: NotRequired[Optional[float]]
+    dpi: NotRequired[Optional[float]]
+    grid: NotRequired[Optional[bool]]
+    grid_alpha: NotRequired[Optional[float]]
+    style: NotRequired[Optional[StyleName]]
+    figsize: NotRequired[Optional[tuple[int, int]]]
+    fontdict: NotRequired[Optional["FontDict"]]
+    legend_loc: NotRequired[Optional[str]]
+    format_label: NotRequired[Optional[bool]]
+    subplots_adjust: NotRequired[Optional["SubplotDict"]]
+
+
+class FigureSettingDict(TypedDict):
+    """
+    Dict of keyword-arguments for `.set_figure()`.
+
+    """
+
+    title: NotRequired[Optional[str]]
+    dpi: NotRequired[Optional[float]]
+    style: NotRequired[Optional[StyleName]]
+    figsize: NotRequired[Optional[tuple[int, int]]]
+    fontdict: NotRequired[Optional["FontDict"]]
+    subplots_adjust: NotRequired[Optional["SubplotDict"]]
+
+
+class AxesSettingDict(TypedDict):
+    """
+    Dict of keyword-arguments for `.set_axes()`.
+
+    """
+
+    title: NotRequired[Optional[str]]
+    xlabel: NotRequired[Optional[str]]
+    ylabel: NotRequired[Optional[str]]
+    alpha: NotRequired[Optional[float]]
+    grid: NotRequired[Optional[bool]]
+    grid_alpha: NotRequired[Optional[float]]
+    fontdict: NotRequired[Optional["FontDict"]]
+    legend_loc: NotRequired[Optional[LegendLoc]]
+
+
+class FontDict(TypedDict):
+    """
+    A dictionary controlling the appearance of the title text.
+
+    Unset parameters are left unmodified; initial values are given by
+    `matplotlib.rcParams`.
+
+    Parameters
+    ----------
+    fontsize : float | FontSizeStr, optional
+        The font size.
+    fontweight : float | FontWeightStr, optional
+        The font weight. If a float, should be in range 0-1000.
+    fontstyle : FontStyleStr, optional
+        The font style.
+    color : ColorStr, optional
+        The font color.
+    verticalalignment : VerticalAlignmentStr, optional
+        The vertical alignment relative to the anchor point.
+    horizontalalignment : HorizontalAlignmentStr, optional
+        The horizontal alignment relative to the anchor point.
+
+    """
+
+    fontsize: NotRequired[float | FontSize]
+    fontweight: NotRequired[float | FontWeight]
+    fontstyle: NotRequired[FontStyleName]
+    color: NotRequired[ColorId]
+    verticalalignment: NotRequired[VerticalAlignment]
+    horizontalalignment: NotRequired[HorizontalAlignment]
+
+
+class SubplotDict(TypedDict):
+    """
+    A dictionary controlling the subplot layout parameters.
+
+    Unset parameters are left unmodified; initial values are given by
+    `matplotlib.rcParams`, whose recommended values are {"left": 0.125,
+    "bottom": 0.11, "right": 0.9, "top": 0.88, "wspace": 0.2, "hspace":
+    0.2}.
+
+    Parameters
+    ----------
+    left / right / bottom / top : float, optional
+        The position of the left / right / bottom / top edge of the
+        subplots, as a fraction of the figure width.
+    wspace / hspace : float, optional
+        The width / height of the padding between subplots, as a fraction
+        of the average Axes width / height.
+
+    """
+
+    left: NotRequired[float]
+    bottom: NotRequired[float]
+    right: NotRequired[float]
+    top: NotRequired[float]
+    wspace: NotRequired[float]
+    hspace: NotRequired[float]

dataplot/artist/__init__.py

@@ -0,0 +1,24 @@
+"""
+Contains artists.
+
+"""
+
+from . import base, corrmap, histogram, ksplot, linechart, ppplot, qqplot, scatterchart
+from .base import *
+from .corrmap import *
+from .histogram import *
+from .ksplot import *
+from .linechart import *
+from .ppplot import *
+from .qqplot import *
+from .scatterchart import *
+
+__all__: list[str] = []
+__all__.extend(base.__all__)
+__all__.extend(corrmap.__all__)
+__all__.extend(histogram.__all__)
+__all__.extend(ksplot.__all__)
+__all__.extend(linechart.__all__)
+__all__.extend(ppplot.__all__)
+__all__.extend(qqplot.__all__)
+__all__.extend(scatterchart.__all__)

dataplot/artist/base.py

@@ -0,0 +1,78 @@
+"""
+Contains the core of artist: Artist, Plotter.
+
+NOTE: this module is private. All functions and objects are available in the main
+`dataplot` namespace - use that instead.
+
+"""
+
+from collections import Counter
+from typing import TYPE_CHECKING, Any, Optional
+
+import numpy as np
+from validating import attr, dataclass
+
+from ..container import FigWrapper
+from ..setting import PlotSettable
+from ..utils.multi import MultiObject, multiple
+
+if TYPE_CHECKING:
+    from ..container import AxesWrapper
+
+__all__ = ["Artist", "Plotter"]
+
+
+@dataclass(validate_methods=True)
+class Artist(PlotSettable):
+    """
+    Paint the desired images on an axes.
+
+    Parameters
+    ----------
+    plotter : Plotter
+        Painting tool.
+
+    """
+
+    plotter: "Plotter | MultiObject"
+    ax: Optional["AxesWrapper"] = attr(default=None, repr=False)
+
+    def __repr__(self) -> str:
+        self.paint(self.ax)
+        names = (x.__class__.__name__ for x in multiple(self.plotter))
+        s = ", ".join(f"{i} {x}s" for x, i in Counter(names).items())
+        return f"<{self.__class__.__name__} with {s}>"
+
+    def paint(self, ax: Optional["AxesWrapper"] = None) -> None:
+        """
+        Paint on the axes.
+
+        Parameters
+        ----------
+        ax : AxesWrapper, optional
+            Specifies the axes-wrapper on which the plot should be painted,
+            by default None.
+
+        """
+        with self.customize(FigWrapper, 1, 1, active := ax is None) as fig:
+            self.plotter.paint(fig.axes[0] if active else ax)
+
+
+@dataclass(init=False, validate_methods=True)
+class Plotter(PlotSettable):
+    """
+    Painting tool used by Artist - user can ignore this.
+
+    """
+
+    data: Optional[np.ndarray] = attr(repr=False, default=None, init=False)
+    label: Optional[str] = attr(default=None, init=False)
+
+    def paint(
+        self,
+        ax: "AxesWrapper",
+        *,
+        __multi_prev_returned__: Any = None,
+        __multi_is_final__: bool = True,
+    ) -> Any:
+        """Paint."""

dataplot/artist/corrmap.py

@@ -0,0 +1,57 @@
+"""
+Contains a plotter class: CorrMap.
+
+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
+import pandas as pd
+import seaborn as sns
+from validating import dataclass
+
+from .base import Plotter
+
+if TYPE_CHECKING:
+    from ..container import AxesWrapper
+
+
+__all__ = ["CorrMap"]
+
+
+@dataclass(validate_methods=True)
+class CorrMap(Plotter):
+    """
+    A plotter class that creates a correlation heatmap.
+
+    """
+
+    annot: bool
+
+    def paint(
+        self,
+        ax: "AxesWrapper",
+        *,
+        __multi_prev_returned__: Optional[tuple[list[np.ndarray], list[str]]] = None,
+        __multi_is_final__: bool = True,
+    ) -> tuple[list[np.ndarray], list[str]]:
+        if __multi_prev_returned__ is None:
+            arrays, labels = [], []
+        else:
+            arrays, labels = __multi_prev_returned__
+        arrays.append(self.data)
+        labels.append(self.label)
+        if __multi_is_final__:
+            ax.set_default(title="Correlation Heatmap")
+            ax.load(self.settings)
+            self.__plot(ax, arrays, labels)
+        return arrays, labels
+
+    def __plot(
+        self, ax: "AxesWrapper", arrays: list[np.ndarray], labels: list[str]
+    ) -> None:
+        corr = pd.DataFrame(arrays, index=labels).T.corr()
+        sns.heatmap(corr, ax=ax.ax, annot=self.annot)

dataplot/artist/histogram.py

@@ -0,0 +1,89 @@
+"""
+Contains a plotter class: Histogram.
+
+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 scipy import stats
+from validating import dataclass
+
+from .base import Plotter
+
+if TYPE_CHECKING:
+    from ..container import AxesWrapper
+
+__all__ = ["Histogram"]
+
+
+@dataclass(validate_methods=True)
+class Histogram(Plotter):
+    """
+    A plotter class that creates a histogram.
+
+    """
+
+    bins: int | list[float]
+    fit: bool
+    density: bool
+    log: bool
+    same_bin: bool
+    stats: bool
+
+    def paint(
+        self,
+        ax: "AxesWrapper",
+        *,
+        __multi_prev_returned__: Optional[tuple[str, np.ndarray]] = None,
+        __multi_is_final__: bool = True,
+    ) -> list[float]:
+        ax.set_default(
+            title="Histogram",
+            alpha=0.8,
+            xlabel="value",
+            ylabel="density" if self.density else "count",
+        )
+        ax.load(self.settings)
+        if __multi_prev_returned__ is None:
+            xlabel, bins = ax.settings.xlabel, None
+        else:
+            xlabel, bins = __multi_prev_returned__
+        ds, new_bins = self.__hist(
+            ax, bins=self.bins if (bins is None or not self.same_bin) else bins
+        )
+        if self.stats:
+            xlabel += "\n" + ds
+        if __multi_is_final__:
+            ax.set_axes(xlabel=xlabel)
+        return (xlabel, new_bins)
+
+    def __hist(
+        self, ax: "AxesWrapper", bins: int | list[float] = 100
+    ) -> tuple[str, np.ndarray]:
+        _, bin_list, _ = ax.ax.hist(
+            self.data,
+            bins=bins,
+            density=self.density,
+            log=self.log,
+            alpha=ax.settings.alpha,
+            label=self.label,
+        )
+        mean, std = np.nanmean(self.data), np.nanstd(self.data)
+        skew: float = stats.skew(self.data, bias=False, nan_policy="omit")
+        kurt: float = stats.kurtosis(self.data, bias=False, nan_policy="omit")
+        if self.fit and self.density:
+            ax.ax.plot(
+                bin_list,
+                stats.norm.pdf(bin_list, mean, std),
+                alpha=ax.settings.alpha,
+                label=f"{self.label} · fit",
+            )
+        return (
+            f"{self.label}: mean={mean:.3f}, std={std:.3f}, skew={skew:.3f}, "
+            f"kurt={kurt:.3f}",
+            bin_list,
+        )

dataplot/artist/ksplot.py

@@ -0,0 +1,42 @@
+"""
+Contains a plotter class: KSPlot.
+
+NOTE: this module is private. All functions and objects are available in the main
+`dataplot` namespace - use that instead.
+
+"""
+
+from validating import dataclass
+from typing import TYPE_CHECKING
+
+from ..utils.math import get_quantile
+from .qqplot import QQPlot
+
+if TYPE_CHECKING:
+    from ..container import AxesWrapper
+
+
+__all__ = ["KSPlot"]
+
+
+@dataclass(validate_methods=True)
+class KSPlot(QQPlot):
+    """
+    A plotter class that creates a K-S plot.
+
+    """
+
+    def paint(self, ax: "AxesWrapper", **_) -> None:
+        ax.set_default(
+            title="Kolmogorov-Smirnov Plot",
+            xlabel="value",
+            ylabel="cummulative probability",
+        )
+        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, p, self.fmt, label=xlabel)
+        ax.ax.plot(q2, p, self.fmt, label=self.label)

dataplot/artist/linechart.py

@@ -0,0 +1,62 @@
+"""
+Contains a plotter class: LineChart.
+
+NOTE: this module is private. All functions and objects are available in the main
+`dataplot` namespace - use that instead.
+
+"""
+
+from validating import dataclass
+from typing import TYPE_CHECKING, Optional
+
+import numpy as np
+
+from ..setting import PlotSettable
+from .base import Plotter
+
+if TYPE_CHECKING:
+    from ..container import AxesWrapper
+    from ..dataset import PlotDataSet
+
+__all__ = ["LineChart"]
+
+
+@dataclass(validate_methods=True)
+class LineChart(Plotter):
+    """
+    A plotter class that creates a line chart.
+
+    """
+
+    xticks: Optional["np.ndarray | PlotDataSet"]
+    fmt: str
+    scatter: bool
+    sorted: bool
+
+    def paint(self, ax: "AxesWrapper", **_) -> None:
+        ax.set_default(title="Line 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, label=self.label)
+        if self.scatter:
+            ax.ax.scatter(xticks, data, zorder=2.0)

dataplot/artist/ppplot.py

@@ -0,0 +1,41 @@
+"""
+Contains a plotter class: PPPlot.
+
+NOTE: this module is private. All functions and objects are available in the main
+`dataplot` namespace - use that instead.
+
+"""
+
+from validating import dataclass
+from typing import TYPE_CHECKING
+
+from ..utils.math import get_prob
+from .qqplot import QQPlot
+
+if TYPE_CHECKING:
+    from ..container import AxesWrapper
+
+__all__ = ["PPPlot"]
+
+
+@dataclass(validate_methods=True)
+class PPPlot(QQPlot):
+    """
+    A plotter class that creates a P-P plot.
+
+    """
+
+    def paint(self, ax: "AxesWrapper", **_) -> None:
+        ax.set_default(
+            title="Probability-Probability Plot",
+            xlabel="cumulative probility",
+            ylabel="cumulative probility",
+        )
+        ax.load(self.settings)
+        self.__plot(ax)
+
+    def __plot(self, ax: "AxesWrapper") -> None:
+        xlabel, p1, q = self._generate_dist()
+        p2 = get_prob(self.data, q)
+        ax.ax.plot(p1, p2, self.fmt, zorder=2.1, label=f"{self.label} & {xlabel}")
+        self._plot_fitted_line(ax, p1, p2)