labelarray 0.1.0__py3-none-any.whl

labelarray/labels.py

@@ -0,0 +1,244 @@
+"""One exact-label rule for every path that compares labels.
+
+Labels on an axis match only when they are the same kind (booleans, numbers,
+times, durations, text, bytes) and exactly equal: a label is never converted
+in a way that changes it to make a match. The integer ``2**53 + 1`` does not
+match the float ``2**53``, a half-second does not match whole seconds, and
+``True`` does not match ``1``. A missing label (NaN or NaT) matches a missing
+label of the same kind. Alignment and joins use these functions on both
+backends, so they agree whatever the label types or their order; the label
+indexes (``labelarray.index``) convert lookups with ``exact_cast`` too.
+
+This module needs NumPy only.
+"""
+
+from __future__ import annotations
+
+import warnings
+from collections import Counter
+from collections.abc import Hashable
+from typing import Any
+
+import numpy as np
+
+from labelarray.errors import LabelError
+
+# Label kinds that can match each other. Booleans, numbers, times, durations,
+# text, and bytes never match across kinds, as in pandas: True is not 1.
+KINDS = {"b": "bool", "i": "number", "u": "number", "f": "number", "c": "number",
+         "M": "time", "m": "duration", "U": "text", "S": "bytes"}
+
+# Kinds registered with an index (``labelarray.index.register_index``), by the Python types
+# their labels have. Such labels match only labels of the same kind, like the kinds above.
+_REGISTERED_TYPES: dict[str, tuple[type, ...]] = {}
+
+
+def kind(values: np.ndarray, op: str = "index", dim: Hashable = None) -> tuple[str, np.ndarray]:
+    """The label kind, with object arrays of one Python type converted to it.
+
+    Object labels whose types a registered kind names (``register_types``)
+    are that kind, and stay objects.
+    """
+    values = np.asarray(values)
+    if values.dtype.kind != "O":
+        return KINDS.get(values.dtype.kind, "other"), values
+    if values.size == 0:
+        return "other", values
+    types = {type(v) for v in values.tolist()}
+    for name, accepted, convert in (
+        ("text", (str,), str), ("bytes", (bytes,), bytes), ("bool", (bool, np.bool_), bool),
+    ):
+        if all(issubclass(t, accepted) for t in types):
+            return name, np.array(values.tolist(), dtype=convert)
+    if all(issubclass(t, (int, float, complex, np.number)) and not issubclass(t, (bool, np.bool_)) for t in types):
+        return "number", np.array(values.tolist())
+    for name, accepted in _REGISTERED_TYPES.items():
+        if all(issubclass(t, accepted) for t in types):
+            return name, values
+    names = ", ".join(sorted(t.__name__ for t in types))
+    raise LabelError(f"{op}: labels on {dim!r} mix types ({names}), so they cannot be ordered or looked up; "
+                     "give the axis labels of one type")
+
+
+def register_types(name: str, types: tuple[type, ...]) -> None:
+    """Make object labels of *types* the kind *name*, or forget *name* when *types* is empty."""
+    if name in KINDS.values():
+        raise ValueError(f"{name} is a built-in label kind; types name the labels of a new kind")
+    _REGISTERED_TYPES.pop(name, None)
+    if types:
+        _REGISTERED_TYPES[name] = tuple(types)
+
+
+def missing(values: np.ndarray) -> np.ndarray:
+    if values.dtype.kind in "fc":
+        return np.isnan(values)
+    if values.dtype.kind in "mM":
+        return np.isnat(values)
+    return np.zeros(values.shape, dtype=bool)
+
+
+def exact_cast(wanted: np.ndarray, dtype: np.dtype) -> tuple[np.ndarray, np.ndarray]:
+    """*wanted* in *dtype*, and where that conversion is exact.
+
+    A value that changes on the way, such as float64 0.1 as float32, a
+    half-second as whole seconds, or -1 as an unsigned integer, is not
+    exact; nothing is rounded to make a match. Missing values are not exact.
+    """
+    with np.errstate(all="ignore"), warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+        cast = wanted.astype(dtype)
+        exact = cast.astype(wanted.dtype) == wanted
+    if dtype.kind in "iu" and wanted.dtype.kind == "f":
+        # A float beyond the integers saturates on some machines (2.0**63 becomes 2**63 - 1 on
+        # ARM), and the saturated value rounds back to the float, so the round trip cannot tell.
+        # The limits are powers of two, exact as floats.
+        info = np.iinfo(dtype)
+        exact &= (wanted >= float(info.min)) & (wanted < float(info.max + 1))
+    elif dtype.kind == "u" and wanted.dtype.kind == "i":
+        exact &= wanted >= 0
+    elif dtype.kind == "i" and wanted.dtype.kind == "u":
+        exact &= wanted <= np.iinfo(dtype).max
+    return cast, np.asarray(exact, dtype=bool)
+
+
+def equal(a: Any, b: Any) -> bool:
+    """The same labels in the same order; a missing label equals a missing label."""
+    if a is b:
+        return True
+    a, b = np.asarray(a), np.asarray(b)
+    if len(a) != len(b):
+        return False
+    if not len(a):
+        return True
+    try:
+        kind_a, a = kind(a)
+        kind_b, b = kind(b)
+    except LabelError:
+        return _keys(a) == _keys(b)
+    if kind_a != kind_b:
+        return False
+    if kind_a == "other":
+        return _keys(a) == _keys(b)
+    gaps_a, gaps_b = missing(a), missing(b)
+    if not np.array_equal(gaps_a, gaps_b):
+        return False
+    if gaps_a.any():
+        a, b = a[~gaps_a], b[~gaps_b]
+    if a.dtype == b.dtype:
+        return bool(np.array_equal(a, b))
+    cast, exact = exact_cast(b, a.dtype)
+    return bool(exact.all() and np.array_equal(cast, a))
+
+
+def compare(a: Any, b: Any, op: str = "align", dim: Hashable = None, *,
+            mixed: bool = False) -> tuple[str, int, int]:
+    """``("same", 0, 0)``, ``("reordered", 0, 0)``, or ``("different", only in a, only in b)``.
+
+    "Reordered" means both hold the same labels as many times each. Counts
+    are of distinct labels. Labels of mixed Python types are an error naming
+    *op* and *dim*, unless *mixed* is true; then they are compared one by
+    one, each with its own kind.
+    """
+    if equal(a, b):
+        return "same", 0, 0
+    a, b = np.asarray(a), np.asarray(b)
+    try:
+        kind_a, values_a = kind(a, op, dim)
+        kind_b, values_b = kind(b, op, dim)
+    except LabelError:
+        if not mixed:
+            raise
+        kind_a = kind_b = "other"
+    if kind_a == "other" or kind_b == "other":
+        keys_a, keys_b = _keys(a), _keys(b)
+        if Counter(keys_a) == Counter(keys_b):
+            return "reordered", 0, 0
+        return "different", len(set(keys_a) - set(keys_b)), len(set(keys_b) - set(keys_a))
+    if len(a) == len(b) and kind_a == kind_b and _same_multiset(values_a, values_b):
+        return "reordered", 0, 0
+    found_a, found_b = _found(kind_a, values_a, kind_b, values_b), _found(kind_b, values_b, kind_a, values_a)
+    return "different", _distinct(values_a[~found_a]), _distinct(values_b[~found_b])
+
+
+def strict_subset(part: Any, whole: Any, op: str = "align", dim: Hashable = None, *, mixed: bool = False) -> bool:
+    """Whether *part*'s labels are some, but not all, of *whole*'s."""
+    state, only_part, only_whole = compare(part, whole, op, dim, mixed=mixed)
+    return state == "different" and only_part == 0 and only_whole > 0
+
+
+def lossy_join_type(a: Any, b: Any) -> np.dtype | None:
+    """The type a join would hold both label arrays in, when it cannot hold them all exactly.
+
+    Joined labels take NumPy's common type, so int64 labels joined with
+    float64 ones become float64; ``2**53 + 1`` cannot survive that, and a
+    join would then pair it with ``2**53``. None when every label survives.
+    """
+    a, b = np.asarray(a), np.asarray(b)
+    if a.dtype == b.dtype:
+        return None
+    try:
+        common = np.result_type(a.dtype, b.dtype)
+    except TypeError:
+        return None
+    if common.kind == "O":
+        return None
+    for values in (a, b):
+        if values.dtype != common:
+            _, exact = exact_cast(values, common)
+            if not (exact | missing(values)).all():
+                return common
+    return None
+
+
+def _found(kind_a: str, a: np.ndarray, kind_b: str, b: np.ndarray) -> np.ndarray:
+    """Which labels of *a* are among *b*'s, exactly."""
+    found = np.zeros(len(a), dtype=bool)
+    if kind_a != kind_b or not len(a) or not len(b):
+        return found
+    gaps_a, gaps_b = missing(a), missing(b)
+    found[gaps_a] = gaps_b.any()
+    rest = ~gaps_a
+    present_a, present_b = a[rest], b[~gaps_b]
+    if present_a.dtype == present_b.dtype:
+        found[rest] = np.isin(present_a, present_b)
+    else:
+        cast, exact = exact_cast(present_a, present_b.dtype)
+        found[rest] = exact & np.isin(cast, present_b)
+    return found
+
+
+def _same_multiset(a: np.ndarray, b: np.ndarray) -> bool:
+    """Whether *a* and *b*, of one kind and length, hold the same labels as many times each."""
+    gaps_a, gaps_b = missing(a), missing(b)
+    if gaps_a.sum() != gaps_b.sum():
+        return False
+    a, b = a[~gaps_a], b[~gaps_b]
+    if a.dtype != b.dtype:
+        b, exact = exact_cast(b, a.dtype)
+        if not exact.all():
+            return False
+    return bool(np.array_equal(np.sort(a), np.sort(b)))
+
+
+def _distinct(values: np.ndarray) -> int:
+    if not len(values):
+        return 0
+    gaps = missing(values)
+    return len(np.unique(values[~gaps])) + int(gaps.any())
+
+
+def _keys(values: np.ndarray) -> list:
+    """Labels as hashable Python values tagged with their kind, a missing label as one key.
+
+    Python compares its numbers exactly (``2**53 + 1 != float(2**53)``);
+    the tag keeps ``True`` apart from ``1``.
+    """
+    return [("missing",) if v != v else (_tag(v), v) for v in np.asarray(values).tolist()]
+
+
+def _tag(value: Any) -> str:
+    if isinstance(value, (bool, np.bool_)):
+        return "bool"
+    if isinstance(value, (int, float, complex, np.number)):
+        return "number"
+    return type(value).__name__

