gsplot 0.0.1__py3-none-any.whl

gsplot/base/base_alias_validator.py

@@ -0,0 +1,155 @@
+import inspect
+from typing import Any
+
+from ..config.config import Config
+
+__all__: list[str] = []
+
+
+class AliasValidator:
+    """
+    Validates alias mappings for function parameters and configuration options.
+
+    This class ensures that aliased parameters do not conflict with their original keys
+    in both function arguments and configuration entries. If an alias and its original
+    key are used simultaneously, an error is raised.
+
+    Parameters
+    --------------------
+    alias_map : dict of str, Any
+        A mapping of alias keys to their original parameter keys.
+    passed_params : dict of str, Any
+        The parameters explicitly passed to the function, including `kwargs`.
+
+    Attributes
+    --------------------
+    wrapped_func_name : str
+        The name of the wrapped function where the validation is performed.
+    alias_map : dict of str, Any
+        The mapping of alias keys to original parameter keys.
+    passed_params : dict of str, Any
+        The explicitly passed parameters, updated during validation.
+    config_entry_option : dict of str, Any
+        Configuration options for the wrapped function.
+
+    Methods
+    --------------------
+    get_wrapped_func_name()
+        Retrieves the name of the wrapped function.
+    get_config_entry_option()
+        Retrieves the configuration options for the wrapped function.
+    check_duplicate_kwargs()
+        Checks and resolves conflicts between alias keys and their original keys
+        in both `passed_params` and `config_entry_option`.
+    validate()
+        Performs the full validation by checking for duplicate aliases and resolving conflicts.
+
+    Examples
+    --------------------
+    >>> @bind_passed_params()
+    >>> def example_func(p1, p2, p3):
+    >>>     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()
+    """
+
+    def __init__(
+        self,
+        alias_map: dict[str, Any],
+        passed_params: dict[str, Any],
+    ) -> None:
+        self.wrapped_func_name: str = self.get_wrapped_func_name()
+
+        self.alias_map: dict[str, Any] = alias_map
+        self.passed_params: dict[str, Any] = passed_params
+        self.config_entry_option: dict[str, Any] = self.get_config_entry_option()
+
+    def get_wrapped_func_name(self) -> str:
+        """
+        Retrieves the name of the wrapped function.
+
+        Returns
+        --------------------
+        str
+            The name of the wrapped function.
+
+        Raises
+        --------------------
+        Exception
+            If the current frame or its ancestors cannot be accessed.
+        """
+        current_frame = inspect.currentframe()
+
+        # Ensure that the frames to the wrapped function can be accessed.
+        if (
+            not current_frame
+            or not current_frame.f_back
+            or not current_frame.f_back.f_back
+        ):
+            raise Exception("Cannot get current frame")
+
+        wrapped_func_frame = current_frame.f_back.f_back
+
+        wrapped_func_name = wrapped_func_frame.f_code.co_name
+        return wrapped_func_name
+
+    def get_config_entry_option(self) -> dict[str, Any]:
+        """
+        Retrieves the configuration options for the wrapped function.
+
+        Returns
+        --------------------
+        dict of str, Any
+            The configuration options for the wrapped function.
+        """
+        config_entry_option: dict[str, Any] = Config().get_config_entry_option(
+            self.wrapped_func_name
+        )
+        return config_entry_option
+
+    def check_duplicate_kwargs(self):
+        """
+        Checks and resolves conflicts between alias keys and their original keys
+        in both `passed_params` and `config_entry_option`.
+
+        Raises
+        --------------------
+        ValueError
+            If an alias and its original key are used simultaneously in the
+            function call or configuration file.
+        """
+
+        def checker_passed_params():
+            for alias, key in self.alias_map.items():
+                if alias in self.passed_params["kwargs"]:
+                    if key in self.passed_params:
+                        raise ValueError(
+                            f"The parameters '{alias}' and '{key}' cannot both be used simultaneously in the '{self.wrapped_func_name}' function."
+                        )
+                    self.passed_params[key] = self.passed_params["kwargs"][alias]
+                    del self.passed_params["kwargs"][alias]
+
+        def checker_config_entry_option(config_entry_option: dict[str, Any]):
+            for alias, key in self.alias_map.items():
+                if alias in config_entry_option:
+                    if key in config_entry_option:
+                        raise ValueError(
+                            f"The parameters '{alias}' and '{key}' cannot both be used simultaneously in the '{self.wrapped_func_name}' in the configuration file."
+                        )
+                    Config().config_dict[self.wrapped_func_name][key] = (
+                        config_entry_option[alias]
+                    )
+                    del Config().config_dict[self.wrapped_func_name][alias]
+
+        # Check for duplicate kwargs in passed_params and config_entry_option
+        checker_passed_params()
+        checker_config_entry_option(self.config_entry_option)
+
+    def validate(self):
+        """
+        Performs the full validation by checking for duplicate aliases
+        and resolving conflicts in `passed_params` and `config_entry_option`.
+        """
+        self.check_duplicate_kwargs()

