gsplot 0.0.1__py3-none-any.whl

gsplot/plot/line_colormap_solid.py

@@ -0,0 +1,289 @@
+from typing import Any
+
+import numpy as np
+from matplotlib.axes import Axes
+from matplotlib.collections import LineCollection
+from matplotlib.colors import Normalize
+from numpy.typing import ArrayLike, NDArray
+
+from ..base.base import CreateClassParams, ParamsGetter, bind_passed_params
+from ..base.base_alias_validator import AliasValidator
+from ..figure.axes_base import AxesRangeSingleton, AxesResolver, AxisLayout
+from ..style.legend_colormap import LegendColormap
+from .line_colormap_base import LineColormapBase
+
+__all__: list[str] = ["line_colormap_solid"]
+
+
+class LineColormapSolid:
+    """
+    A class for plotting solid lines with a colormap applied along the line segments.
+
+    This class generates a single continuous line where the color is mapped to the
+    provided data using a colormap. It also supports interpolating points for smoother
+    color transitions.
+
+    Parameters
+    --------------------
+    axis_target : int or matplotlib.axes.Axes
+        The target axis for plotting. Can be an axis index or a Matplotlib `Axes` object.
+    x : ArrayLike
+        The x-coordinates of the line.
+    y : ArrayLike
+        The y-coordinates of the line.
+    cmapdata : ArrayLike
+        Data values used to map colors to the line segments.
+    cmap : str, optional
+        Name of the colormap to use (default is "viridis").
+    linewidth : int or float, optional
+        Width of the line (default is 1).
+    label : str or None, optional
+        Label for the line, used in legends (default is `None`).
+    interpolation_points : int or None, optional
+        Number of interpolation points for smooth color transitions (default is `None`).
+    **kwargs : Any
+        Additional keyword arguments passed to the `LegendColormap` class.
+
+    Attributes
+    --------------------
+    axis_index : int
+        The resolved index of the target axis.
+    axis : matplotlib.axes.Axes
+        The resolved target axis object.
+    x : numpy.ndarray
+        The x-coordinates as a NumPy array.
+    y : numpy.ndarray
+        The y-coordinates as a NumPy array.
+    cmapdata : numpy.ndarray
+        The colormap data as a NumPy array.
+
+    Methods
+    --------------------
+    add_legend_colormap()
+        Adds a legend entry for the colormap associated with the solid line.
+    normal_interpolate_points(interpolation_points)
+        Interpolates x, y, and colormap data for smoother color transitions.
+    plot()
+        Creates and plots the solid line with a colormap and returns the `LineCollection`.
+
+    Examples
+    --------------------
+    >>> x = [0, 1, 2, 3, 4]
+    >>> y = [1, 3, 2, 5, 4]
+    >>> cmapdata = [0.1, 0.3, 0.6, 0.9, 1.0]
+    >>> line = LineColormapSolid(axis_target=0, x=x, y=y, cmapdata=cmapdata, cmap="plasma")
+    >>> line.plot()
+    """
+
+    def __init__(
+        self,
+        axis_target: int | Axes,
+        x: ArrayLike,
+        y: ArrayLike,
+        cmapdata: ArrayLike,
+        cmap: str = "viridis",
+        linewidth: int | float = 1,
+        label: str | None = None,
+        interpolation_points: int | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self.axis_target: int | Axes = axis_target
+
+        self.axis_index: int = AxesResolver(axis_target).axis_index
+        self.axis: Axes = AxesResolver(axis_target).axis
+
+        self._x: ArrayLike = x
+        self._y: ArrayLike = y
+        self._cmapdata: ArrayLike = cmapdata
+        self.cmap: str = cmap
+        self.linewidth = linewidth
+        self.label: str | None = label
+        self.interpolation_points: int | None = interpolation_points
+
+        self.kwargs: Any = kwargs
+
+        self.x: NDArray[Any] = np.array(self._x)
+        self.y: NDArray[Any] = np.array(self._y)
+        self.cmapdata: NDArray[Any] = np.array(self._cmapdata)
+
+        if self.label is not None:
+            self.add_legend_colormap()
+
+    def add_legend_colormap(self) -> None:
+        """
+        Adds a legend entry for the colormap associated with the solid line.
+
+        Determines the number of stripes in the colormap based on the interpolation
+        points or the colormap data length and adds a colormap patch to the legend.
+        """
+        if self.interpolation_points is None:
+            NUM_STRIPES = len(self.cmapdata)
+        else:
+            NUM_STRIPES = self.interpolation_points
+
+        # NUM_STRIPES in colormap should be subtracted by 1
+        NUM_STRIPES -= 1
+
+        LegendColormap(
+            self.axis_index,
+            self.cmap,
+            self.label,
+            NUM_STRIPES,
+            **self.kwargs,
+        ).axis_patch()
+
+    def normal_interpolate_points(self, interpolation_points: int) -> tuple:
+        """
+        Interpolates x, y, and colormap data to create smoother transitions.
+
+        Parameters
+        --------------------
+        interpolation_points : int
+            Number of points for interpolation.
+
+        Returns
+        --------------------
+        tuple
+            Interpolated x-coordinates, y-coordinates, and colormap data.
+        """
+        xdiff = np.diff(self.x)
+        ydiff = np.diff(self.y)
+        distances = np.sqrt(xdiff**2 + ydiff**2)
+        cumulative_distances = np.insert(np.cumsum(distances), 0, 0)
+        interpolated_distances = np.linspace(
+            0, cumulative_distances[-1], interpolation_points
+        )
+
+        x_interpolated = np.interp(interpolated_distances, cumulative_distances, self.x)
+        y_interpolated = np.interp(interpolated_distances, cumulative_distances, self.y)
+
+        # Interpolate cmapdata
+        cmap_interpolated = np.interp(
+            interpolated_distances, cumulative_distances, self.cmapdata
+        )
+
+        return x_interpolated, y_interpolated, cmap_interpolated
+
+    @AxesRangeSingleton.update
+    def plot(self) -> list[LineCollection]:
+        """
+        Plots the solid line with a colormap applied to its segments.
+
+        This method interpolates points if required, creates line segments from the
+        data, and applies the colormap to the segments. The resulting line collection
+        is added to the axis.
+
+        Returns
+        --------------------
+        list[matplotlib.collections.LineCollection]
+            A list containing the single `LineCollection` object for the plotted solid line.
+
+        Notes
+        --------------------
+        This method is decorated with `@AxesRangeSingleton.update` to update the axis range.
+        """
+        if self.interpolation_points is not None:
+            self.x, self.y, self.cmapdata = self.normal_interpolate_points(
+                self.interpolation_points
+            )
+        segments: NDArray[np.float64] = LineColormapBase()._create_segment(
+            self.x, self.y
+        )
+        norm = LineColormapBase()._create_cmap(self.cmapdata)
+        print(norm)
+
+        lc: LineCollection = LineCollection(
+            segments.tolist(), cmap=self.cmap, norm=norm
+        )
+        lc.set_array(self.cmapdata)
+        lc.set_linewidth(self.linewidth)
+        lc.set_capstyle("projecting")
+        self.axis.add_collection(lc)
+
+        return [lc]
+
+
+@bind_passed_params()
+def line_colormap_solid(
+    axis_target: int | Axes,
+    x: ArrayLike,
+    y: ArrayLike,
+    cmapdata: ArrayLike,
+    cmap: str = "viridis",
+    linewidth: float | int = 1,
+    label: str | None = None,
+    interpolation_points: int | None = None,
+    **kwargs: Any,
+) -> list[LineCollection]:
+    """
+    Plots a solid line with a colormap applied along its segments.
+
+    This function creates a solid line on the specified axis with colors mapped
+    to the provided colormap data. It supports interpolation for smoother transitions
+    between segments.
+
+    Parameters
+    --------------------
+    axis_target : int or matplotlib.axes.Axes
+        The target axis for plotting. Can be an axis index or a Matplotlib `Axes` object.
+    x : ArrayLike
+        The x-coordinates of the line.
+    y : ArrayLike
+        The y-coordinates of the line.
+    cmapdata : ArrayLike
+        Data values used to map colors to the line segments.
+    cmap : str, optional
+        Name of the colormap to use (default is "viridis").
+    linewidth : float or int, optional
+        Width of the line (default is 1).
+    label : str or None, optional
+        Label for the line, used in legends (default is `None`).
+    interpolation_points : int or None, optional
+        Number of interpolation points for smooth color transitions (default is `None`).
+    **kwargs : Any
+        Additional keyword arguments passed to the `LegendColormap` class.
+
+    Notes
+    --------------------
+    - This function utilizes the `ParamsGetter` to retrieve bound parameters and the `CreateClassParams` class to handle the merging of default, configuration, and passed parameters.
+    - Alias validation is performed using the `AliasValidator` class.
+
+        - 'lw' (linewidth)
+
+    Returns
+    --------------------
+    list[matplotlib.collections.LineCollection]
+        A list containing the single `LineCollection` object for the plotted solid line.
+
+
+    Examples
+    --------------------
+    >>> import gsplot as gs
+    >>> x = [0, 1, 2, 3, 4]
+    >>> y = [1, 3, 2, 5, 4]
+    >>> cmapdata = [0.1, 0.3, 0.6, 0.9, 1.0]
+    >>> lc_list = gs.line_colormap_solid(axis_target=0, x=x, y=y, cmapdata=cmapdata, cmap="plasma")
+    >>> print(len(lc_list))
+    1
+    """
+
+    alias_map = {
+        "lw": "linewidth",
+    }
+
+    passed_params: dict[str, Any] = ParamsGetter("passed_params").get_bound_params()
+    AliasValidator(alias_map, passed_params).validate()
+    class_params = CreateClassParams(passed_params).get_class_params()
+
+    _line_colormap_solid: LineColormapSolid = LineColormapSolid(
+        class_params["axis_target"],
+        class_params["x"],
+        class_params["y"],
+        class_params["cmapdata"],
+        class_params["cmap"],
+        class_params["linewidth"],
+        class_params["label"],
+        class_params["interpolation_points"],
+        **class_params["kwargs"],
+    )
+    return _line_colormap_solid.plot()

gsplot/plot/scatter.py

@@ -0,0 +1,228 @@
+from typing import Any
+
+import numpy as np
+from matplotlib import colors
+from matplotlib.axes import Axes
+from matplotlib.collections import PathCollection
+from matplotlib.typing import ColorType
+from numpy.typing import ArrayLike, NDArray
+
+from ..base.base import CreateClassParams, ParamsGetter, bind_passed_params
+from ..base.base_alias_validator import AliasValidator
+from ..figure.axes_base import AxesRangeSingleton, AxesResolver
+from .line_base import AutoColor, NumLines
+
+__all__: list[str] = ["scatter"]
+
+
+class Scatter:
+    """
+    A class for creating scatter plots on a specified Matplotlib axis.
+
+    Parameters
+    --------------------
+    axis_target : int or matplotlib.axes.Axes
+        The target axis for the scatter plot. Can be an axis index or a Matplotlib `Axes` object.
+    x : ArrayLike
+        The x-coordinates of the scatter points.
+    y : ArrayLike
+        The y-coordinates of the scatter points.
+    color : ColorType or None, optional
+        Color of the points. If `None`, a default color from the axis's cycle is used (default is `None`).
+    size : int or float, optional
+        Size of the scatter points (default is 1).
+    alpha : int or float, optional
+        Opacity of the scatter points (default is 1).
+    **kwargs : Any
+        Additional keyword arguments passed to the `scatter` method of Matplotlib's `Axes`.
+
+    Attributes
+    --------------------
+    axis_index : int
+        The resolved index of the target axis.
+    axis : matplotlib.axes.Axes
+        The resolved target axis object.
+    x : numpy.ndarray
+        The x-coordinates as a NumPy array.
+    y : numpy.ndarray
+        The y-coordinates as a NumPy array.
+
+    Methods
+    --------------------
+    get_color() -> ColorType
+        Determines the color for the scatter points, either from the user input or the axis's color cycle.
+    plot() -> matplotlib.collections.PathCollection
+        Creates and plots the scatter points on the axis.
+
+    Examples
+    --------------------
+    >>> x = [1, 2, 3, 4]
+    >>> y = [10, 20, 15, 25]
+    >>> scatter = Scatter(axis_target=0, x=x, y=y, color="blue", size=10, alpha=0.5)
+    >>> scatter.plot()
+    """
+
+    def __init__(
+        self,
+        axis_target: int | Axes,
+        x: ArrayLike,
+        y: ArrayLike,
+        color: ColorType | None = None,
+        size: int | float = 1,
+        alpha: int | float = 1,
+        **kwargs: Any,
+    ) -> None:
+        self.axis_target: int | Axes = axis_target
+
+        self.axis_index: int = AxesResolver(self.axis_target).axis_index
+        self.axis: Axes = AxesResolver(self.axis_target).axis
+
+        self._x: ArrayLike = x
+        self._y: ArrayLike = y
+        self._color: ColorType | None = color
+        self.size: int | float = size
+        self.alpha: int | float = alpha
+        self.kwargs: Any = kwargs
+
+        self.x: NDArray[Any] = np.array(self._x)
+        self.y: NDArray[Any] = np.array(self._y)
+
+    def get_color(self) -> ColorType:
+        """
+        Determines the color for the scatter points.
+
+        If a color is not explicitly provided, it retrieves a default color from the
+        axis's color cycle.
+
+        Returns
+        --------------------
+        ColorType
+            The resolved color for the scatter points.
+
+        Notes
+        --------------------
+        The method ensures compatibility with Matplotlib's color representation, converting
+        NumPy arrays to hexadecimal strings if needed.
+
+        Examples
+        --------------------
+        >>> scatter = Scatter(axis_target=0, x=[1, 2], y=[3, 4])
+        >>> scatter.get_color()
+        """
+        cycle_color: NDArray | str = AutoColor(self.axis_index).get_color()
+        if isinstance(cycle_color, np.ndarray):
+            cycle_color = colors.to_hex(
+                tuple(cycle_color)
+            )  # convert numpy array to tuple
+
+        default_color: ColorType = cycle_color if self._color is None else self._color
+        return default_color
+
+    @NumLines.count
+    @AxesRangeSingleton.update
+    def plot(self) -> PathCollection:
+        """
+        Plots the scatter points on the specified axis.
+
+        This method creates a scatter plot using the provided x, y, color, size, and alpha values.
+
+        Returns
+        --------------------
+        matplotlib.collections.PathCollection
+            The scatter plot as a PathCollection object.
+
+        Notes
+        --------------------
+        - This method is decorated with `@NumLines.count` to track the number of scatter calls on the axis.
+        - It is also decorated with `@AxesRangeSingleton.update` to update the axis range with the scatter data.
+
+        Examples
+        --------------------
+        >>> scatter = Scatter(axis_target=0, x=[1, 2, 3], y=[4, 5, 6], size=50, alpha=0.8)
+        >>> scatter.plot()
+        <matplotlib.collections.PathCollection>
+        """
+        _plot = self.axis.scatter(
+            self.x,
+            self.y,
+            s=self.size,
+            c=self.get_color(),
+            alpha=self.alpha,
+            **self.kwargs,
+        )
+        return _plot
+
+
+@bind_passed_params()
+def scatter(
+    axis_target: int | Axes,
+    x: ArrayLike,
+    y: ArrayLike,
+    color: ColorType | None = None,
+    size: int | float = 1,
+    alpha: int | float = 1,
+    **kwargs: Any,
+) -> PathCollection:
+    """
+    Creates a scatter plot on the specified axis.
+
+    This function uses the `Scatter` class to generate a scatter plot with customizable
+    size, color, and transparency.
+
+    Parameters
+    --------------------
+    axis_target : int or matplotlib.axes.Axes
+        The target axis for the scatter plot. Can be an axis index or a Matplotlib `Axes` object.
+    x : ArrayLike
+        The x-coordinates of the scatter points.
+    y : ArrayLike
+        The y-coordinates of the scatter points.
+    color : ColorType or None, optional
+        Color of the points. If `None`, a default color from the axis's cycle is used (default is `None`).
+    size : int or float, optional
+        Size of the scatter points (default is 1).
+    alpha : int or float, optional
+        Opacity of the scatter points (default is 1).
+    **kwargs : Any
+        Additional keyword arguments passed to the `scatter` method of Matplotlib's `Axes`.
+
+    Notes
+    --------------------
+    - This function utilizes the `ParamsGetter` to retrieve bound parameters and the `CreateClassParams` class to handle the merging of default, configuration, and passed parameters.
+    - Alias validation is performed using the `AliasValidator` class.
+
+        - 's' (size)
+        - 'c' (color)
+
+    Returns
+    --------------------
+    matplotlib.collections.PathCollection
+        The scatter plot as a PathCollection object.
+
+    Examples
+    --------------------
+    >>> import gsplot as gs
+    >>> x = [1, 2, 3, 4]
+    >>> y = [10, 20, 15, 25]
+    >>> gs.scatter(axis_target=0, x=x, y=y, color="red", size=20, alpha=0.8)
+    <matplotlib.collections.PathCollection>
+    """
+    alias_map = {
+        "s": "size",
+        "c": "color",
+    }
+
+    passed_params: dict[str, Any] = ParamsGetter("passed_params").get_bound_params()
+    AliasValidator(alias_map, passed_params).validate()
+    class_params: dict[str, Any] = CreateClassParams(passed_params).get_class_params()
+
+    _scatter = Scatter(
+        class_params["axis_target"],
+        class_params["x"],
+        class_params["y"],
+        class_params["color"],
+        class_params["size"],
+        class_params["alpha"],
+        **class_params["kwargs"],
+    )
+    return _scatter.plot()