dataplot 0.1.6__py3-none-any.whl

dataplot/setting.py

@@ -0,0 +1,232 @@
+"""
+Contains dataclasses: PlotSettings, PlotSettable.
+
+NOTE: this module is private. All functions and objects are available in the main
+`dataplot` namespace - use that instead.
+
+"""
+
+from dataclasses import asdict
+from typing import Any, Optional, Self, Unpack
+
+from validating import attr, dataclass
+
+from ._typing import (
+    DefaultVar,
+    FontDict,
+    PlotSettableVar,
+    SettingDict,
+    SettingKey,
+    StyleName,
+    SubplotDict,
+)
+
+__all__ = ["PlotSettings", "PlotSettable"]
+
+
+@dataclass(validate_methods=True)
+class PlotSettings:
+    """Stores and manages settings for plotting."""
+
+    title: Optional[str] = None
+    xlabel: Optional[str] = None
+    ylabel: Optional[str] = None
+    alpha: Optional[float] = None
+    dpi: Optional[float] = None
+    grid: Optional[bool] = None
+    grid_alpha: Optional[float] = None
+    style: Optional[StyleName] = None
+    figsize: Optional[tuple[int, int]] = None
+    fontdict: Optional[FontDict] = None
+    legend_loc: Optional[str] = None
+    subplots_adjust: Optional[SubplotDict] = None
+
+    def __getitem__(self, __key: SettingKey) -> Any:
+        return getattr(self, __key)
+
+    def __setitem__(self, __key: SettingKey, __value: Any) -> None:
+        setattr(self, __key, __value)
+
+    def __repr__(self) -> str:
+        return self.__class__.__name__ + "(" + self.repr_not_none() + ")"
+
+    def repr_not_none(self) -> str:
+        """
+        Returns a string representation of attributes with not-None values.
+
+        Returns
+        -------
+        str
+            String representation.
+
+        """
+        diff = [f"{k}={repr(v)}" for k, v in asdict(self).items() if v is not None]
+        return ", ".join(diff)
+
+    def keys(self) -> list[SettingKey]:
+        """
+        Keys of settings.
+
+        Returns
+        -------
+        list[SettingKey]
+            Keys of the settings.
+
+        """
+        return getattr(self, "__match_args__")
+
+    def reset(self) -> None:
+        """
+        Reset all the settings to None.
+
+        """
+        for k in self.keys():
+            self[k] = None
+
+
+@dataclass(init=False)
+class PlotSettable:
+    """Contains an attribute of plot settings, and provides methods for
+    handling these settings.
+
+    """
+
+    settings: PlotSettings = attr(default_factory=PlotSettings, init=False)
+
+    def _set(
+        self, *, inplace: bool = False, **kwargs: Unpack[SettingDict]
+    ) -> Self | None:
+        obj = self if inplace else self.copy()
+        keys = obj.settings.keys()
+        for k, v in kwargs.items():
+            if v is None or k not in keys:
+                continue
+            obj.setting_check(k, v)
+            if isinstance(v, dict) and isinstance(d := obj.settings[k], dict):
+                d.update(v)
+            else:
+                obj.settings[k] = v
+        if not inplace:
+            return obj
+
+    def setting_check(self, key: SettingKey, value: Any) -> None:
+        """
+        Checks if a new setting is legal.
+
+        Parameters
+        ----------
+        key : SettingKey
+            Key of the setting.
+        value : Any
+            Value of the setting.
+
+        """
+
+    def set_default(self, **kwargs: Unpack[SettingDict]) -> None:
+        """
+        Sets the default settings.
+
+        Parameters
+        ----------
+        **kwargs : Unpack[SettingDict]
+            Specifies the settings.
+
+        """
+        keys = self.settings.keys()
+        for k, v in kwargs.items():
+            if k not in keys:
+                continue
+            if self.settings[k] is None:
+                self.settings[k] = v
+            elif isinstance(d := self.settings[k], dict):
+                self.settings[k] = {**v, **d}
+
+    def load(self, settings: "PlotSettings | SettingDict") -> None:
+        """
+        Load in the settings.
+
+        Parameters
+        ----------
+        settings : PlotSettings | SettingDict
+            An instance of `PlotSettings` or a dict.
+
+        """
+        if isinstance(settings, PlotSettings):
+            settings = asdict(settings)
+        self._set(inplace=True, **settings)
+
+    def get_setting(
+        self, key: SettingKey, default: Optional[DefaultVar] = None
+    ) -> "DefaultVar | Any":
+        """
+        Returns the value of a setting if it is not None, otherwise returns the
+        default value.
+
+        Parameters
+        ----------
+        key : SettingKey
+            Key of the setting.
+        default : DefaultVar, optional
+            Specifies the default value to be returned if the requested value
+            is None, by default None.
+
+        Returns
+        -------
+        DefaultVar | Any
+            Value of the setting.
+
+        """
+        return default if (value := self.settings[key]) is None else value
+
+    def customize(
+        self, cls: type["PlotSettableVar"], *args, **kwargs
+    ) -> "PlotSettableVar":
+        """
+        Initialize another instance with the same settings as `self`.
+
+        Parameters
+        ----------
+        cls : type[PlotSetableVar]
+            Type of the new instance.
+        *args :
+            Positional arguments.
+        **kwargs :
+            Keyword arguments.
+
+        Returns
+        -------
+        PlotSetableVar
+            The new instance.
+
+        Raises
+        ------
+        ValueError
+            Raised when `cls` cannot be customized.
+
+        """
+        if not issubclass(cls, PlotSettable):
+            raise ValueError(f"type {cls} cannot be customized")
+        matched: dict[str, Any] = {}
+        unmatched: dict[str, Any] = {}
+        for k, v in kwargs.items():
+            if k in cls.__init__.__code__.co_varnames[1:]:
+                matched[k] = v
+            else:
+                unmatched[k] = v
+        obj = cls(*args, **matched)
+        obj.settings = PlotSettings(**asdict(self.settings))
+        for k, v in unmatched.items():
+            setattr(obj, k, v)
+        return obj
+
+    def copy(self) -> Self:
+        """
+        Copy the instance of self (but not deepcopy).
+
+        Returns
+        -------
+        Self
+            A new instance of self.
+
+        """
+        raise TypeError(f"cannot copy instance of {self.__class__.__name__!r}")