gsplot/color/colormap.py

@@ -0,0 +1,218 @@
+from typing import Any
+
+import matplotlib as mpl
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from ..base.base import CreateClassParams, ParamsGetter, bind_passed_params
+
+__all__: list[str] = ["get_cmap"]
+
+
+class Colormap:
+    """
+    A utility class for managing and generating colormap data for visualization.
+
+    This class allows for the creation of normalized and reversed colormap arrays
+    using Matplotlib colormaps.
+
+    Attributes
+    --------------------
+    DEFAULT_N : int
+        The default number of evenly spaced values to generate when no colormap data
+        or number of points (N) is provided.
+    cmap : str
+        The name of the Matplotlib colormap to use.
+    cmap_data : numpy.ndarray
+        The array of colormap data, either generated or provided.
+    normalize : bool
+        Whether to normalize the colormap data.
+    reverse : bool
+        Whether to reverse the colormap data.
+
+    Parameters
+    --------------------
+    cmap : str, optional
+        The name of the Matplotlib colormap to use (default is "viridis").
+    N : int, optional
+        The number of evenly spaced values to generate for the colormap data.
+        If specified, `cmap_data` must be `None`.
+    cmap_data : array-like, optional
+        Custom colormap data to use. If specified, `N` must be `None`.
+    normalize : bool, optional
+        Whether to normalize the colormap data (default is True).
+    reverse : bool, optional
+        Whether to reverse the colormap data (default is False).
+
+    Methods
+    --------------------
+    get_split_cmap()
+        Generates the final colormap array, applying normalization and reversal if specified.
+    _initialize_cmap_data(N, cmap_data)
+        Initializes the colormap data based on the number of points or a custom array.
+    _normalize(ndarray)
+        Normalizes an array to the range [0, 1].
+
+    Examples
+    --------------------
+    >>> colormap = Colormap(cmap="plasma", N=5, normalize=True, reverse=True)
+    >>> print(colormap.get_split_cmap())
+    [[0.940015  0.975158  0.131326  1.      ]
+     [0.647257  0.107541  0.508936  1.      ]
+     [0.20803   0.05997   0.481219  1.      ]
+     [0.069447  0.037392  0.283268  1.      ]
+     [0.050383  0.029803  0.527975  1.      ]]
+    """
+
+    DEFAULT_N: int = 10
+
+    def __init__(
+        self,
+        cmap: str = "viridis",
+        N: int | None = None,
+        cmap_data: ArrayLike | None = None,
+        normalize: bool = True,
+        reverse: bool = False,
+    ) -> None:
+
+        self.cmap: str = cmap
+        self.cmap_data: NDArray[Any] = self._initialize_cmap_data(N, cmap_data)
+        self.normalize: bool = normalize
+        self.reverse: bool = reverse
+
+    def _initialize_cmap_data(
+        self, N: int | None, cmap_data: ArrayLike | None
+    ) -> NDArray[Any]:
+        """
+        Initializes the colormap data based on the provided number of points or custom array.
+
+        Parameters
+        ----------
+        N : int, optional
+            The number of evenly spaced values to generate. If specified, `cmap_data` must be `None`.
+        cmap_data : array-like, optional
+            Custom colormap data to use. If specified, `N` must be `None`.
+
+        Returns
+        -------
+        numpy.ndarray
+            The initialized colormap data.
+
+        Raises
+        --------------------
+        ValueError
+            If both `N` and `cmap_data` are provided.
+        """
+        if N is not None and cmap_data is not None:
+            raise ValueError("Only one of N and ndarray can be specified.")
+        if N is not None:
+            return np.linspace(0, 1, N)
+        if cmap_data is not None:
+            return np.array(cmap_data)
+        return np.linspace(0, 1, self.DEFAULT_N)
+
+    def get_split_cmap(self) -> NDArray[Any]:
+        """
+        Generates the final colormap array, applying normalization and reversal if specified.
+
+        Returns
+        --------------------
+        numpy.ndarray
+            The final colormap array with RGBA values.
+        """
+        if self.normalize:
+            cmap_data = self._normalize(self.cmap_data)
+        else:
+            cmap_data = self.cmap_data
+        if self.reverse:
+            cmap_data = cmap_data[::-1]
+        return np.array(mpl.colormaps.get_cmap(self.cmap)(cmap_data))
+
+    @staticmethod
+    def _normalize(ndarray: NDArray[Any]) -> NDArray[Any]:
+        """
+        Normalizes an array to the range [0, 1].
+
+        Parameters
+        --------------------
+        ndarray : numpy.ndarray
+            The array to normalize.
+
+        Returns
+        --------------------
+        numpy.ndarray
+            The normalized array.
+        """
+        return np.array(
+            (ndarray - np.min(ndarray)) / (np.max(ndarray) - np.min(ndarray))
+        )
+
+
+@bind_passed_params()
+def get_cmap(
+    cmap: str = "viridis",
+    N: int | None = 10,
+    cmap_data: ArrayLike | None = None,
+    normalize: bool = True,
+    reverse: bool = False,
+) -> NDArray[Any]:
+    """
+    Generates a colormap array using the specified parameters.
+
+    This function provides a convenient interface to create and customize
+    colormaps using Matplotlib's colormap utilities. Parameters can be passed
+    directly or via a `Colormap` class.
+
+    Parameters
+    --------------------
+    cmap : str, optional
+        The name of the Matplotlib colormap to use (default is "viridis").
+    N : int or None, optional
+        The number of evenly spaced values to generate for the colormap data.
+        If `None`, `cmap_data` must be provided (default is 10).
+    cmap_data : array-like or None, optional
+        Custom colormap data to use. If specified, `N` must be `None` (default is None).
+    normalize : bool, optional
+        Whether to normalize the colormap data to the range [0, 1] (default is True).
+    reverse : bool, optional
+        Whether to reverse the colormap data (default is False).
+
+    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 generated colormap array as an RGBA numpy array.
+
+    Raises
+    --------------------
+    ValueError
+        If both `N` and `cmap_data` are provided simultaneously.
+
+    Examples
+    --------------------
+    >>> import gsplot as gs
+    >>> colormap_array = gs.get_cmap(cmap="plasma", N=5, normalize=True, reverse=True)
+    >>> print(colormap_array)
+    [[0.940015  0.975158  0.131326  1.      ]
+     [0.647257  0.107541  0.508936  1.      ]
+     [0.20803   0.05997   0.481219  1.      ]
+     [0.069447  0.037392  0.283268  1.      ]
+     [0.050383  0.029803  0.527975  1.      ]]
+    """
+    passed_params: dict[str, Any] = ParamsGetter("passed_params").get_bound_params()
+    class_params = CreateClassParams(passed_params).get_class_params()
+
+    _colormap: Colormap = Colormap(
+        class_params["cmap"],
+        class_params["N"],
+        class_params["cmap_data"],
+        class_params["normalize"],
+        class_params["reverse"],
+    )
+
+    return _colormap.get_split_cmap()