labelarray/sums.py

@@ -0,0 +1,317 @@
+"""Float32 sums and means: float64 accumulation, rounded once to float32.
+
+Two ways, chosen by how many values each result adds:
+
+- Every grouped reduction, and every ungrouped one adding ``FEW`` (8) or more
+  values per result: the result is correctly rounded, the float32 nearest
+  the exact sum or mean of the stored values, ties to even. A float64 sum
+  and an error bound settle almost every result; where the bound cannot,
+  the values are added exactly (``_exact``). A correctly rounded result is
+  unique, so every memory layout, summation order, kernel (NumPy or the
+  optional compiled one), thread count, and backend gives the same bits.
+- Ungrouped reductions adding fewer than ``FEW`` values per result, such as
+  ``sum(p**2, over="i")`` over x, y, and z: the values are added in float64
+  in a fixed order, first to last along the reduced axes, and rounded once.
+  The order does not depend on memory layout; the compiled kernel, when
+  installed, adds in the same order in one pass. Checking each of these results
+  would cost several times the sum itself (the float64 sum of a few float32
+  values is often exact and exactly halfway between two float32 values, where
+  a bound cannot decide), so cancellation among those few values is rounded
+  in float64 as it goes: ``[2**53, 1, -2**53]`` sums to 0 here, not 1.
+
+Missing values: without ``na_rm`` a NaN makes its result NaN; with it, NaN
+is skipped and a mean divides by the values present. +inf and -inf together
+give NaN. A sum of no values is +0.0 and a mean NaN; a zero sum is +0.0, as
+NumPy gives it. ``min_count`` makes a sum NaN where fewer values are present.
+This module needs NumPy only.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Sequence
+from fractions import Fraction
+
+import numpy as np
+
+FEW = 8
+COMPILED = True  # use the optional compiled kernels when Numba is installed
+# From these many values; below them, calling compiled code costs more than it saves. Grouped sums: 34,688
+# values took 201 µs compiled against 155, 300,000 took 322 against 1,231. Few-value sums: 180,000 values
+# 89 against 78 µs, 300,000 103 against 118. Both paths give the same bits.
+COMPILED_FROM = 100_000
+IN_ORDER_COMPILED_FROM = 300_000
+
+_U = 2.0**-53  # float64 unit roundoff
+# Sums are made in chunks of positions, then the chunk totals added, so a result's error bound grows
+# with the chunk length plus the number of chunks rather than with every position: about sqrt(n) chunks
+# of sqrt(n) positions, with at most this many (chunk, group) bins at once.
+_BINS = 1 << 22
+_MAX32 = Fraction(float(np.finfo(np.float32).max))
+
+
+def reduce(values: np.ndarray, op: str, axes: Sequence[int], *, na_rm: bool = False,
+           min_count: int | None = None, codes: np.ndarray | None = None, groups: int = 0,
+           sizes: np.ndarray | None = None) -> np.ndarray:
+    """*op* (``"sum"`` or ``"mean"``) of float32 *values* over the axis numbers *axes*.
+
+    Without *codes*, the result has the kept axes in their order. With
+    *codes* (one group code from 0 to ``groups - 1`` per position along
+    ``axes[0]``), it has one row per group first: ``(groups, *kept)``;
+    *sizes*, positions per group along ``axes[0]``, may be passed when known.
+    """
+    values = np.asarray(values)
+    if values.dtype != np.float32:
+        raise TypeError(f"float32 values expected, got {values.dtype}")
+    axes = tuple(int(a) for a in axes)
+    kept = tuple(a for a in range(values.ndim) if a not in axes)
+    kept_shape = tuple(values.shape[a] for a in kept)
+    positions = math.prod(values.shape[a] for a in axes)
+    with np.errstate(all="ignore"):
+        if codes is None and positions < FEW:
+            compiled = (_compiled("in_order") if COMPILED and len(axes) == 1 and values.ndim <= 2
+                        and values.size >= IN_ORDER_COMPILED_FROM else None)
+            if compiled is not None:
+                # A view: one reduced axis, at most one kept; the width is explicit, since -1 is ambiguous when empty.
+                table = np.moveaxis(values, axes[0], 0).reshape(positions, math.prod(kept_shape))
+                result, present = compiled(table, op == "mean", na_rm)
+                if op == "sum" and min_count is not None:
+                    result = np.where(present >= min_count, result, np.float32(np.nan))
+                return result.reshape(kept_shape)
+            return _in_order(values, axes, kept_shape, op, na_rm, min_count)
+        table = np.transpose(values, axes + kept).reshape(positions, math.prod(kept_shape))
+        if codes is not None:
+            others = math.prod(values.shape[a] for a in axes[1:])
+            rows = np.asarray(codes) if others == 1 else np.repeat(np.asarray(codes), others)
+            if sizes is not None and others != 1:
+                sizes = np.asarray(sizes) * others
+            result = _settled(table, rows, groups, sizes, op, na_rm, min_count)
+            return result.reshape((groups, *kept_shape))
+        return _settled(table, None, 1, None, op, na_rm, min_count).reshape(kept_shape)
+
+
+def _in_order(values, axes, kept_shape, op, na_rm, min_count) -> np.ndarray:
+    """Few values per result: float64, added first to last along *axes*, rounded once.
+
+    Each position along the reduced axes is a view of the input, added in
+    place, so no copy is made whatever the layout; missing values are
+    counted only when ``na_rm`` or ``min_count`` needs them.
+    """
+    moved = np.moveaxis(values, axes, tuple(range(len(axes))))
+    total = np.zeros(kept_shape)
+    counting = na_rm or (op == "sum" and min_count is not None)
+    present = np.zeros(kept_shape, dtype=np.intp) if counting else None
+    for index in np.ndindex(moved.shape[:len(axes)]):
+        row = moved[index]
+        if counting:
+            missing = np.isnan(row)
+            present += ~missing
+            if na_rm:
+                row = np.where(missing, np.float32(0), row)
+        np.add(total, row, out=total)
+    terms = math.prod(values.shape[a] for a in axes)
+    return _finish(total, present, terms, op, na_rm, min_count)
+
+
+def _finish(total, present, terms, op, na_rm, min_count) -> np.ndarray:
+    if op == "mean":
+        np.divide(total, present if na_rm else terms, out=total)
+        return total.astype(np.float32)
+    result = total.astype(np.float32)
+    return np.where(present >= min_count, result, np.float32(np.nan)) if min_count is not None else result
+
+
+# ── Correctly rounded: an estimate, a bound, and exact sums where needed ────
+
+
+def _settled(table, rows, groups, sizes, op, na_rm, min_count) -> np.ndarray:
+    """Correctly rounded results, one row per group (one row in all when *rows* is None)."""
+    total, magnitude, present, values, terms, compensated = _estimate(table, rows, groups, sizes, na_rm)
+    counts = present if na_rm else values
+    result, sure = _certify(total, magnitude, terms, counts, op, compensated)
+    unsure = ~sure
+    for column in np.flatnonzero(unsure.any(axis=0)):
+        chosen = np.flatnonzero(unsure[:, column])
+        result[chosen, column] = _exact(table[:, column], rows, chosen, groups, op, na_rm)
+    if op == "sum" and min_count is not None:
+        result = np.where(present >= min_count, result, np.float32(np.nan))
+    return result
+
+
+def _estimate(table, rows, groups, sizes, na_rm):
+    """Float64 sums, sums of magnitudes, values present, values, and terms for the bound, per group and column.
+
+    The NumPy path adds chunks of positions (one ``np.bincount`` over
+    (chunk, group) bins, or ``np.add.reduceat`` without groups) and then the
+    chunk totals, so a result's error grows with the chunk length plus the
+    number of chunks; "terms" is that effective count, for the bound only.
+    """
+    positions, width = table.shape
+    chunks = max(1, min(math.isqrt(positions), _BINS // max(groups, 1)))
+    length = -(-positions // chunks) if positions else 0
+    if rows is None:
+        missing = np.isnan(table)
+        weights = np.where(missing, np.float32(0), table) if na_rm else table
+        if positions:
+            starts = np.arange(0, positions, length)
+            total = np.add.reduceat(weights, starts, axis=0, dtype=np.float64).sum(axis=0)[None]
+            magnitude = np.add.reduceat(np.abs(weights), starts, axis=0, dtype=np.float64).sum(axis=0)[None]
+        else:
+            total = magnitude = np.zeros((1, width))
+        present = (positions - missing.sum(axis=0))[None]
+        terms = np.full((1, width), min(positions, length + chunks))
+        return total, magnitude, present, np.full((1, width), positions), terms, False
+    if sizes is None:
+        sizes = np.bincount(rows, minlength=groups)
+    sizes = np.asarray(sizes)
+    kernel = _compiled("grouped_estimate") if COMPILED and table.size >= COMPILED_FROM else None
+    if kernel is not None:
+        total, magnitude, present = kernel(table, np.ascontiguousarray(rows, dtype=np.intp), groups, na_rm)
+        values = np.repeat(sizes[:, None], width, axis=1)
+        return total, magnitude, present, values, values, True
+    effective = np.minimum(sizes, length) + np.minimum(sizes, chunks)  # additions within a chunk, then of chunk totals
+    terms = np.repeat(np.minimum(sizes, effective)[:, None], width, axis=1)
+    key = rows if chunks == 1 else (np.arange(positions) // length) * groups + rows
+    bins = chunks * groups
+    total = np.empty((groups, width))
+    magnitude = np.empty((groups, width))
+    present = np.empty((groups, width), dtype=np.intp)
+    for column in range(width):
+        values = table[:, column]
+        missing = np.isnan(values)
+        anything_missing = bool(missing.any())
+        weights = np.where(missing, np.float32(0), values) if na_rm and anything_missing else values
+        total[:, column] = np.bincount(key, weights=weights, minlength=bins).reshape(chunks, groups).sum(axis=0)
+        magnitude[:, column] = np.bincount(key, weights=np.abs(weights), minlength=bins).reshape(chunks, groups).sum(axis=0)
+        present[:, column] = (sizes - np.bincount(rows, weights=missing, minlength=groups).astype(np.intp)
+                              if anything_missing else sizes)
+    return total, magnitude, present, np.repeat(sizes[:, None], width, axis=1), terms, False
+
+
+def _certify(total, magnitude, terms, counts, op, compensated):
+    """Results where the error bound proves the rounding, and where it does.
+
+    A float64 sum of n values, in any order, is within gamma(n) * sum|x| of
+    the exact sum, gamma(n) = n u / (1 - n u); a compensated one within
+    (6u + 4 (n u)^2) * sum|x|. Where both ends of the interval round to the
+    same float32, the exact value rounds there too.
+    """
+    n = terms.astype(np.float64)
+    gamma = n * _U / (1 - n * _U)
+    size = magnitude / (1 - gamma)  # the computed magnitude may itself be low by that factor
+    bound = (6 * _U + 4 * (n * _U) ** 2) * size if compensated else gamma * size
+    bound = bound * (1 + 8 * _U) + np.abs(total) * (2 * _U) + 1e-300  # the bound's and the ends' own rounding
+    if op == "mean":
+        centre = total / counts
+        bound = bound / counts * (1 + 4 * _U) + np.abs(centre) * (4 * _U)
+    else:
+        centre = total
+    low, high = (centre - bound).astype(np.float32), (centre + bound).astype(np.float32)
+    sure = (low == high) & np.isfinite(bound) & np.isfinite(centre)
+    if op == "mean":
+        sure &= counts > 0
+    return high, sure
+
+
+def _exact(values, rows, chosen, groups, op, na_rm) -> np.ndarray:
+    """Correctly rounded results for groups *chosen*, from exact sums of their values."""
+    if rows is None:
+        part, codes, count = values, np.zeros(len(values), dtype=np.intp), 1
+    else:
+        remap = np.full(groups, -1, dtype=np.intp)
+        remap[chosen] = np.arange(len(chosen))
+        codes = remap[rows]
+        keep = codes >= 0
+        part, codes, count = values[keep], codes[keep], len(chosen)
+    totals, present, special = _exact_sums(part, codes, count, na_rm)
+    out = np.empty(count, dtype=np.float32)
+    for k in range(count):
+        if special[k] is not None:
+            out[k] = special[k]
+        elif op == "sum":
+            out[k] = _round32(totals[k])
+        else:
+            out[k] = _round32(totals[k] / present[k]) if present[k] else np.float32(np.nan)
+    if op == "mean":
+        out[(present == 0) & np.array([s is None for s in special])] = np.nan
+    return out
+
+
+def _exact_sums(values, codes, count, na_rm):
+    """Exact sums as Fractions, values present, and NaN or infinity where they decide the result.
+
+    A float32 is M * 2**(e - 150) with M a signed integer below 2**24 and e
+    from 1 to 254. Integers M with the same e add exactly in float64 for
+    fewer than 2**29 values, so they are summed per group and exponent with
+    ``np.bincount``, and the few totals per group combined in Python integers.
+    """
+    bits = values.view(np.uint32)
+    exponent = ((bits >> 23) & 0xFF).astype(np.intp)
+    nan = np.isnan(values)
+    infinite = np.isinf(values)
+    finite = ~(nan | infinite)
+    mantissa = (bits & 0x7FFFFF).astype(np.int64) | np.where(exponent > 0, 1 << 23, 0)
+    mantissa = np.where(bits >> 31, -mantissa, mantissa)
+    exponent = np.maximum(exponent, 1)
+    present = np.bincount(codes, minlength=count) - np.bincount(codes, weights=nan, minlength=count).astype(np.intp)
+    has_nan = np.bincount(codes, weights=nan, minlength=count) > 0
+    plus = np.bincount(codes, weights=values == np.inf, minlength=count) > 0
+    minus = np.bincount(codes, weights=values == -np.inf, minlength=count) > 0
+    totals = [Fraction(0)] * count
+    if finite.any():
+        low, high = int(exponent[finite].min()), int(exponent[finite].max())
+        width = high - low + 1
+        key = codes[finite] * width + (exponent[finite] - low)
+        weights = mantissa[finite].astype(np.float64)
+        buckets = np.zeros(count * width, dtype=np.int64)
+        chunk = 1 << 28  # each bucket sum stays below 2**52, so float64 holds it exactly
+        for start in range(0, len(key), chunk):
+            buckets += np.bincount(key[start:start + chunk], weights=weights[start:start + chunk],
+                                   minlength=count * width).astype(np.int64)
+        buckets = buckets.reshape(count, width)
+        scale = Fraction(2) ** (low - 150)
+        for k in range(count):
+            row = buckets[k]
+            whole = sum(int(row[j]) << int(j) for j in np.flatnonzero(row))  # Python integers: shifts beyond 63
+            totals[k] = whole * scale
+    special = [None] * count
+    for k in range(count):
+        if (has_nan[k] and not na_rm) or (plus[k] and minus[k]):
+            special[k] = np.float32(np.nan)
+        elif plus[k] or minus[k]:
+            special[k] = np.float32(np.inf if plus[k] else -np.inf)
+    return totals, present, special
+
+
+def _round32(value: Fraction) -> np.float32:
+    """*value* correctly rounded to float32, ties to even."""
+    if value == 0:
+        return np.float32(0.0)
+    if abs(value) >= _MAX32 + Fraction(2) ** 103:  # half a step above the largest float32
+        return np.float32(math.inf if value > 0 else -math.inf)
+    guess = np.float32(float(value))  # float() rounds correctly; the cast can round a second time
+    best = guess
+    for candidate in (np.nextafter(guess, np.float32(-np.inf)), np.nextafter(guess, np.float32(np.inf))):
+        if not np.isfinite(candidate):
+            continue
+        gap, best_gap = abs(Fraction(float(candidate)) - value), abs(Fraction(float(best)) - value)
+        if gap < best_gap or (gap == best_gap and int(candidate.view(np.uint32)) % 2 == 0):
+            best = candidate
+    return np.float32(best)
+
+
+# ── The optional compiled kernel ────────────────────────────────────────────
+
+_KERNELS: dict = {}
+
+
+def _compiled(name: str):
+    """A compiled kernel from ``_compiled`` when Numba is installed (``labelarray[fast]``), else None."""
+    if name not in _KERNELS:
+        try:
+            from labelarray import _compiled as module
+        except ImportError:
+            _KERNELS[name] = None
+        else:
+            _KERNELS[name] = getattr(module, name)
+    return _KERNELS[name]