dataplot/utils/__init__.py

@@ -0,0 +1,6 @@
+"""
+Contains utils for dataplot.
+
+"""
+
+__all__ = []

dataplot/utils/math.py

@@ -0,0 +1,80 @@
+"""
+The core of math: linear_regression_1d(), get_quantile(), get_prob(), etc.
+
+"""
+
+import numpy as np
+
+__all__ = ["linear_regression_1d", "get_quantile", "get_prob"]
+
+
+def linear_regression_1d(y: np.ndarray, x: np.ndarray) -> tuple[float, float]:
+    """
+    Implements a 1-demensional linear regression of y on x (y = ax + b), and
+    returns the regression coefficients (a, b). Nan-values and inf-values are
+    handled smartly.
+
+    Parameters
+    ----------
+    y : np.ndarray
+        The dependent variable.
+    x : np.ndarray
+        The independent variable.
+
+    Returns
+    -------
+    tuple[float, float]
+        The regression coefficients (a, b).
+
+    """
+    x, y = (
+        np.nan_to_num(x, posinf=np.nan, neginf=np.nan),
+        np.nan_to_num(y, posinf=np.nan, neginf=np.nan),
+    )
+    xy_mean = np.nanmean(x * y)
+    x_mean = np.nanmean(x)
+    y_mean = np.nanmean(y)
+    b = (xy_mean - x_mean * y_mean) / np.nanvar(x)
+    a = y_mean - x_mean * b
+    return a, b
+
+
+def get_quantile(data: np.ndarray, p: np.ndarray) -> np.ndarray:
+    """
+    Get quantiles from cummulative probabilities. Nan-values and inf-values
+    are handled smartly.
+
+    Parameters
+    ----------
+    data : np.ndarray
+        Original data.
+    p : np.ndarray
+        Cummulative probabilities.
+
+    Returns
+    -------
+    np.ndarray
+        Quantiles.
+
+    """
+    return np.nanquantile(np.nan_to_num(data, posinf=np.nan, neginf=np.nan), p)
+
+
+def get_prob(data: np.ndarray, q: np.ndarray) -> np.ndarray:
+    """
+    Get cummulative probabilities from quantiles.
+
+    Parameters
+    ----------
+    data : np.ndarray
+        Original data.
+    q : np.ndarray
+        Quantiles.
+
+    Returns
+    -------
+    np.ndarray
+        Cummulative probabilities.
+
+    """
+    return np.array([np.sum(data <= x) for x in q]) / np.isfinite(data).sum()

