hilbertplot 0.0.0__py3-none-any.whl

hilbertplot/_core/geometry.py

@@ -0,0 +1,142 @@
+"""From curve words to grid coordinates, plus validation and canonicalisation.
+
+The functions here turn a word of ``u/d/l/r`` strokes into the ordered array of
+integer lattice points the curve visits, and provide the tools we use to *prove*
+the constructions are correct:
+
+* :func:`is_space_filling` checks that an order ``k`` curve visits every cell of the
+  ``2**k`` by ``2**k`` grid exactly once (a Hamiltonian path on the grid);
+* :func:`canonical_form` reduces a point sequence modulo the sixteen square
+  symmetries and reversion, so that two curves can be compared "up to rotation,
+  reflection or reversion" -- the equivalence under which the paper's forty curves
+  are distinct.
+
+Coordinates are produced with a vectorised cumulative sum, so building the
+``4**k`` points is linear in the output size with essentially no Python-level loop.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .symmetry import (
+    ANTIDIAGONAL,
+    DIAGONAL,
+    FLIP_HORIZONTAL,
+    FLIP_VERTICAL,
+    IDENTITY,
+    ROT90,
+    ROT180,
+    ROT270,
+    Symmetry,
+)
+
+__all__ = [
+    "codes_to_points",
+    "word_to_codes",
+    "word_to_steps",
+    "word_to_points",
+    "is_space_filling",
+    "canonical_form",
+    "D4_ELEMENTS",
+]
+
+#: The eight elements of D4, used for canonicalisation and (later) generalisation.
+D4_ELEMENTS: tuple[Symmetry, ...] = (
+    IDENTITY,
+    ROT90,
+    ROT180,
+    ROT270,
+    FLIP_VERTICAL,
+    FLIP_HORIZONTAL,
+    DIAGONAL,
+    ANTIDIAGONAL,
+)
+
+# Stroke codes u=0, d=1, l=2, r=3, indexed into unit (dx, dy) steps.
+_LETTER_TO_CODE = bytes.maketrans(b"udlr", bytes((0, 1, 2, 3)))
+_STEP_LOOKUP = np.array([(0, 1), (0, -1), (-1, 0), (1, 0)], dtype=np.int64)
+
+
+def word_to_codes(word: str) -> np.ndarray:
+    """Return the ``uint8`` stroke-code array for a ``u/d/l/r`` word."""
+    if not word:
+        return np.empty(0, dtype=np.uint8)
+    return np.frombuffer(word.encode("ascii").translate(_LETTER_TO_CODE), dtype=np.uint8)
+
+
+def codes_to_points(codes: np.ndarray, *, normalize: bool = True) -> np.ndarray:
+    """Return the ordered ``(len(codes) + 1, 2)`` integer points for a stroke-code array.
+
+    The walk starts at the origin and accumulates unit steps with a single vectorised
+    ``cumsum``.  With ``normalize=True`` (the default) the points are shifted so the
+    minimum corner is ``(0, 0)``; for a valid order ``k`` curve they then tile
+    ``{0, ..., 2**k - 1}`` on each axis.
+    """
+    points = np.empty((len(codes) + 1, 2), dtype=np.int64)
+    points[0] = 0
+    if len(codes):
+        np.cumsum(_STEP_LOOKUP[codes], axis=0, out=points[1:])
+    if normalize:
+        points -= points.min(axis=0)
+    return points
+
+
+def word_to_steps(word: str) -> np.ndarray:
+    """Return the ``(len(word), 2)`` array of unit ``(dx, dy)`` steps for ``word``."""
+    return _STEP_LOOKUP[word_to_codes(word)]
+
+
+def word_to_points(word: str, *, normalize: bool = True) -> np.ndarray:
+    """Return the ordered ``(len(word) + 1, 2)`` integer points a curve word visits."""
+    return codes_to_points(word_to_codes(word), normalize=normalize)
+
+
+def is_space_filling(points: np.ndarray, order: int) -> bool:
+    """Check that ``points`` is a Hamiltonian path over the ``2**order`` grid.
+
+    Verifies three things at once: the right number of points, all of them distinct,
+    and a bounding box of exactly ``2**order`` by ``2**order``.  Together these imply
+    the curve visits every cell of the square exactly once.
+    """
+    side = 2**order
+    if points.shape != (side * side, 2):
+        return False
+    lo = points.min(axis=0)
+    hi = points.max(axis=0)
+    if not (np.array_equal(lo, (0, 0)) and np.array_equal(hi, (side - 1, side - 1))):
+        return False
+    # Distinctness: pack each (x, y) into a single integer key and count uniques.
+    keys = points[:, 0] * side + points[:, 1]
+    return np.unique(keys).size == side * side
+
+
+def _transform_points(points: np.ndarray, sym: Symmetry, *, reverse: bool) -> np.ndarray:
+    (a, b), (c, d) = sym.matrix
+    x = points[:, 0]
+    y = points[:, 1]
+    out = np.empty_like(points)
+    out[:, 0] = a * x + b * y
+    out[:, 1] = c * x + d * y
+    if reverse:
+        out = out[::-1]
+    out -= out.min(axis=0)
+    return np.ascontiguousarray(out)
+
+
+def canonical_form(points: np.ndarray) -> bytes:
+    """Return a canonical byte key for ``points`` modulo symmetry and reversion.
+
+    Two point sequences share a canonical form iff one can be mapped onto the other
+    by a square symmetry (rotation/reflection) and/or reversion (traversal reversal).
+    This is exactly the equivalence under which the paper's forty curves are counted
+    as distinct, so equal canonical forms mean "the same curve".
+    """
+    best: bytes | None = None
+    for sym in D4_ELEMENTS:
+        for reverse in (False, True):
+            key = _transform_points(points, sym, reverse=reverse).tobytes()
+            if best is None or key < best:
+                best = key
+    assert best is not None
+    return best

hilbertplot/_core/symmetry.py

@@ -0,0 +1,186 @@
+"""Symmetries of the square (the dihedral group :math:`D_4`) acting on directions.
+
+Every construction rule in Estevez-Rams *et al.* (2017) is expressed with a small
+set of *morphisms* :math:`\\delta_\\bullet` that rewrite the direction letters of a
+curve word.  Each such morphism is nothing more than an element of the symmetry
+group of the square applied to unit direction vectors.  Making that explicit here
+(rather than hard-coding opaque letter tables) keeps the code principled and gives
+us the group machinery we will need later when generalising the curves to squares
+of arbitrary side.
+
+Directions
+----------
+A curve is encoded as a word over the alphabet ``{'u', 'd', 'l', 'r'}`` where each
+letter is a unit pencil stroke:
+
+======  ==========
+letter  vector
+======  ==========
+``u``   ``(0, +1)``
+``d``   ``(0, -1)``
+``l``   ``(-1, 0)``
+``r``   ``(+1, 0)``
+======  ==========
+
+The eight elements of :math:`D_4` are exposed both as named constants and through
+:data:`MORPHISMS`, keyed by the single-letter codes used throughout the paper
+(``e o a g x f m y``).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from functools import cached_property
+
+__all__ = [
+    "Direction",
+    "DIRECTIONS",
+    "DIRECTION_VECTORS",
+    "Symmetry",
+    "MORPHISMS",
+    "IDENTITY",
+    "ROT90",
+    "ROT180",
+    "ROT270",
+    "FLIP_VERTICAL",
+    "FLIP_HORIZONTAL",
+    "DIAGONAL",
+    "ANTIDIAGONAL",
+    "reverse_word",
+    "apply_morphism",
+]
+
+#: The four direction letters, in a fixed canonical order.
+DIRECTIONS: tuple[str, ...] = ("u", "d", "l", "r")
+
+#: Mapping from each direction letter to its integer unit vector ``(dx, dy)``.
+DIRECTION_VECTORS: Mapping[str, tuple[int, int]] = {
+    "u": (0, 1),
+    "d": (0, -1),
+    "l": (-1, 0),
+    "r": (1, 0),
+}
+
+# Reverse lookup: unit vector -> letter.
+_VECTOR_TO_LETTER: Mapping[tuple[int, int], str] = {v: k for k, v in DIRECTION_VECTORS.items()}
+
+# A lightweight alias; a "Direction" is just one of the letters above.
+Direction = str
+
+
+@dataclass(frozen=True)
+class Symmetry:
+    """An element of the dihedral group :math:`D_4` (symmetries of the square).
+
+    The element is stored as a 2x2 integer matrix ``((a, b), (c, d))`` acting on a
+    column vector ``(x, y)`` as ``(a*x + b*y, c*x + d*y)``.  Only the eight
+    orthogonal integer matrices with determinant :math:`\\pm 1` are valid, but the
+    class does not police this -- the named constants below are the canonical set.
+
+    Instances are immutable and hashable, so they compose cleanly and can be used
+    as dictionary keys or catalog entries.
+    """
+
+    matrix: tuple[tuple[int, int], tuple[int, int]]
+    name: str = ""
+
+    # -- action on geometry -------------------------------------------------
+    def apply_vector(self, vector: tuple[int, int]) -> tuple[int, int]:
+        """Return ``self`` applied to an integer ``(x, y)`` vector."""
+        (a, b), (c, d) = self.matrix
+        x, y = vector
+        return (a * x + b * y, c * x + d * y)
+
+    def apply_letter(self, letter: Direction) -> Direction:
+        """Return the direction letter obtained by transforming ``letter``."""
+        return self._letter_map[letter]
+
+    @cached_property
+    def _letter_map(self) -> Mapping[str, str]:
+        return {
+            letter: _VECTOR_TO_LETTER[self.apply_vector(DIRECTION_VECTORS[letter])]
+            for letter in DIRECTIONS
+        }
+
+    def apply_word(self, word: str) -> str:
+        """Rewrite every letter of ``word`` under this symmetry (a morphism)."""
+        table = self._letter_map
+        return "".join(table[letter] for letter in word)
+
+    # -- group structure ----------------------------------------------------
+    def compose(self, other: Symmetry) -> Symmetry:
+        """Return the symmetry ``self`` followed by ``other`` (``other after self``).
+
+        ``s.compose(t).apply_vector(v) == t.apply_vector(s.apply_vector(v))``.
+        """
+        (a, b), (c, d) = other.matrix
+        (e, f), (g, h) = self.matrix
+        return Symmetry(
+            (
+                (a * e + b * g, a * f + b * h),
+                (c * e + d * g, c * f + d * h),
+            )
+        )
+
+    def __matmul__(self, other: Symmetry) -> Symmetry:
+        return self.compose(other)
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        return f"Symmetry({self.name or self.matrix})"
+
+
+# The eight elements of D4.  Matrices act on (x, y) column vectors.
+IDENTITY = Symmetry(((1, 0), (0, 1)), "e")  # identity
+ROT90 = Symmetry(((0, -1), (1, 0)), "g")  # +90 deg (counter-clockwise)
+ROT180 = Symmetry(((-1, 0), (0, -1)), "f")  # 180 deg
+ROT270 = Symmetry(((0, 1), (-1, 0)), "x")  # -90 deg (clockwise)
+FLIP_VERTICAL = Symmetry(((1, 0), (0, -1)), "m")  # reflect across x-axis (y -> -y)
+FLIP_HORIZONTAL = Symmetry(((-1, 0), (0, 1)), "y")  # reflect across y-axis (x -> -x)
+DIAGONAL = Symmetry(((0, 1), (1, 0)), "o")  # reflect across line y = x
+ANTIDIAGONAL = Symmetry(((0, -1), (-1, 0)), "a")  # reflect across line y = -x
+
+#: The paper's morphisms, keyed by their single-letter codes.
+#:
+#: ``e`` identity, ``g`` = :math:`\\delta_g`, ``x`` = :math:`\\delta_x`,
+#: ``f`` = :math:`\\delta_f`, ``m`` = :math:`\\delta_m`, ``y`` = :math:`\\delta_y`,
+#: ``o`` = :math:`\\delta_o`, ``a`` = :math:`\\delta_a` (written :math:`\\delta_d`
+#: in section V of the paper).
+MORPHISMS: Mapping[str, Symmetry] = {
+    "e": IDENTITY,
+    "g": ROT90,
+    "x": ROT270,
+    "f": ROT180,
+    "m": FLIP_VERTICAL,
+    "y": FLIP_HORIZONTAL,
+    "o": DIAGONAL,
+    "a": ANTIDIAGONAL,
+}
+
+
+def apply_morphism(code: str, word: str) -> str:
+    """Apply the morphism named ``code`` (one of :data:`MORPHISMS`) to ``word``."""
+    return MORPHISMS[code].apply_word(word)
+
+
+def reverse_word(word: str) -> str:
+    """Return the *reversion* :math:`\\bar p` of a curve word.
+
+    Reversion swaps the entry and exit point of a curve: it reverses the order of
+    the strokes and negates each one (``u`` <-> ``d`` and ``l`` <-> ``r``).  This is
+    exactly walking the curve backwards, i.e. reversing the word and applying the
+    180-degree rotation :data:`ROT180` to every letter.
+
+    >>> reverse_word("ruluurdrurddldr")
+    'luruuldlulddrdl'
+    """
+    flip = ROT180._letter_map
+    return "".join(flip[letter] for letter in reversed(word))
+
+
+def compose_all(symmetries: Iterable[Symmetry]) -> Symmetry:
+    """Compose a sequence of symmetries left to right, returning their product."""
+    result = IDENTITY
+    for sym in symmetries:
+        result = result.compose(sym)
+    return result

