scales-python 1.4.0.9000__py3-none-any.whl

scales/range.py

@@ -0,0 +1,223 @@
+"""
+Mutable range classes for accumulating scale domains.
+
+Python port of ``R/range.R`` from the R *scales* package
+(https://github.com/r-lib/scales).  The R source uses R6 classes;
+here we use plain Python classes with the same ``train`` / ``reset``
+interface.
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Sequence, Union
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+__all__ = [
+    "Range",
+    "ContinuousRange",
+    "DiscreteRange",
+]
+
+
+class Range:
+    """Base range class.
+
+    Attributes
+    ----------
+    range : object or None
+        The accumulated range.  ``None`` until the first ``train()``
+        call.
+    """
+
+    def __init__(self) -> None:
+        self.range: object = None
+
+    def train(self, x: ArrayLike, **kwargs) -> None:  # pragma: no cover
+        """Update the range with new data (implemented by subclasses)."""
+        raise NotImplementedError
+
+    def reset(self) -> None:
+        """Reset the range to its initial (empty) state."""
+        self.range = None
+
+
+class ContinuousRange(Range):
+    """Mutable continuous range that accumulates via :meth:`train`.
+
+    An R6-style object that progressively builds a numeric ``(min, max)``
+    range across multiple ``train()`` calls.
+
+    Examples
+    --------
+    >>> rng = ContinuousRange()
+    >>> rng.train([1, 5, 3])
+    >>> rng.range
+    (1.0, 5.0)
+    >>> rng.train([0, 4])
+    >>> rng.range
+    (0.0, 5.0)
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.range: Optional[tuple[float, float]] = None
+
+    def train(self, x: ArrayLike) -> None:
+        """Update the range with new numeric data.
+
+        Parameters
+        ----------
+        x : array_like
+            Numeric values.  Non-finite values (``NaN``, ``Inf``) are
+            silently dropped before the range is updated.
+        """
+        x = np.asarray(x, dtype=float)
+        x = x[np.isfinite(x)]
+        if len(x) == 0:
+            return
+        new_range = (float(np.min(x)), float(np.max(x)))
+        if self.range is None:
+            self.range = new_range
+        else:
+            self.range = (
+                min(self.range[0], new_range[0]),
+                max(self.range[1], new_range[1]),
+            )
+
+    def reset(self) -> None:
+        """Reset to an empty range."""
+        self.range = None
+
+
+class DiscreteRange(Range):
+    """Mutable discrete range (ordered set of unique levels).
+
+    Mirrors R ``scales::discrete_range`` / ``clevels``
+    (scales/R/scale-discrete.R:55-116):
+
+    * If the input is a pandas Categorical (R factor), its ``categories``
+      order is preserved.
+    * Otherwise, levels are **sorted alphabetically** (R ``sort(unique(x))``).
+    * When combined with an existing range, a factor input keeps its
+      order; a non-factor combination is re-sorted.
+
+    Examples
+    --------
+    >>> rng = DiscreteRange()
+    >>> rng.train(["b", "a", "c"])
+    >>> rng.range
+    ['a', 'b', 'c']
+    >>> rng.train(["d", "a"])
+    >>> rng.range
+    ['a', 'b', 'c', 'd']
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.range: Optional[list] = None
+        self._is_factor: bool = False
+
+    def train(
+        self,
+        x: Union[ArrayLike, Sequence, "pd.Categorical"],
+        drop: bool = False,
+        na_rm: bool = False,
+    ) -> None:
+        """Update the range with new discrete data.
+
+        Parameters
+        ----------
+        x : array_like or pandas.Categorical
+            Discrete values.  If *x* is a :class:`pandas.Categorical`
+            its categories are used (respecting order).  Otherwise,
+            the unique values are sorted alphabetically to match R's
+            ``sort(unique(x))`` behaviour in ``clevels()``.
+        drop : bool, optional
+            If ``True`` and *x* is categorical, unused categories are
+            dropped before training (default ``False``).
+        na_rm : bool, optional
+            If ``True``, ``None`` / ``NaN`` values are removed before
+            training (default ``False``).
+        """
+        new_is_factor = hasattr(x, "categories")
+        # Handle pandas Categoricals — factor-style, preserve order.
+        if new_is_factor:
+            if drop:
+                x = x.remove_unused_categories()
+            levels = list(x.categories)
+        else:
+            x = np.asarray(x)
+            # R's clevels for non-factor: sort(unique(x))
+            seen: set = set()
+            uniq: list = []
+            for val in x.flat:
+                key = val
+                if isinstance(val, float) and np.isnan(val):
+                    key = None
+                if key not in seen:
+                    seen.add(key)
+                    uniq.append(val)
+            # Sort alphabetically (R default).  Keep NaN separate —
+            # sorted() will raise on mixed None/str, so we strip first
+            # and re-append.
+            non_na = [v for v in uniq if not (v is None or
+                        (isinstance(v, float) and np.isnan(v)))]
+            na_tail = [v for v in uniq if v is None or
+                        (isinstance(v, float) and np.isnan(v))]
+            try:
+                non_na = sorted(non_na)
+            except TypeError:
+                # Mixed incomparable types — keep insertion order
+                pass
+            levels = non_na + na_tail
+
+        # Optionally strip NaN / None
+        if na_rm:
+            levels = [
+                v
+                for v in levels
+                if not (v is None or (isinstance(v, float) and np.isnan(v)))
+            ]
+
+        if self.range is None:
+            # First batch — remember whether it was a factor.
+            self.range = levels
+            self._is_factor = new_is_factor
+        else:
+            # Combine with existing range.  R discrete_range
+            # (scale-discrete.R:82-96): union of old ∪ new_levels.
+            # Keep factor order if either side was a factor; else
+            # re-sort alphabetically.
+            existing_set = set()
+            for v in self.range:
+                if isinstance(v, float) and np.isnan(v):
+                    existing_set.add(None)
+                else:
+                    existing_set.add(v)
+            combined = list(self.range)
+            for v in levels:
+                key = None if (isinstance(v, float) and np.isnan(v)) else v
+                if key not in existing_set:
+                    existing_set.add(key)
+                    combined.append(v)
+
+            if self._is_factor or new_is_factor:
+                self.range = combined
+                self._is_factor = True
+            else:
+                non_na = [v for v in combined if not (v is None or
+                            (isinstance(v, float) and np.isnan(v)))]
+                na_tail = [v for v in combined if v is None or
+                            (isinstance(v, float) and np.isnan(v))]
+                try:
+                    non_na = sorted(non_na)
+                except TypeError:
+                    pass
+                self.range = non_na + na_tail
+
+    def reset(self) -> None:
+        """Reset to an empty range."""
+        self.range = None
+        self._is_factor = False

scales/scale_continuous.py

@@ -0,0 +1,146 @@
+"""
+Continuous-scale helpers: apply and train continuous scales.
+
+Python port of ``R/scale-continuous.R`` from the R *scales* package
+(https://github.com/r-lib/scales).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional, Tuple, Union
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+from .bounds import censor, rescale
+from .transforms import Transform, as_transform
+
+__all__ = [
+    "cscale",
+    "train_continuous",
+]
+
+
+def cscale(
+    x: ArrayLike,
+    palette: Callable[[np.ndarray], np.ndarray],
+    na_value: Any = np.nan,
+    trans: Optional[Union[Transform, str]] = None,
+    oob: Callable[[np.ndarray], np.ndarray] = censor,
+) -> np.ndarray:
+    """Apply a continuous scale to numeric data.
+
+    Mirrors R's ``cscale`` + ``map_continuous``: transforms *x*, rescales
+    to ``[0, 1]``, applies *oob* (censor by default) to that rescaled
+    result, then passes it through *palette*.  NaNs (including those
+    introduced by *oob*) are replaced with *na_value*.
+
+    Parameters
+    ----------
+    x : array_like
+        Numeric values in data coordinates.
+    palette : callable
+        A continuous palette function that maps values in ``[0, 1]`` to
+        output values (e.g. colours or sizes).
+    na_value : any, optional
+        Value used for ``NaN`` entries in *x* (default ``np.nan``).
+    trans : Transform or str, optional
+        If given, *x* is first transformed before rescaling.  May be a
+        :class:`~scales.transforms.Transform` object or a string name
+        recognised by :func:`~scales.transforms.as_transform`.
+    oob : callable, optional
+        Out-of-bounds handler applied to the rescaled ``[0, 1]`` values
+        before the palette.  Default is :func:`~scales.bounds.censor`,
+        which replaces values outside ``[0, 1]`` with ``NaN`` — matching
+        R's ``map_continuous(oob = censor)``.  Use
+        :func:`~scales.bounds.squish` to clamp instead.
+
+    Returns
+    -------
+    numpy.ndarray
+        Palette-mapped values, same length as *x*.
+
+    Examples
+    --------
+    >>> from scales.palettes import pal_seq_gradient
+    >>> cscale([1, 5, 10], pal_seq_gradient("white", "blue"))
+    """
+    x = np.asarray(x, dtype=float)
+
+    # 1. Optionally transform
+    if trans is not None:
+        if isinstance(trans, str):
+            trans = as_transform(trans)
+        x = trans.transform(x)
+
+    # 2. Identify NAs *before* rescaling
+    na_mask = ~np.isfinite(x)
+
+    # 3. Rescale to [0, 1] using the finite range of x
+    scaled = rescale(x, to=(0.0, 1.0))
+
+    # 4. Apply OOB handler (default: censor → NaN). After this, any value
+    #    outside [0, 1] that the user asked to censor becomes NaN.
+    scaled = np.asarray(oob(scaled), dtype=float)
+    na_mask = na_mask | ~np.isfinite(scaled)
+
+    # 5. Apply palette
+    result = palette(scaled)
+    result = np.asarray(result)
+
+    # 6. Replace NAs
+    if np.any(na_mask):
+        if result.dtype.kind in ("U", "S", "O"):
+            # String / object array
+            result = result.astype(object)
+        result[na_mask] = na_value
+
+    return result
+
+
+def train_continuous(
+    new: ArrayLike,
+    existing: Optional[Tuple[float, float]] = None,
+) -> Tuple[float, float]:
+    """Train (update) a continuous range with new data.
+
+    Combines the range of *new* with an *existing* ``(min, max)`` range
+    to produce an updated range that spans both.
+
+    Parameters
+    ----------
+    new : array_like
+        New numeric observations.  Non-finite values are ignored.
+    existing : tuple of float or None, optional
+        Previously computed ``(min, max)`` range.  ``None`` indicates
+        no prior range.
+
+    Returns
+    -------
+    tuple of float
+        Updated ``(min, max)`` range.
+
+    Examples
+    --------
+    >>> train_continuous([1, 5, 3])
+    (1.0, 5.0)
+    >>> train_continuous([0, 4], existing=(1.0, 5.0))
+    (0.0, 5.0)
+    """
+    new = np.asarray(new, dtype=float)
+    new = new[np.isfinite(new)]
+
+    if len(new) == 0:
+        if existing is None:
+            raise ValueError("Cannot train on empty data with no existing range.")
+        return existing
+
+    new_range = (float(np.min(new)), float(np.max(new)))
+
+    if existing is None:
+        return new_range
+
+    return (
+        min(existing[0], new_range[0]),
+        max(existing[1], new_range[1]),
+    )

scales/scale_discrete.py

@@ -0,0 +1,196 @@
+"""
+Discrete-scale helpers: apply and train discrete scales.
+
+Python port of ``R/scale-discrete.R`` from the R *scales* package
+(https://github.com/r-lib/scales).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, List, Optional, Sequence, Union
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+__all__ = [
+    "dscale",
+    "train_discrete",
+]
+
+
+def dscale(
+    x: ArrayLike,
+    palette: Callable[[int], Any],
+    na_value: Any = None,
+) -> np.ndarray:
+    """Apply a discrete scale to categorical data.
+
+    Maps each unique level of *x* to a palette output, then broadcasts
+    back to the full length of *x*.
+
+    Parameters
+    ----------
+    x : array_like
+        Discrete (categorical) values.  May be strings, integers, or a
+        :class:`pandas.Categorical`.
+    palette : callable
+        A discrete palette function that takes an integer *n* (number
+        of levels) and returns a sequence of *n* output values.
+    na_value : any, optional
+        Value used for ``None`` / ``NaN`` entries in *x* (default
+        ``None``).
+
+    Returns
+    -------
+    numpy.ndarray
+        Palette-mapped values, same length as *x*.
+
+    Examples
+    --------
+    >>> from scales.palettes import pal_brewer
+    >>> dscale(["a", "b", "a", "c"], pal_brewer())
+    """
+    # Determine levels (ordered unique values)
+    if hasattr(x, "categories"):
+        # pandas Categorical
+        levels = list(x.categories)
+        x_arr = np.asarray(x)
+    else:
+        x_arr = np.asarray(x)
+        # Preserve first-appearance order
+        seen: set = set()
+        levels: list = []
+        for val in x_arr.flat:
+            key = _na_key(val)
+            if key not in seen:
+                seen.add(key)
+                if not _is_na(val):
+                    levels.append(val)
+
+    n = len(levels)
+    if n == 0:
+        return np.full(x_arr.shape, na_value, dtype=object)
+
+    # Get palette colours / values for n levels
+    pal_values = palette(n)
+    pal_values = np.asarray(pal_values)
+
+    # Build lookup: level -> palette value
+    lookup: dict = {}
+    for i, lev in enumerate(levels):
+        lookup[lev] = pal_values[i] if i < len(pal_values) else na_value
+
+    # Map x through the lookup
+    result = np.empty(x_arr.shape, dtype=pal_values.dtype if len(pal_values) > 0 else object)
+    for idx in np.ndindex(x_arr.shape):
+        val = x_arr[idx]
+        if _is_na(val):
+            result[idx] = na_value
+        else:
+            result[idx] = lookup.get(val, na_value)
+
+    return result
+
+
+def train_discrete(
+    new: Union[ArrayLike, Sequence],
+    existing: Optional[List] = None,
+    drop: bool = False,
+    na_rm: bool = False,
+) -> list:
+    """Train (update) a discrete range with new data.
+
+    Combines the unique levels of *new* with an *existing* level list
+    to produce an updated set of levels (preserving order of first
+    appearance).
+
+    Parameters
+    ----------
+    new : array_like or sequence
+        New discrete observations.
+    existing : list or None, optional
+        Previously computed list of levels.  ``None`` indicates no
+        prior levels.
+    drop : bool, optional
+        If ``True`` and *new* is a :class:`pandas.Categorical`,
+        unused categories are dropped (default ``False``).
+    na_rm : bool, optional
+        If ``True``, ``None`` / ``NaN`` values are removed from the
+        result (default ``False``).
+
+    Returns
+    -------
+    list
+        Updated list of unique levels.
+
+    Examples
+    --------
+    >>> train_discrete(["a", "b", "c"])
+    ['a', 'b', 'c']
+    >>> train_discrete(["b", "d"], existing=["a", "b", "c"])
+    ['a', 'b', 'c', 'd']
+    """
+    # Extract levels from new data.
+    # R semantics: non-factor input is `sort(unique(...))`; Categorical
+    # (factor) input preserves its defined order.
+    existing_is_factor = hasattr(existing, "categories")
+    new_is_factor = hasattr(new, "categories")
+
+    if new_is_factor:
+        if drop:
+            new = new.remove_unused_categories()
+        new_levels = list(new.categories)
+    else:
+        arr = np.asarray(new)
+        seen: set = set()
+        uniq: list = []
+        for val in arr.flat:
+            key = _na_key(val)
+            if key not in seen:
+                seen.add(key)
+                uniq.append(val)
+        new_levels = uniq
+
+    if na_rm:
+        new_levels = [v for v in new_levels if not _is_na(v)]
+
+    if existing is None:
+        if new_is_factor:
+            return new_levels
+        # Non-factor: sort alphabetically per R's clevels().
+        return sorted(new_levels, key=lambda v: (v is None, str(v)))
+
+    existing_keys = {_na_key(v) for v in existing}
+    merged = list(existing)
+    for v in new_levels:
+        key = _na_key(v)
+        if key not in existing_keys:
+            existing_keys.add(key)
+            merged.append(v)
+
+    # When neither side is a factor, R re-sorts the union.
+    if not (existing_is_factor or new_is_factor):
+        merged = sorted(merged, key=lambda v: (v is None, str(v)))
+
+    return merged
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _is_na(val: Any) -> bool:
+    """Check if a value is NA-like (None or NaN)."""
+    if val is None:
+        return True
+    try:
+        return np.isnan(val)
+    except (TypeError, ValueError):
+        return False
+
+
+def _na_key(val: Any) -> Any:
+    """Return a hashable key, mapping all NA variants to ``None``."""
+    if _is_na(val):
+        return None
+    return val