dataplot/utils/multi.py

@@ -0,0 +1,269 @@
+"""
+The core of multi: multi(), multipartial(), etc.
+
+"""
+
+from typing import Any, Callable, Generic, Iterable, LiteralString, Optional, TypeVar
+
+from validating import dataclass
+
+T = TypeVar("T")
+S = TypeVar("S", bound=LiteralString)
+
+
+__all__ = [
+    "MultiObject",
+    "multipartial",
+    "single",
+    "multiple",
+    "REMAIN",
+    "UNSUBSCRIPTABLE",
+]
+
+
+class MultiObject(Generic[T]):
+    """
+    A basic object that enables multi-element attribute-getting,
+    attribute-setting, calling, etc. This object maintains a list of items,
+    and if a method (including some magic methods, see below) is called, each
+    item's method with the same name will be called instead, and the results
+    come as a new MultiObject.
+
+    Here are the methods that will be overloaded:
+    * __getattr__()
+    * __setattr__()
+    * __call__()
+    * __getitem__()
+    * __setitem__()
+    * All public methods
+    * All private methods that starts with only one "_"
+
+    And here is the only property that is exposed outside:
+    * __multiobjects__ : returns the items
+
+    Parameters
+    ----------
+    __iterable : Iterable, optional
+        If not given, the constructor creates a new empty MultiObject. If
+        specified, the argument must be an iterable (the same as what is needed
+        for creating a list). By default None.
+    call_reducer : Callable[[list], Any], optional
+        Specifies a reducer for the return values of `__call__()`. If specified,
+        should be a callable that receives the list of original returns, and
+        gives back a reduced value. If None, the reduced value will always be a
+        new MultiObject. By default None.
+    call_reflex : bool, optional
+        If True, the return values of a previous element's `__call__()` will be
+        provided to the next element as a keyword argument named
+        '__multi_prev_returned__', by default False.
+    attr_reducer: Callable[[str], Callable[[list], Any]],  optional
+        Specifies a reducer for the return values of `__getattr__()`. If
+        specified, should be a callable that receives the attribute name, and
+        gives back a new callable. The new callable will receive the list of
+        original return values, and gives back a reduced value. If None, the
+        reduced value will always be a new MultiObject. By default None.
+
+    """
+
+    def __init__(
+        self,
+        __iterable: Optional[Iterable] = None,
+        *,
+        call_reducer: Optional[Callable[[list], Any]] = None,
+        call_reflex: bool = False,
+        attr_reducer: Optional[Callable[[str], Callable[[list], Any]]] = None,
+    ) -> None:
+        self.__call_reducer = call_reducer
+        self.__call_reflex = call_reflex
+        self.__attr_reducer = attr_reducer
+        self.__items: list[S] = [] if __iterable is None else list(__iterable)
+
+    def __getattr__(self, __name: str) -> "MultiObject | Any":
+        if __name.startswith("__"):
+            raise AttributeError(f"cannot reach attribute '{__name}'")
+        attrs = [getattr(x, __name) for x in self.__items]
+        if self.__attr_reducer:
+            reduced = self.__attr_reducer(__name)(attrs)
+            if reduced != REMAIN:
+                return reduced
+        return MultiObject(attrs)
+
+    def __setattr__(self, __name: Any, __value: Any) -> None:
+        if isinstance(__name, str) and __name.startswith("_"):
+            super().__setattr__(__name, __value)
+        else:
+            for i, obj in enumerate(self.__items):
+                setattr(obj, single(__name, n=i), single(__value, n=i))
+
+    def __call__(self, *args: Any, **kwargs: Any) -> "MultiObject | Any":
+        returns = []
+        len_items = len(self.__items)
+        r = None
+        for i, obj in enumerate(self.__items):
+            a = [single(x, n=i) for x in args]
+            kwd = {k: single(v, n=i) for k, v in kwargs.items()}
+            if self.__call_reflex:
+                kwd["__multi_is_final__"] = i == len_items - 1
+                kwd["__multi_prev_returned__"] = r if i > 0 else None
+            returns.append(r := obj(*a, **kwd))
+        if self.__call_reducer:
+            reduced = self.__call_reducer(returns)
+            if reduced != REMAIN:
+                return reduced
+        return MultiObject(returns)
+
+    def __getitem__(self, __key: Any) -> T | "MultiObject":
+        items = [x[__key] for x in self.__items]
+        if isinstance(__key, int) and UNSUBSCRIPTABLE in items:
+            return self.__items[__key]
+        return MultiObject(items)
+
+    def __setitem__(self, __key: Any, __value: Any) -> None:
+        for i, obj in enumerate(self.__items):
+            obj[single(__key, n=i)] = single(__value, n=i)
+
+    def __repr__(self) -> str:
+        return ("\n").join("- " + repr(x).replace("\n", "\n  ") for x in self.__items)
+
+    def __str__(self) -> str:
+        signature = self.__class__.__name__ + repr_not_none(self)
+        return f"{signature}"
+
+    @property
+    def __multiobjects__(self) -> list[T]:
+        return self.__items
+
+
+def repr_not_none(x: MultiObject) -> str:
+    """
+    Returns a string representation of the MultiObject's attributes with
+    not-None values. Attributes with values of None are ignored.
+
+    Parameters
+    ----------
+    x : MultiObject
+        Any object.
+
+    Returns
+    -------
+    str
+        String representation.
+
+    """
+    namelist = [n for n in x.__init__.__code__.co_varnames[1:] if not n.startswith("_")]
+    not_nones: list[str] = []
+    for n in namelist:
+        if not hasattr(x, p := f"_{type(x).__name__}__{n}"):
+            continue
+        if (v := getattr(x, p)) is None:
+            continue
+        if isinstance(v, Callable):
+            v = v.__name__
+        not_nones.append(f"{n}={v}")
+    return "" if len(not_nones) == 0 else "(" + ", ".join(not_nones) + ")"
+
+
+@dataclass(validate_methods=True)
+class MultiFlag:
+    """Flag for MultiObjects."""
+
+    flag: int
+    name: str
+    err: type | None = None
+    errmsg: str = ""
+
+    def __repr__(self) -> str:
+        if self.err is not None:
+            raise self.err(self.errmsg)
+        return self.name
+
+    def __eq__(self, __value: Any) -> bool:
+        if isinstance(__value, MultiFlag):
+            return self.flag == __value.flag
+        return False
+
+
+REMAIN = MultiFlag(0, "REMAIN")
+UNSUBSCRIPTABLE = MultiFlag(
+    -1, "UNSUBSCRIPTABLE", TypeError, "object is not subscriptable"
+)
+
+
+def multipartial(**kwargs) -> Callable[[list], MultiObject]:
+    """
+    Returns a MultiObject constructor with partial application of the
+    given arguments and keywords.
+
+    Returns
+    -------
+    Callable[[list], MultiObject]
+        A MultiObject constructor.
+
+    """
+
+    def multi_constructor(x: list):
+        return MultiObject(x, **kwargs)
+
+    return multi_constructor
+
+
+def single(x: T, n: int = -1) -> T:
+    """
+    If a MultiObject is provided, return its n-th element, otherwise return
+    the input itself.
+
+    Parameters
+    ----------
+    x : T
+        Can be a MultiObject or anything else.
+    n : int, optional
+        Specifies which element to return if a MultiObject is provided, by
+        default -1.
+
+    Returns
+    -------
+    T
+        A single object.
+
+    """
+    return x.__multiobjects__[n] if isinstance(x, MultiObject) else x
+
+
+def multiple(x: T) -> list[T]:
+    """
+    If a MultiObject is provided, return a list of its elements, otherwise
+    return `[x]`.
+
+    Parameters
+    ----------
+    x : T
+        Can be a MultiObject or anything else.
+
+    Returns
+    -------
+    list[T]
+        List of elements.
+
+    """
+    return x.__multiobjects__ if isinstance(x, MultiObject) else [x]
+
+
+def cleaner(x: list) -> MultiObject | None:
+    """
+    If the list is consist of None's only, return None, otherwise return
+    a MultiObject instantiated by the list.
+
+    Parameters
+    ----------
+    x : list
+        List of objects.
+
+    Returns
+    -------
+    MultiObject | None
+        May be a MultiObject instantiated by the list or None.
+
+    """
+    if all(i is None for i in x):
+        return None
+    return MultiObject(x, call_reducer=cleaner, attr_reducer=lambda x: cleaner)