hilbertplot/_data/__init__.py

@@ -0,0 +1 @@
+"""Internal subpackage (not part of the public API)."""

hilbertplot/_data/mapping.py

@@ -0,0 +1,255 @@
+"""Mapping 1-D data onto 2-D through a Hilbert curve, and the granularity transform.
+
+This implements the *Hilbert plot* of Estevez-Rams et al., "Visualizing long vectors
+of measurements by use of the Hilbert curve", Comput. Phys. Commun. 197 (2015) 118:
+the chosen curve is walked and value ``data[i]`` is placed at the ``i``-th cell it
+visits, so every one of the forty curves induces its own data-to-image mapping.  The
+*l-granularity* transform (eqs. 1-3) coarsens the data by replacing each block of ``l``
+values with ``l`` copies of the block mean.
+
+Everything here is curve-agnostic (functions take a plain point array), which keeps it
+reusable for the coming arbitrary-square generalisation.  Fitting a sequence whose
+length is not a power of four is an explicit choice, see :func:`resolve_order` /
+:func:`scatter`.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+__all__ = [
+    "order_for",
+    "order_floor",
+    "square_side",
+    "granulate",
+    "resolve_order",
+    "scatter",
+    "gather",
+    "label_map",
+    "difference_map",
+    "fourier_spectrum",
+]
+
+
+def order_for(n: int) -> int:
+    """Smallest order ``k`` whose ``2**k`` by ``2**k`` grid holds ``n`` values.
+
+    ``ceil(log4(n))`` -- the order the paper uses for a length-``n`` sequence.
+
+    >>> order_for(1024), order_for(1000), order_for(1025)
+    (5, 5, 6)
+    """
+    if n < 1:
+        raise ValueError(f"need at least one value, got n={n}")
+    k = 0
+    while 4**k < n:
+        k += 1
+    return k
+
+
+def order_floor(n: int) -> int:
+    """Largest order ``k`` whose grid fits *inside* ``n`` values (``floor(log4(n))``).
+
+    >>> order_floor(1024), order_floor(1000), order_floor(15)
+    (5, 4, 1)
+    """
+    if n < 1:
+        raise ValueError(f"need at least one value, got n={n}")
+    k = 0
+    while 4 ** (k + 1) <= n:
+        k += 1
+    return k
+
+
+def resolve_order(n: int, order: int | None, fit: str) -> int:
+    """Pick the grid order for ``n`` values given an explicit ``order`` or a ``fit`` mode.
+
+    ``fit="pad"`` uses the smallest enclosing grid (``order_for``); ``fit="truncate"``
+    uses the largest grid that fits inside the data (``order_floor``).  An explicit
+    ``order`` overrides both.
+    """
+    if order is not None:
+        return order
+    if fit == "pad":
+        return order_for(n)
+    if fit == "truncate":
+        return order_floor(n)
+    raise ValueError(f"fit must be 'pad' or 'truncate', got {fit!r}")
+
+
+def granulate(data, l: int) -> np.ndarray:
+    """Return the *l-granularity* representation of ``data`` (same length as the input).
+
+    The sequence is cut into non-overlapping blocks of ``l`` values and each block is
+    replaced by ``l`` copies of its mean.  ``l = 1`` returns the data unchanged (the
+    "faithful" representation); a trailing short block is averaged over what it has.
+
+    >>> granulate([0, 2, 10, 0], 2).tolist()
+    [1.0, 1.0, 5.0, 5.0]
+    """
+    if l < 1:
+        raise ValueError(f"granularity l must be >= 1, got {l}")
+    data = np.asarray(data, dtype=float).ravel()
+    if l == 1:
+        return data.copy()
+    n = data.size
+    out = np.empty(n, dtype=float)
+    full = (n // l) * l
+    if full:
+        out[:full] = np.repeat(data[:full].reshape(-1, l).mean(axis=1), l)
+    if full < n:  # trailing partial block
+        out[full:] = data[full:].mean()
+    return out
+
+
+def square_side(n: int) -> int:
+    """Smallest square side holding ``n`` values: ``ceil(sqrt(n))``.
+
+    >>> square_side(10000), square_side(1000)
+    (100, 32)
+    """
+    if n < 1:
+        raise ValueError(f"need at least one value, got n={n}")
+    s = int(n**0.5)
+    while s * s < n:
+        s += 1
+    while (s - 1) * (s - 1) >= n:
+        s -= 1
+    return s
+
+
+def scatter(points: np.ndarray, values: np.ndarray, side: int, fill: float = np.nan) -> np.ndarray:
+    """Place ``values`` onto a ``side x side`` grid along a curve's ``points`` path.
+
+    ``values[i]`` is written to ``points[i]``.  If there are more values than cells
+    they are truncated to fit; if fewer, the remaining cells keep ``fill``.  Returned
+    array is indexed ``image[y, x]`` (for ``origin="lower"`` display).
+    """
+    cap = side * side
+    values = np.asarray(values, dtype=float).ravel()
+    if values.size > cap:
+        values = values[:cap]
+    n = values.size
+    image = np.full((side, side), fill, dtype=float)
+    sel = points[:n]
+    image[sel[:, 1], sel[:, 0]] = values
+    return image
+
+
+def gather(points: np.ndarray, array: np.ndarray) -> np.ndarray:
+    """Read a 2-D ``array`` along a curve's ``points`` path -> 1-D (inverse of :func:`scatter`).
+
+    Parameters
+    ----------
+    points : numpy.ndarray
+        The ordered ``(N, 2)`` ``(x, y)`` cells the curve visits.
+    array : numpy.ndarray
+        A 2-D array indexed ``array[y, x]`` covering those cells.
+
+    Returns
+    -------
+    numpy.ndarray
+        ``array`` values in visit order, i.e. ``array[points[i, 1], points[i, 0]]``.
+    """
+    return array[points[:, 1], points[:, 0]]
+
+
+def fourier_spectrum(
+    image: np.ndarray, *, log: bool = True, window: bool = False, remove_dc: bool = True
+) -> np.ndarray:
+    """Return the centred 2-D power spectrum of a Hilbert-plot image.
+
+    The magnitude of the (fft-shifted) 2-D Fourier transform: hidden periodicities and
+    symmetries in the data show up as bright peaks and structured patterns, exactly the
+    "Fourier map" companion to the Hilbert plot of Estevez-Rams et al. (2015).
+
+    Parameters
+    ----------
+    image : numpy.ndarray
+        A 2-D array (a data image from :meth:`hilbertplot.HilbertPlot.image`).  ``NaN`` cells
+        (padding) are replaced by the finite mean before transforming.
+    log : bool, default True
+        Return ``log(1 + |F|)`` (compresses the huge dynamic range so faint structure is
+        visible); otherwise the raw magnitude.
+    window : bool, default False
+        Multiply by a 2-D Hann window first, to suppress the cross-shaped artifact from
+        the image's hard edges.
+    remove_dc : bool, default True
+        Subtract the mean before transforming, so the enormous DC (mean-brightness) spike
+        at the centre does not wash out the pattern.
+
+    Returns
+    -------
+    numpy.ndarray
+        A real ``image.shape`` array, the centred spectrum (indexed ``[y, x]``).
+    """
+    img = np.asarray(image, dtype=float)
+    if np.isnan(img).any():
+        img = np.where(np.isnan(img), np.nanmean(img), img)
+    if remove_dc:
+        img = img - img.mean()
+    if window:
+        img = img * np.outer(np.hanning(img.shape[0]), np.hanning(img.shape[1]))
+    mag = np.abs(np.fft.fftshift(np.fft.fft2(img)))
+    return np.log1p(mag) if log else mag
+
+
+def label_map(points: np.ndarray, side: int) -> np.ndarray:
+    """Return the ``(side, side)`` grid of visit-order indices (labels) for a curve.
+
+    ``label_map[y, x]`` is the step ``i`` at which the curve reaches cell ``(x, y)`` --
+    the inverse of ``points``.
+
+    Parameters
+    ----------
+    points : numpy.ndarray
+        The ordered ``(side*side, 2)`` cells the curve visits.
+    side : int
+        Grid side length (``2**order``).
+
+    Returns
+    -------
+    numpy.ndarray
+        An ``(side, side)`` integer array of labels, indexed ``[y, x]``.
+    """
+    labels = np.empty((side, side), dtype=np.int64)
+    labels[points[:, 1], points[:, 0]] = np.arange(points.shape[0])
+    return labels
+
+
+def difference_map(points: np.ndarray, side: int) -> np.ndarray:
+    """Return the *difference map*: mean 8-neighbour label distance at every cell.
+
+    At each cell the value is the mean of ``|label - neighbour_label|`` over its up-to-8
+    nearest (Moore) neighbours.  Large values mark sites where cells that are close on
+    the plane are far apart along the curve -- i.e. where locality is broken (Estevez-Rams
+    et al., "Locality preserving homogeneous Hilbert curves by use of arbitrary kernels",
+    *Appl. Math. Comput.* **234** (2014) 531).
+
+    Parameters
+    ----------
+    points : numpy.ndarray
+        The ordered ``(side*side, 2)`` cells the curve visits.
+    side : int
+        Grid side length (``2**order``).
+
+    Returns
+    -------
+    numpy.ndarray
+        An ``(side, side)`` float array of mean neighbour label differences, ``[y, x]``.
+    """
+    labels = label_map(points, side).astype(np.float64)
+    padded = np.full((side + 2, side + 2), np.nan)
+    padded[1:-1, 1:-1] = labels
+    total = np.zeros((side, side))
+    count = np.zeros((side, side))
+    for dy in (-1, 0, 1):
+        for dx in (-1, 0, 1):
+            if dx == 0 and dy == 0:
+                continue
+            neighbour = padded[1 + dy : 1 + dy + side, 1 + dx : 1 + dx + side]
+            valid = ~np.isnan(neighbour)
+            diff = np.abs(labels - neighbour)
+            total[valid] += diff[valid]
+            count[valid] += 1
+    return total / count

hilbertplot/_viz/__init__.py

@@ -0,0 +1 @@
+"""Internal subpackage (not part of the public API)."""