gsplot 0.1.1__tar.gz → 0.1.3__tar.gz

{gsplot-0.1.1 → gsplot-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: gsplot
-Version: 0.1.1
+Version: 0.1.3
 Summary: General-scientific plot based on matplotlib
 Author: Giordano Mattoni
 Author-email: mattoni@scphys.kyoto-u.ac.jp
@@ -26,6 +26,7 @@ Description-Content-Type: text/markdown
 ![Using Poetry](https://img.shields.io/badge/Using-Poetry-blue)
 ![PyPI](https://img.shields.io/pypi/v/gsplot)
 ![PyPI - Downloads](https://img.shields.io/pypi/dm/gsplot)
+[![PyPI Downloads](https://static.pepy.tech/badge/gsplot)](https://pepy.tech/projects/gsplot)
 ![Python](https://img.shields.io/badge/python-3.10%2B-blue)
 ![License: MIT](https://img.shields.io/badge/License-MIT-green)
 
@@ -51,7 +52,7 @@ Welcome to **gsplot** (General-Scientific Plot), a toolkit designed to elevate c
 
 ### 📈 Example using gsplot
 
-[See more details](https://soichiroyamane.github.io/gsplot/guides/stable/demo/4_paper_plot.html)
+[See more details](https://soichiroyamane.github.io/gsplot/stable/guides/demo/4_paper_plot.html)
 
 ![example](docs/_static/tutorial/SC_cal.png)
 
@@ -59,7 +60,7 @@ Welcome to **gsplot** (General-Scientific Plot), a toolkit designed to elevate c
 
 [See more details](https://soichiroyamane.github.io/gsplot/stable/guides/demo/13_REPL.html)
 
-![repl_tutorial](./docs/_static/tutorial/repl_tutorial_sp.gif)
+![repl_tutorial](./docs/_static/tutorial/repl_tutorial_45fps.gif)
 
 ## 🚀 Getting Started
 

{gsplot-0.1.1 → gsplot-0.1.3}/README.md

@@ -6,6 +6,7 @@
 ![Using Poetry](https://img.shields.io/badge/Using-Poetry-blue)
 ![PyPI](https://img.shields.io/pypi/v/gsplot)
 ![PyPI - Downloads](https://img.shields.io/pypi/dm/gsplot)
+[![PyPI Downloads](https://static.pepy.tech/badge/gsplot)](https://pepy.tech/projects/gsplot)
 ![Python](https://img.shields.io/badge/python-3.10%2B-blue)
 ![License: MIT](https://img.shields.io/badge/License-MIT-green)
 
@@ -31,7 +32,7 @@ Welcome to **gsplot** (General-Scientific Plot), a toolkit designed to elevate c
 
 ### 📈 Example using gsplot
 
-[See more details](https://soichiroyamane.github.io/gsplot/guides/stable/demo/4_paper_plot.html)
+[See more details](https://soichiroyamane.github.io/gsplot/stable/guides/demo/4_paper_plot.html)
 
 ![example](docs/_static/tutorial/SC_cal.png)
 
@@ -39,7 +40,7 @@ Welcome to **gsplot** (General-Scientific Plot), a toolkit designed to elevate c
 
 [See more details](https://soichiroyamane.github.io/gsplot/stable/guides/demo/13_REPL.html)
 
-![repl_tutorial](./docs/_static/tutorial/repl_tutorial_sp.gif)
+![repl_tutorial](./docs/_static/tutorial/repl_tutorial_45fps.gif)
 
 ## 🚀 Getting Started
 

{gsplot-0.1.1 → gsplot-0.1.3}/gsplot/__init__.py

@@ -1,7 +1,7 @@
 from .color.colormap import get_cmap
 from .config.config import (Config, config_dict, config_entry_option,
                             config_load, save_metadata)
-from .data.load_file import load_file
+from .data.load_file import load_file, load_file_fast
 from .figure.axes import axes
 from .figure.axes_inset import axes_inset, axes_inset_padding
 from .figure.figure_tools import get_figure_size
@@ -22,6 +22,7 @@ from .style.legend import (legend, legend_axes, legend_get_handlers,
                            legend_handlers, legend_reverse)
 from .style.legend_colormap import legend_colormap
 from .style.ticks import ticks_off, ticks_on, ticks_on_axes
+from .style.title import title, title_axes
 from .version import __commit__, __version__
 
 # ╭──────────────────────────────────────────────────────────╮
@@ -48,6 +49,7 @@ __all__ = [
     "get_cmap",
     # data/load_file.py
     "load_file",
+    "load_file_fast",
     # figure/axes.py
     "axes",
     # figure/axes_inset.py
@@ -70,8 +72,6 @@ __all__ = [
     "pwd_main",
     # plot/line.py
     "line",
-    # plot/line_colormap.py
-    "line_colormap",
     # plot/line_colormap_solid.py
     "line_colormap_solid",
     # plot/line_colormap_dashed.py
@@ -103,4 +103,7 @@ __all__ = [
     "ticks_off",
     "ticks_on",
     "ticks_on_axes",
+    # style/title.py
+    "title",
+    "title_axes",
 ]

{gsplot-0.1.1 → gsplot-0.1.3}/gsplot/data/load_file.py

@@ -6,7 +6,7 @@ from numpy.typing import NDArray
 
 from ..base.base import CreateClassParams, ParamsGetter, bind_passed_params
 
-__all__: list[str] = ["load_file"]
+__all__: list[str] = ["load_file", "load_file_fast"]
 
 
 class LoadFile:
@@ -186,3 +186,146 @@ def load_file(
         **class_params["kwargs"],
     )
     return _load_file.load_data()
+
+
+class LoadFileFast:
+    """
+    A utility class to load data from a file or iterable source using NumPy's `loadtxt`.
+
+    This class provides an interface for loading unstructured data from files or iterables
+    with options for handling delimiters and skipping rows.
+
+    Parameters
+    --------------------
+    f : str, os.PathLike, Iterable[str], or Iterable[bytes]
+        The file path, file-like object, or iterable source from which to load data.
+    delimiter : str or None, optional
+        The string used to separate values. If `None`, any whitespace is treated as a delimiter (default is ",").
+    skiprows : int, optional
+        The number of rows to skip at the beginning of the file (default is 0).
+    unpack : bool, optional
+        Whether to unpack columns into separate arrays (default is True).
+    **kwargs : Any
+        Additional keyword arguments to pass to NumPy's `loadtxt`.
+
+    Attributes
+    --------------------
+    f : str, os.PathLike, Iterable[str], or Iterable[bytes]
+        The file path, file-like object, or iterable source from which to load data.
+    delimiter : str or None
+        The string used to separate values.
+    skiprows : int
+        The number of rows to skip at the beginning of the file.
+    unpack : bool
+        Whether to unpack columns into separate arrays.
+    kwargs : Any
+        Additional arguments passed to `loadtxt`.
+
+    Methods
+    --------------------
+    load_data()
+        Loads the data using NumPy's `loadtxt` with the specified parameters.
+    """
+
+    def __init__(
+        self,
+        f: str | PathLike | Iterable[str] | Iterable[bytes],
+        delimiter: str | None = ",",
+        skiprows: int = 0,
+        unpack: bool = True,
+        **kwargs: Any,
+    ) -> None:
+        self.f: str | PathLike | Iterable[str] | Iterable[bytes] = f
+        self.delimiter: str | None = delimiter
+        self.skiprows: int = skiprows
+        self.unpack: bool = unpack
+        self.kwargs: Any = kwargs
+
+    def load_data(self) -> NDArray[Any]:
+        """
+        Loads the data using NumPy's `loadtxt` with the specified parameters.
+
+        Returns
+        --------------------
+        numpy.ndarray
+            The loaded data as a NumPy array.
+        """
+        data = np.loadtxt(
+            fname=self.f,
+            skiprows=self.skiprows,
+            delimiter=self.delimiter,
+            unpack=self.unpack,
+            **self.kwargs,
+        )
+        return data
+
+
+@bind_passed_params()
+def load_file_fast(
+    f: str | PathLike | Iterable[str] | Iterable[bytes],
+    delimiter: str | None = ",",
+    skiprows: int = 0,
+    unpack: bool = True,
+    **kwargs: Any,
+) -> NDArray[Any]:
+    """
+    Loads unstructured data from a file or iterable source using the specified parameters.
+
+    This function provides a flexible interface for loading data with NumPy's `loadtxt`.
+    It captures and processes the passed parameters, allowing for customized file loading
+    options, such as handling delimiters, skipping rows, and unpacking columns.
+
+    Parameters
+    --------------------
+    f : str, os.PathLike, Iterable[str], or Iterable[bytes]
+        The file path, file-like object, or iterable source from which to load data.
+    delimiter : str or None, optional
+        The string used to separate values. If `None`, any whitespace is treated as a delimiter (default is ",").
+    skiprows : int, optional
+        The number of rows to skip at the beginning of the file (default is 0).
+    unpack : bool, optional
+        Whether to unpack columns into separate arrays (default is True).
+    **kwargs : Any
+        Additional keyword arguments to pass to NumPy's `loadtxt`.
+
+    Notes
+    --------------------
+    This function utilizes the `ParamsGetter` to retrieve bound parameters and
+    the `CreateClassParams` class to handle the merging of default, configuration,
+    and passed parameters.
+
+    Returns
+    --------------------
+    numpy.ndarray
+        The loaded data as a NumPy array.
+
+    Raises
+    --------------------
+    ValueError
+        If the file cannot be loaded or parsed correctly.
+
+    Examples
+    --------------------
+    >>> import gsplot as gs
+    >>> data = gs.load_file_fast("data.csv", delimiter=",", skiprows=1, unpack=False)
+    >>> print(data)
+    array([[1.0, 2.0, 3.0],
+           [4.0, 5.0, 6.0],
+           [7.0, 8.0, 9.0]])
+
+    >>> data = gs.load_file_fast(["1,2,3", "4,5,6", "7,8,9"], delimiter=",", unpack=True)
+    >>> print(data)
+    [array([1.0, 4.0, 7.0]), array([2.0, 5.0, 8.0]), array([3.0, 6.0, 9.0])]
+    """
+
+    passed_params: dict[str, Any] = ParamsGetter("passed_params").get_bound_params()
+    class_params = CreateClassParams(passed_params).get_class_params()
+
+    _load_file_fast: LoadFileFast = LoadFileFast(
+        class_params["f"],
+        class_params["delimiter"],
+        class_params["skiprows"],
+        class_params["unpack"],
+        **class_params["kwargs"],
+    )
+    return _load_file_fast.load_data()

gsplot-0.1.3/gsplot/figure/axes_base.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+from typing import Any, Callable, TypeVar
+
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.axes import Axes
+from matplotlib.transforms import Bbox
+from numpy.typing import NDArray
+
+from .figure_tools import FigureLayout
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+__all__: list[str] = []
+
+
+class AxisLayout:
+    """
+    A utility class for managing axis layout properties in a Matplotlib figure.
+
+    This class provides methods to retrieve an axis's position and size, both in
+    normalized figure coordinates and in physical units (inches). It integrates
+    with the `AxesResolver` and `FigureLayout` classes to ensure consistent layout
+    calculations.
+
+    Parameters
+    --------------------
+    ax : matplotlib.axes.Axes
+        The target `Axes` object for which to manage the
+
+    Attributes
+    --------------------
+    ax : matplotlib.axes.Axes
+        The target `Axes` object for which to manage the layout.
+    fig_size : numpy.ndarray
+        The size of the figure in inches as a NumPy array.
+
+    Methods
+    --------------------
+    get_axis_position()
+        Returns the position of the axis in normalized figure coordinates.
+    get_axis_size()
+        Returns the size of the axis in normalized figure coordinates.
+    get_axis_position_inches()
+        Returns the position of the axis in physical units (inches).
+    get_axis_size_inches()
+        Returns the size of the axis in physical units (inches).
+
+    Examples
+    --------------------
+    >>> fig, ax = plt.subplots()
+    >>> layout = AxisLayout(ax)
+    >>> position = layout.get_axis_position()
+    >>> size = layout.get_axis_size()
+    >>> position_inches = layout.get_axis_position_inches()
+    """
+
+    def __init__(self, ax: Axes) -> None:
+        self.ax: Axes = ax
+        self.fig_size: NDArray[Any] = FigureLayout().get_figure_size()
+
+    def get_axis_position(self) -> Bbox:
+        """
+        Retrieves the position of the axis in normalized figure coordinates.
+
+        Returns
+        --------------------
+        matplotlib.transforms.Bbox
+            The position of the axis as a bounding box in normalized coordinates.
+
+        Examples
+        --------------------
+        >>> layout = AxisLayout(axis_index=0)
+        >>> position = layout.get_axis_position()
+        >>> print(position)
+        Bbox(x0=0.1, y0=0.1, x1=0.9, y1=0.9)
+        """
+        axis_position = self.ax.get_position()
+        return axis_position
+
+    def get_axis_size(self) -> NDArray[Any]:
+        """
+        Retrieves the size of the axis in normalized figure coordinates.
+
+        Returns
+        --------------------
+        numpy.ndarray
+            The width and height of the axis as a NumPy array.
+
+        Examples
+        --------------------
+        >>> layout = AxisLayout(axis_index=0)
+        >>> size = layout.get_axis_size()
+        >>> print(size)
+        array([0.8, 0.8])
+        """
+        axis_position_size = np.array(self.get_axis_position().size)
+        return axis_position_size
+
+    def get_axis_position_inches(self) -> Bbox:
+        """
+        Retrieves the position of the axis in physical units (inches).
+
+        Returns
+        --------------------
+        matplotlib.transforms.Bbox
+            The position of the axis as a bounding box in inches.
+
+        Examples
+        --------------------
+        >>> layout = AxisLayout(axis_index=0)
+        >>> position_inches = layout.get_axis_position_inches()
+        >>> print(position_inches)
+        Bbox(x0=1.6, y0=1.6, x1=14.4, y1=14.4)
+        """
+
+        axis_position = self.get_axis_position()
+
+        axis_position_inches = Bbox.from_bounds(
+            axis_position.x0 * self.fig_size[0],
+            axis_position.y0 * self.fig_size[1],
+            axis_position.width * self.fig_size[0],
+            axis_position.height * self.fig_size[1],
+        )
+        return axis_position_inches
+
+    def get_axis_size_inches(self) -> NDArray[Any]:
+        """
+        Retrieves the size of the axis in physical units (inches).
+
+        Returns
+        --------------------
+        numpy.ndarray
+            The width and height of the axis in inches as a NumPy array.
+
+        Examples
+        --------------------
+        >>> layout = AxisLayout(axis_index=0)
+        >>> size_inches = layout.get_axis_size_inches()
+        >>> print(size_inches)
+        array([12.8, 12.8])
+        """
+        axis_position_size_inches = np.array(self.get_axis_position_inches().size)
+        return axis_position_size_inches

{gsplot-0.1.1 → gsplot-0.1.3}/gsplot/figure/axes_inset.py

@@ -30,10 +30,6 @@ class InsetAxesBase:
     lab_lims : list[Any] | None, optional
         List specifying axis labels and limits for the inset axis.
         Expected format: [x_label, y_label, x_lim_min, x_lim_max, y_lim_min, y_lim_max].
-    x_pad : int | float, default=2
-        Horizontal padding for axis labels.
-    y_pad : int | float, default=2
-        Vertical padding for axis labels.
     minor_ticks : bool, default=True
         Whether to enable minor ticks on the inset axis.
     zoom : bool or tuple[tuple[int, int], tuple[int, int]], default=True
@@ -97,8 +93,6 @@ class InsetAxesBase:
         ax,
         axins,
         lab_lims: list[Any] | None = None,
-        x_pad: int | float = 2,
-        y_pad: int | float = 2,
         minor_ticks: bool = True,
         zoom: bool | tuple[tuple[int, int], tuple[int, int]] = True,
         zoom_color: ColorType = "black",
@@ -108,8 +102,6 @@ class InsetAxesBase:
         self.ax: Axes = ax
         self.axins: Axes = axins
         self.lab_lims: list[Any] | None = lab_lims
-        self.x_pad: int | float = x_pad
-        self.y_pad: int | float = y_pad
         self.minor_ticks: bool = minor_ticks
         self.zoom: bool | tuple[tuple[int, int], tuple[int, int]] = zoom
         self.zoom_color: ColorType = zoom_color
@@ -233,8 +225,6 @@ class InsetAxesBase:
 
         _label = Label(
             self.lab_lims,
-            self.x_pad,
-            self.y_pad,
             minor_ticks_axes=False,
             tight_layout=False,
             **self.kwargs,
@@ -246,7 +236,7 @@ class InsetAxesBase:
             raise ValueError("lab_lims has invalid shape")
 
         # Label the inset axes
-        _label.configure_axis_labels(self.axins, x_lab, y_lab)
+        _label.configure_axis_labels(self.axins, x_lab, y_lab, **self.kwargs)
         # Set the axis limits
         _label.configure_axis_limits(self.axins, lims)
 

{gsplot-0.1.1 → gsplot-0.1.3}/gsplot/plot/scatter.py

@@ -141,7 +141,7 @@ class Scatter:
             self.x,
             self.y,
             s=self.size,
-            c=self.color,
+            color=self.color,
             alpha=self.alpha,
             **self.kwargs,
         )
@@ -187,7 +187,6 @@ def scatter(
     - Alias validation is performed using the `AliasValidator` class.
 
         - 's' (size)
-        - 'c' (color)
 
     Returns
     --------------------
@@ -204,7 +203,6 @@ def scatter(
     """
     alias_map = {
         "s": "size",
-        "c": "color",
     }
 
     passed_params: dict[str, Any] = ParamsGetter("passed_params").get_bound_params()

{gsplot-0.1.1 → gsplot-0.1.3}/gsplot/style/label.py

@@ -452,31 +452,39 @@ class Label:
     lab_lims : list[Any]
         A list specifying labels and limits for each axis in the figure. Each entry
         should be a tuple of the form `(x_label, y_label, x_limits, y_limits)`.
-    x_pad : int, default=2
-        Horizontal padding for tight layout.
-    y_pad : int, default=2
-        Vertical padding for tight layout.
+    xpad_label : int or float, default=5
+        Padding for the x-axis label.
+    ypad_label : int or float, default=5
+        Padding for the y-axis label.
     minor_ticks_axes : bool, default=True
         Whether to add minor ticks to all axes.
     tight_layout : bool, default=True
         Whether to apply `tight_layout` to the figure.
+    xpad_layout : int, default=2
+        Horizontal padding for tight layout.
+    ypad_layout : int, default=2
+        Vertical padding for tight layout.
     *args : Any
-        Additional arguments for `plt.tight_layout`.
+        Additional arguments for `ax.set_xlabel` and `ax.set_ylabel.
     **kwargs : Any
-        Additional keyword arguments for `plt.tight_layout`.
+        Additional keyword arguments for `ax.set_xlabel` and `ax.set_ylabel`.
 
     Attributes
     --------------------
     lab_lims : list[Any]
         The labels and limits configuration for the axes.
-    x_pad : int
-        Horizontal padding for tight layout.
-    y_pad : int
-        Vertical padding for tight layout.
+    xpad_label : int or float
+        Padding for the x-axis label.
+    ypad_label : int or float
+        Padding for the y-axis label.
     minor_ticks_axes : bool
         Whether minor ticks are enabled for axes.
     tight_layout : bool
         Whether `tight_layout` is applied.
+    xpad_layout : int
+        Horizontal padding for tight layout.
+    ypad_layout : int
+        Vertical padding for tight layout.
     _axes : list[Axes]
         List of axes in the current figure.
 
@@ -507,20 +515,22 @@ class Label:
     def __init__(
         self,
         lab_lims: list[Any],
-        x_pad: int | float = 2,
-        y_pad: int | float = 2,
+        xpad_label: int | float = 2,
+        ypad_label: int | float = 2,
         minor_ticks_axes: bool = True,
         tight_layout: bool = True,
-        *args: Any,
+        xpad_layout: int | float = 2,
+        ypad_layout: int | float = 2,
         **kwargs: Any,
     ) -> None:
 
         self.lab_lims: list[Any] = lab_lims
-        self.x_pad: int | float = x_pad
-        self.y_pad: int | float = y_pad
+        self.xpad_label: int | float = xpad_label
+        self.ypad_label: int | float = ypad_label
         self.minor_ticks_axes: bool = minor_ticks_axes
         self.tight_layout: bool = tight_layout
-        self.args: Any = args
+        self.xpad_layout: int | float = xpad_layout
+        self.ypad_layout: int | float = ypad_layout
         self.kwargs: Any = kwargs
 
         self._axes: list[Axes] = plt.gcf().axes
@@ -621,7 +631,15 @@ class Label:
         if self.minor_ticks_axes:
             MinorTicksAxes().set_minor_ticks_axes()
 
-    def configure_axis_labels(self, ax: Axes, x_lab: str | None, y_lab: str | None):
+    def configure_axis_labels(
+        self,
+        ax: Axes,
+        x_lab: str | None,
+        y_lab: str | None,
+        xpad_label: int | float = 10,
+        ypad_label: int | float = 10,
+        **kwargs: Any,
+    ) -> None:
         """
         Configures the labels for a given axis.
 
@@ -633,20 +651,27 @@ class Label:
             The label for the x-axis. If `None`, the x-axis label is removed.
         y_lab : str, optional
             The label for the y-axis. If `None`, the y-axis label is removed.
+        xpad_label : int or float, default=5
+            Padding for the x-axis label.
+        ypad_label : int or float, default=5
+            Padding for the y-axis label.
+        **kwargs : Any
+            Additional keyword arguments for the labels.
 
         Returns
         --------------------
         None
         """
+
         if isinstance(x_lab, str):
-            ax.set_xlabel(x_lab)
+            ax.set_xlabel(xlabel=x_lab, labelpad=xpad_label, **kwargs)
         elif x_lab is None:
             self.remove_xlabels(ax)
         else:
             raise ValueError("Invalid x-axis label. Must be a string or None.")
 
         if isinstance(y_lab, str):
-            ax.set_ylabel(y_lab)
+            ax.set_ylabel(ylabel=y_lab, labelpad=ypad_label, **kwargs)
         elif y_lab is None:
             self.remove_ylabels(ax)
         else:
@@ -676,6 +701,7 @@ class Label:
         --------------------
         None
         """
+
         if lims:
             x_lims, y_lims = lims
 
@@ -714,18 +740,40 @@ class Label:
             )
 
     def set_labels(self):
+        """
+        Applies labels, limits, and scales to all axes based on the configuration.
+
+        Returns
+        --------------------
+        None
+
+        """
         final_axes_ranges = self._get_final_axes_ranges()
 
         for i, (x_lab, y_lab, *lims) in enumerate(self.lab_lims):
             ax = self._axes[i]
 
             # Configure axis labels
-            self.configure_axis_labels(ax, x_lab, y_lab)
+            self.configure_axis_labels(
+                ax, x_lab, y_lab, self.xpad_label, self.ypad_label, **self.kwargs
+            )
 
             # Configure axis limits and scales
             self.configure_axis_limits(ax, lims, final_axes_ranges)
 
     def _calculate_padding_range(self, range: NDArray[Any]) -> NDArray[Any]:
+        """
+        Calculates the padding range for a given axis.
+
+        Parameters
+        --------------------
+        range : numpy.ndarray
+            The range of values for the axis.
+
+        Returns
+        --------------------
+        numpy.ndarray
+        """
 
         PADDING_FACTOR: float = 0.05
         span: float = range[1] - range[0]
@@ -736,11 +784,32 @@ class Label:
     def _get_wider_range(
         self, range1: NDArray[Any], range2: NDArray[Any]
     ) -> NDArray[Any]:
+        """
+        Calculates the wider range between two ranges.
+
+        Parameters
+        --------------------
+        range1 : numpy.ndarray
+            The first range of values.
+        range2 : numpy.ndarray
+            The second range of values.
+
+        Returns
+        --------------------
+        numpy.ndarray
+        """
 
         new_range = np.array([min(range1[0], range2[0]), max(range1[1], range2[1])])
         return new_range
 
     def _get_axes_ranges_current(self) -> list[list[NDArray[Any]]]:
+        """
+        Retrieves the current ranges for all axes.
+
+        Returns
+        --------------------
+        list[list[numpy.ndarray]]
+        """
 
         axes_ranges_current = []
         for ax in self._axes:
@@ -750,6 +819,13 @@ class Label:
         return axes_ranges_current
 
     def _get_final_axes_ranges(self) -> dict[Axes, list[NDArray[Any]]]:
+        """
+        Retrieves the final axes ranges for all axes.
+
+        Returns
+        --------------------
+        dict[matplotlib.axes.Axes, list[numpy.ndarray]]
+        """
         _axes_range_singleton = AxesRangeSingleton()
 
         axes_ranges_current = self._get_axes_ranges_current()
@@ -784,21 +860,28 @@ class Label:
 
     #! Xpad and Ypad will change the size of the axis
     def apply_tight_layout(self) -> None:
+        """
+        Applies `tight_layout` to the figure.
 
+        Returns
+        --------------------
+        None
+        """
         if self.tight_layout:
             # Ignore this warning when using inset_axes:
             # UserWarning: This figure includes Axes that are not compatible with tight_layout, so results might be incorrect
             with warnings.catch_warnings():
                 warnings.simplefilter("ignore")
-                try:
-                    plt.tight_layout(
-                        w_pad=self.x_pad, h_pad=self.y_pad, *self.args, **self.kwargs
-                    )
-                except Exception:
-                    plt.tight_layout(w_pad=self.x_pad, h_pad=self.y_pad)
+                plt.tight_layout(w_pad=self.xpad_layout, h_pad=self.ypad_layout)
 
     def label(self) -> None:
+        """
+        Adds labels, limits, and layouts to the figure's axes.
 
+        Returns
+        --------------------
+        None
+        """
         self.add_minor_ticks_axes()
         self.set_labels()
         self.apply_tight_layout()
@@ -808,16 +891,17 @@ class Label:
 @track_order
 def label(
     lab_lims: list[Any],
-    x_pad: int = 2,
-    y_pad: int = 2,
+    xpad_label: int | float = 5,
+    ypad_label: int | float = 5,
     minor_ticks_axes: bool = True,
     tight_layout: bool = True,
+    xpad_layout: int = 2,
+    ypad_layout: int = 2,
     *args: Any,
     **kwargs: Any,
 ) -> None:
     """
     Configures labels, limits, ticks, and layouts for Matplotlib axes.
-
     This function is a wrapper for the `Label` class.
 
     Parameters
@@ -825,18 +909,22 @@ def label(
     lab_lims : list[Any]
         A list specifying labels and limits for each axis in the figure. Each entry
         should be a tuple of the form `(x_label, y_label, x_limits, y_limits)`.
-    x_pad : int, default=2
-        Horizontal padding for tight layout.
-    y_pad : int, default=2
-        Vertical padding for tight layout.
+    xpad_label : int or float, default=5
+        Padding for the x-axis label.
+    ypad_label : int or float, default=5
+        Padding for the y-axis label.
     minor_ticks_axes : bool, default=True
         Whether to add minor ticks to all axes.
     tight_layout : bool, default=True
         Whether to apply `tight_layout` to the figure.
+    xpad_layout : int, default=2
+        Horizontal padding for tight layout.
+    ypad_layout : int, default=2
+        Vertical padding for tight layout.
     *args : Any
-        Additional arguments for `plt.tight_layout`.
+        Additional arguments for `ax.set_xlabel` and `ax.set_ylabel`.
     **kwargs : Any
-        Additional keyword arguments for `plt.tight_layout`.
+        Additional keyword arguments for `ax.set_xlabel` and `ax.set_ylabel`.
 
     Notes
     --------------------
@@ -857,8 +945,8 @@ def label(
     >>> import gsplot as gs
     >>> gs.label(
     >>>     lab_lims=[("X Label", "Y Label", [1, 10, "log"], [1, 20, 2])],
-    >>>     x_pad=5,
-    >>>     y_pad=5,
+    >>>     xpad_layout=5,
+    >>>     ypad_layout=5,
     >>> )
     """
 
@@ -867,11 +955,12 @@ def label(
 
     _label = Label(
         class_params["lab_lims"],
-        class_params["x_pad"],
-        class_params["y_pad"],
+        class_params["xpad_label"],
+        class_params["ypad_label"],
         class_params["minor_ticks_axes"],
         class_params["tight_layout"],
-        *class_params["args"],
+        class_params["xpad_layout"],
+        class_params["ypad_layout"],
         **class_params["kwargs"],
     )
 

gsplot-0.1.3/gsplot/style/title.py

@@ -0,0 +1,122 @@
+from typing import Any
+
+import matplotlib.pyplot as plt
+from matplotlib.axes import Axes
+from matplotlib.text import Text
+
+__all__ = ["title", "title_axes"]
+
+
+class Title:
+    """
+    Set the title of the current figure.
+
+    Parameters
+    --------------------
+    title : str
+    **kwargs : Any
+
+    Attributes
+    --------------------
+    title : str
+    kwargs : Any
+
+    Methods
+    --------------------
+    set_title()
+        Set the title of the current figure
+    """
+
+    def __init__(self, title: str, **kwargs: Any) -> None:
+        self.title: str = title
+        self.kwargs: Any = kwargs
+
+    def set_title(self) -> Text:
+        """
+        Set the title of the current figure.
+
+        Returns
+        --------------------
+        Text
+            The title of the current figure.
+        """
+        return plt.gcf().suptitle(self.title, **self.kwargs)
+
+
+def title(title: str, **kwargs: Any) -> Text:
+    """
+    Set the title of the current figure.
+
+    Parameters
+    --------------------
+    title : str
+        The title of the current figure.
+    **kwargs : Any
+        Additional keyword arguments to pass to the title.
+
+    Returns
+    --------------------
+    Text
+        The title of the current figure.
+    """
+    return Title(title=title, **kwargs).set_title()
+
+
+class TitleAxes:
+    """
+    Set the title of the current figure.
+
+    Parameters
+    --------------------
+    ax : Axes
+    title : str
+    **kwargs : Any
+
+    Attributes
+    --------------------
+    ax : Axes
+    title : str
+    kwargs : Any
+
+    Methods
+    --------------------
+    set_title()
+        Set the title of the current figure
+    """
+
+    def __init__(self, ax: Axes, title: str, **kwargs: Any) -> None:
+        self.ax: Axes = ax
+        self.title: str = title
+        self.kwargs: Any = kwargs
+
+    def set_title(self) -> Text:
+        """
+        Set the title of the current figure.
+
+        Returns
+        --------------------
+        Text
+            The title of the current figure.
+        """
+        return self.ax.set_title(self.title, **self.kwargs)
+
+
+def title_axes(ax: Axes, title: str, **kwargs: Any) -> Text:
+    """
+    Set the title of the current figure.
+
+    Parameters
+    --------------------
+    ax : Axes
+        The axes to set the title of.
+    title : str
+        The title of the current figure.
+    **kwargs : Any
+        Additional keyword arguments to pass to the title.
+
+    Returns
+    --------------------
+    Text
+        The title of the current figure.
+    """
+    return TitleAxes(ax=ax, title=title, **kwargs).set_title()

gsplot-0.1.3/gsplot/version.py

@@ -0,0 +1,2 @@
+__version__ = '0.1.3'
+__commit__ = '637c2d2e807a84c94b172b28e5c736bd885c3469'

{gsplot-0.1.1 → gsplot-0.1.3}/pyproject.toml

@@ -1,7 +1,7 @@
 [tool.poetry]
 name = "gsplot"
 
-version = "0.1.1"
+version = "0.1.3"
 
 description = "General-scientific plot based on matplotlib"
 authors = [

gsplot-0.1.1/gsplot/figure/axes_base.py

@@ -1,288 +0,0 @@
-from __future__ import annotations
-
-from typing import Any, Callable, TypeVar
-
-import matplotlib.pyplot as plt
-import numpy as np
-from matplotlib.axes import Axes
-from matplotlib.transforms import Bbox
-from numpy.typing import NDArray
-
-from .figure_tools import FigureLayout
-
-F = TypeVar("F", bound=Callable[..., Any])
-
-__all__: list[str] = []
-
-
-# class AxesResolver:
-#     """
-#     Resolves an axis target to a Matplotlib `Axes` object or its index.
-#
-#     This class provides a mechanism to convert an axis target, which can be either
-#     an integer (index of the axis) or an `Axes` object, into a consistent representation
-#     including the corresponding `Axes` object and its index within the current figure.
-#
-#     Parameters
-#     --------------------
-#     axis_target : int or matplotlib.axes.Axes
-#         The target axis to resolve. Can be an integer representing the index of the
-#         axis in the current figure or a specific `Axes` object.
-#
-#     Attributes
-#     --------------------
-#     axis_target : int or matplotlib.axes.Axes
-#         The input target axis (as provided by the user).
-#     _axis_index : int or None
-#         The resolved index of the target axis in the current figure.
-#     _axis : matplotlib.axes.Axes or None
-#         The resolved `Axes` object corresponding to the target.
-#
-#     Methods
-#     --------------------
-#     _resolve_type()
-#         Resolves the type of the axis target and retrieves the corresponding
-#         `Axes` object and its index.
-#     axis_index
-#         Returns the resolved index of the axis.
-#     axis
-#         Returns the resolved `Axes` object.
-#
-#     Raises
-#     --------------------
-#     IndexError
-#         If the provided axis index is out of range for the current figure.
-#     ValueError
-#         If the axis target is neither an integer nor an `Axes` object.
-#
-#     Examples
-#     --------------------
-#     >>> import matplotlib.pyplot as plt
-#     >>> fig, axs = plt.subplots(2, 2)
-#     >>> resolver = AxesResolver(1)  # Resolves the second axis (index 1)
-#     >>> print(resolver.axis)
-#     AxesSubplot(0.5,0.5;0.352273x0.352273)
-#
-#     >>> resolver = AxesResolver(axs[0, 0])  # Resolves an Axes object directly
-#     >>> print(resolver.axis_index)
-#     0
-#     """
-#
-#     def __init__(self, axis_target: int | Axes) -> None:
-#         self.axis_target: int | Axes = axis_target
-#
-#         self._axis_index: int | None = None
-#         self._axis: Axes | None = None
-#
-#         self._resolve_type()
-#
-#     def _resolve_type(self) -> None:
-#         """
-#         Resolves the type of the axis target and retrieves the corresponding
-#         `Axes` object and its index.
-#
-#         Raises
-#         --------------------
-#         IndexError
-#             If the provided axis index is out of range for the current figure.
-#         ValueError
-#             If the axis target is neither an integer nor an `Axes` object.
-#         """
-#
-#         def ordinal_suffix(n: int) -> str:
-#             if 11 <= n % 100 <= 13:
-#                 suffix = "th"
-#             else:
-#                 suffix = {1: "st", 2: "nd", 3: "rd"}.get(n % 10, "th")
-#             return f"{n}{suffix}"
-#
-#         if isinstance(self.axis_target, int):
-#             self._axis_index = self.axis_target
-#             axes = plt.gcf().axes
-#             try:
-#                 self._axis = axes[self._axis_index]
-#             except IndexError:
-#                 error_message = f"Axes out of range: {self._axis_index} => Number of axes: {len(axes)}, but requested {ordinal_suffix(self._axis_index + 1)} axis."
-#                 raise IndexError(error_message)
-#         elif isinstance(self.axis_target, Axes):
-#             self._axis = self.axis_target
-#             if self.axis_target in plt.gcf().axes:
-#                 self._axis_index = plt.gcf().axes.index(self._axis)
-#             else:
-#                 # Add the axis to the current figure if it is not present
-#                 plt.gcf().add_axes(self._axis)
-#                 self._axis_index = len(plt.gcf().axes) - 1
-#         else:
-#             raise ValueError(
-#                 "Invalid axis target. Please provide an integer or Axes object."
-#             )
-#
-#     @property
-#     def axis_index(self) -> int:
-#         """
-#         Returns the resolved index of the target axis.
-#
-#         Returns
-#         --------------------
-#         int
-#             The index of the resolved axis.
-#
-#         Raises
-#         --------------------
-#         ValueError
-#             If the axis index is not resolved.
-#         """
-#         if isinstance(self._axis_index, int):
-#             return self._axis_index
-#         else:
-#             raise ValueError("Axis index not resolved. Please check the AxisResolver")
-#
-#     @property
-#     def axis(self) -> Axes:
-#         """
-#         Returns the resolved `Axes` object.
-#
-#         Returns
-#         --------------------
-#         matplotlib.axes.Axes
-#             The resolved `Axes` object.
-#
-#         Raises
-#         --------------------
-#         ValueError
-#             If the axis is not resolved.
-#         """
-#         if isinstance(self._axis, Axes):
-#             return self._axis
-#         else:
-#             raise ValueError("Axis not resolced. Please check the AxisResolver")
-
-
-class AxisLayout:
-    """
-    A utility class for managing axis layout properties in a Matplotlib figure.
-
-    This class provides methods to retrieve an axis's position and size, both in
-    normalized figure coordinates and in physical units (inches). It integrates
-    with the `AxesResolver` and `FigureLayout` classes to ensure consistent layout
-    calculations.
-
-    Parameters
-    --------------------
-    ax : matplotlib.axes.Axes
-        The target `Axes` object for which to manage the
-
-    Attributes
-    --------------------
-    ax : matplotlib.axes.Axes
-        The target `Axes` object for which to manage the layout.
-    fig_size : numpy.ndarray
-        The size of the figure in inches as a NumPy array.
-
-    Methods
-    --------------------
-    get_axis_position()
-        Returns the position of the axis in normalized figure coordinates.
-    get_axis_size()
-        Returns the size of the axis in normalized figure coordinates.
-    get_axis_position_inches()
-        Returns the position of the axis in physical units (inches).
-    get_axis_size_inches()
-        Returns the size of the axis in physical units (inches).
-
-    Examples
-    --------------------
-    >>> fig, ax = plt.subplots()
-    >>> layout = AxisLayout(ax)
-    >>> position = layout.get_axis_position()
-    >>> size = layout.get_axis_size()
-    >>> position_inches = layout.get_axis_position_inches()
-    """
-
-    def __init__(self, ax: Axes) -> None:
-        self.ax: Axes = ax
-        self.fig_size: NDArray[Any] = FigureLayout().get_figure_size()
-
-    def get_axis_position(self) -> Bbox:
-        """
-        Retrieves the position of the axis in normalized figure coordinates.
-
-        Returns
-        --------------------
-        matplotlib.transforms.Bbox
-            The position of the axis as a bounding box in normalized coordinates.
-
-        Examples
-        --------------------
-        >>> layout = AxisLayout(axis_index=0)
-        >>> position = layout.get_axis_position()
-        >>> print(position)
-        Bbox(x0=0.1, y0=0.1, x1=0.9, y1=0.9)
-        """
-        axis_position = self.ax.get_position()
-        return axis_position
-
-    def get_axis_size(self) -> NDArray[Any]:
-        """
-        Retrieves the size of the axis in normalized figure coordinates.
-
-        Returns
-        --------------------
-        numpy.ndarray
-            The width and height of the axis as a NumPy array.
-
-        Examples
-        --------------------
-        >>> layout = AxisLayout(axis_index=0)
-        >>> size = layout.get_axis_size()
-        >>> print(size)
-        array([0.8, 0.8])
-        """
-        axis_position_size = np.array(self.get_axis_position().size)
-        return axis_position_size
-
-    def get_axis_position_inches(self) -> Bbox:
-        """
-        Retrieves the position of the axis in physical units (inches).
-
-        Returns
-        --------------------
-        matplotlib.transforms.Bbox
-            The position of the axis as a bounding box in inches.
-
-        Examples
-        --------------------
-        >>> layout = AxisLayout(axis_index=0)
-        >>> position_inches = layout.get_axis_position_inches()
-        >>> print(position_inches)
-        Bbox(x0=1.6, y0=1.6, x1=14.4, y1=14.4)
-        """
-
-        axis_position = self.get_axis_position()
-
-        axis_position_inches = Bbox.from_bounds(
-            axis_position.x0 * self.fig_size[0],
-            axis_position.y0 * self.fig_size[1],
-            axis_position.width * self.fig_size[0],
-            axis_position.height * self.fig_size[1],
-        )
-        return axis_position_inches
-
-    def get_axis_size_inches(self) -> NDArray[Any]:
-        """
-        Retrieves the size of the axis in physical units (inches).
-
-        Returns
-        --------------------
-        numpy.ndarray
-            The width and height of the axis in inches as a NumPy array.
-
-        Examples
-        --------------------
-        >>> layout = AxisLayout(axis_index=0)
-        >>> size_inches = layout.get_axis_size_inches()
-        >>> print(size_inches)
-        array([12.8, 12.8])
-        """
-        axis_position_size_inches = np.array(self.get_axis_position_inches().size)
-        return axis_position_size_inches

gsplot-0.1.1/gsplot/version.py

@@ -1,2 +0,0 @@
-__version__ = '0.1.1'
-__commit__ = '1edf3b25e5a53fef29c008d68dd3c0035ea93fe6'