dataplot-0.1.6.dist-info/METADATA

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: dataplot
+Version: 0.1.6
+Summary: Provides plotting tools useful in datascience.
+Project-URL: Documentation, https://github.com/Chitaoji/dataplot/blob/main/README.md
+Project-URL: Repository, https://github.com/Chitaoji/dataplot/
+Author-email: Chitaoji <2360742040@qq.com>
+Maintainer-email: Chitaoji <2360742040@qq.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: plot
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.13
+Requires-Dist: lazyr
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: scipy
+Requires-Dist: seaborn
+Requires-Dist: validating
+Description-Content-Type: text/markdown
+
+# dataplot
+Provides plotting tools useful in datascience.
+
+## Installation
+```sh
+$ pip install dataplot
+```
+
+## Requirements
+```txt
+validating
+lazyr
+matplotlib
+numpy
+pandas
+scipy
+seaborn
+```
+
+## 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.
+
+## History
+### v0.1.6
+* New method `PlotDataSet.scatter()` to draw true scatter charts while keeping `PlotDataSet.plot()` as line chart behavior.
+* Improved automatic label inference for `dp.data(...)`, plotting labels, and x-axis labels in interactive contexts.
+* Plot builders now use deferred drawing; removed `dp.show()` and improved axis/figure rendering in object representations.
+* Refined rendering stability with fixes for empty-axis cleanup and figure re-rendering in `FigWrapper.__repr__`.
+* Updated minimum required Python version to >=3.13.
+
+### v0.1.5
+* Fixed issue: unworking figure settings in the artist methods.
+
+### v0.1.4
+* Fixed issue: incorrectly displayed histogram statistics when the x-label had been modified by the user.
+
+### v0.1.3
+* Allowed users to set the plot-settings by kwargs in artist methods like `PlotDataSet.hist()`, `PlotDataSet.plot()`, etc.
+* New operation methods `PlotDataSet.signedpow()` and `PlotDataSet.log10()`.
+* Renamed `PlotDataSet.signlog()` to `.signedlog()`; renamed `PlotDataSet.opclear()` to `.undo_all()`; removed `PlotDataSet.opclear_records_only()`.
+* New optional parameter `format_label=` for `PlotDataSet.set_plot()` to decide whether to format the label when painting on the axes.
+* When defining the data classes, used *dataclasses* instead of *attrs* for a faster import.
+
+### v0.1.2
+* New methods `PlotDataSet.corrmap()`, `PlotDataSet.ppplot()`, and `PlotDataSet.resample()`.
+* New optional parameter `fmt=` for `PlotDataSet.plot()`, `PlotDataSet.qqplot()`, `PlotDataSet.ppplot()`, and `PlotDataSet.ksplot()`.
+* Bugfix.
+
+### v0.1.1
+* New module-level function `dp.show()`.
+* New methods `PlotDataSet.qqplot()`, `PlotDataSet.ksplot()` and `PlotDataSet.abs()`.
+* All the plotting method (e.g., `.hist()`) will now return an `Artist` object instead of None.
+* New plot settings: `grid` and `grid_alpha`.
+* Parameters of `FigWrapper.set_figure()`, `AxesWrapper.set_axes()` and `PlotDataSet.set_plot()` are keyword-only now.
+* The returns of `.set_figure()` and `.set_axes()` will be None (instead of `self`) to avoid misunderstandings.
+* New optional parameter `inplace=` for `PlotDataSet.set_plot()` to decide whether the changes will happen in-place (which is the only option before) or in a new copy.
+* Parameter `ticks=` for `PlotDataSet.plot()` can be set to a `PlotDataSet` object now.
+
+### v0.1.0
+* `PlotDataSet` now supports binary operations including +, -, *, /, and **.
+* New methods `FigWrapper.set_figure()` and `AxesWrapper.set_axes()` - use them instead of `*.set_plot()`.
+* Simplified the usage of `AxesWrapper`.
+* New plot settings: `subplots_adjust=`, `fontdict=` and `dpi=`.
+* After this version, the required Python version is updated to >=3.11.9. Download and install v0.0.2 if the user is under lower Python version (>=3.8.13).
+
+### v0.0.2
+* Updated the meta-data.
+
+### v0.0.1
+* Initial release.