labelarray 0.1.0__py3-none-any.whl

labelarray/__init__.py

@@ -0,0 +1,82 @@
+"""labelarray: labelled N-D arrays in NumPy, with exact labels and reproducible reductions.
+
+The public API:
+
+- ``Array``: a NumPy array with named axes, exact labels, attributes, and a
+  name; NumPy's ufuncs, ``np.where``, and Python's operators broadcast by axis
+  name. ``Collection``: arrays sharing axes, one label array per axis.
+  ``concat``, ``align``, and ``broadcast`` work on several arrays (``array``,
+  ``collection``).
+- The exact label rule: ``kind``, ``equal``, ``compare``, ``strict_subset``,
+  ``exact_cast``, ``lossy_join_type`` (``labels``); label indexes and their
+  factory, ``index_for`` and ``register_index`` (``index``).
+- Grouping: ``Grouping``, with ``reduce``, ``counts``, and ``broadcast``
+  applying it to an array (``grouped``); ``factorize`` and the key transforms
+  ``Bins``, ``Duration``, ``Round``, and ``GridCells`` (``transforms``).
+- Numbers: float32 sums and means correctly rounded (``sums``) and the
+  contraction behind ``Array.dot`` (``contract``).
+- Errors: ``LabelArrayError`` and its ``LabelError``, ``AlignError``,
+  ``GroupError``, and ``ShapeError`` (``errors``).
+"""
+
+from labelarray.__version__ import __version__
+from labelarray.array import Array, align, broadcast, concat, label_index
+from labelarray.collection import Collection
+from labelarray.errors import (
+    AlignError,
+    GroupError,
+    LabelArrayError,
+    LabelError,
+    ShapeError,
+)
+from labelarray.grouped import Grouping
+from labelarray.index import (
+    GridIndex,
+    LabelIndex,
+    SortedIndex,
+    SortOnceIndex,
+    index_for,
+    register_index,
+)
+from labelarray.labels import (
+    compare,
+    equal,
+    exact_cast,
+    kind,
+    lossy_join_type,
+    strict_subset,
+)
+from labelarray.transforms import Bins, Duration, GridCells, Round, factorize
+
+__all__ = [
+    "AlignError",
+    "Array",
+    "Bins",
+    "Collection",
+    "Duration",
+    "GridCells",
+    "GridIndex",
+    "GroupError",
+    "Grouping",
+    "LabelArrayError",
+    "LabelError",
+    "LabelIndex",
+    "Round",
+    "ShapeError",
+    "SortOnceIndex",
+    "SortedIndex",
+    "__version__",
+    "align",
+    "broadcast",
+    "compare",
+    "concat",
+    "equal",
+    "exact_cast",
+    "factorize",
+    "index_for",
+    "kind",
+    "label_index",
+    "lossy_join_type",
+    "register_index",
+    "strict_subset",
+]

labelarray/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

labelarray/_compiled.py

@@ -0,0 +1,101 @@
+"""The compiled grouped estimate for ``sums``, used when Numba is installed (``labelarray[fast]``).
+
+One parallel pass over the values computes, per group and column, a
+compensated float64 sum (Neumaier's improvement of Kahan's method), the sum
+of magnitudes, and the values present. Each thread adds its share of the
+positions; the threads' compensated sums are then added with compensation
+too. The result is within (6u + 4 (n u)^2) * sum|x| of the exact sum, so
+``sums._certify`` settles nearly every result even under heavy cancellation,
+and the results are the same float32 values the NumPy path gives.
+"""
+
+from __future__ import annotations
+
+import numba as nb
+import numpy as np
+
+
+@nb.njit(parallel=True, cache=True, nogil=True)
+def _estimate(table, rows, groups, na_rm, threads):  # pragma: no cover - compiled
+    positions, width = table.shape
+    share = (positions + threads - 1) // threads
+    sums = np.zeros((threads, groups, width))
+    carries = np.zeros((threads, groups, width))
+    magnitudes = np.zeros((threads, groups, width))
+    present = np.zeros((threads, groups, width), dtype=np.intp)
+    for thread in nb.prange(threads):
+        for position in range(thread * share, min(positions, (thread + 1) * share)):
+            group = rows[position]
+            for column in range(width):
+                value = np.float64(table[position, column])
+                if np.isnan(value):  # skipped with na_rm, otherwise it makes the sum NaN
+                    if na_rm:
+                        continue
+                else:
+                    present[thread, group, column] += 1
+                total = sums[thread, group, column]
+                added = total + value
+                if abs(total) >= abs(value):
+                    carries[thread, group, column] += (total - added) + value
+                else:
+                    carries[thread, group, column] += (value - added) + total
+                sums[thread, group, column] = added
+                magnitudes[thread, group, column] += abs(value)
+    total = np.zeros((groups, width))
+    carry = np.zeros((groups, width))
+    magnitude = np.zeros((groups, width))
+    counted = np.zeros((groups, width), dtype=np.intp)
+    for thread in range(threads):
+        for group in range(groups):
+            for column in range(width):
+                for value in (sums[thread, group, column], carries[thread, group, column]):
+                    running = total[group, column]
+                    added = running + value
+                    if abs(running) >= abs(value):
+                        carry[group, column] += (running - added) + value
+                    else:
+                        carry[group, column] += (value - added) + running
+                    total[group, column] = added
+                magnitude[group, column] += magnitudes[thread, group, column]
+                counted[group, column] += present[thread, group, column]
+    return total + carry, magnitude, counted
+
+
+def grouped_estimate(table: np.ndarray, rows: np.ndarray, groups: int, na_rm: bool):
+    """Compensated float64 sums, sums of magnitudes, and values present, per group and column."""
+    # The thread count is passed in: reading it inside the compiled function would stop Numba caching it.
+    return _estimate(table, rows, groups, na_rm, nb.get_num_threads())
+
+
+@nb.njit(parallel=True, cache=True, nogil=True, error_model="numpy")
+def _in_order(table, mean, na_rm):  # pragma: no cover - compiled
+    positions, width = table.shape
+    out = np.empty(width, dtype=np.float32)
+    present = np.zeros(width, dtype=np.intp)
+    for column in nb.prange(width):
+        total = 0.0
+        counted = 0
+        for position in range(positions):
+            value = np.float64(table[position, column])
+            if np.isnan(value):
+                if na_rm:
+                    value = 0.0
+            else:
+                counted += 1
+            total += value
+        if mean:
+            total = total / (counted if na_rm else positions)
+        out[column] = np.float32(total)
+        present[column] = counted
+    return out, present
+
+
+def in_order(table: np.ndarray, mean: bool, na_rm: bool):
+    """Few values per result, as ``sums._in_order`` adds them, in one parallel pass.
+
+    Each result adds the values of its column first to last in float64,
+    starting from 0.0, with NaN as 0.0 under ``na_rm``; a mean divides in
+    float64; the result is rounded once to float32. These are the operations
+    and the order of the NumPy path, so the bits are the same.
+    """
+    return _in_order(table, mean, na_rm)

labelarray/align.py

@@ -0,0 +1,40 @@
+"""Exact alignment of one axis's labels (exact is the only mode).
+
+Labels on a shared axis must match exactly. The same labels in another
+order are matched by label; different labels, or repeated labels in another
+order, cannot be paired and are an ``AlignError``. There is no looser mode
+(xarray's outer join): a mode can be added later, a changed default cannot.
+
+This module needs NumPy only.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Hashable
+from typing import Any
+
+import numpy as np
+
+from labelarray.errors import AlignError
+from labelarray.index import LabelIndex, index_for
+from labelarray.labels import compare
+
+
+def order_like(reference: Any, labels: Any, dim: Hashable = None, *,
+               index: Callable[..., LabelIndex] = index_for) -> np.ndarray | None:
+    """The positions that put *labels* in *reference*'s order, or None when they are already the same.
+
+    *index* gives a label array's index; a caller that keeps indexes on its
+    label arrays passes its own, so they are built once.
+    """
+    state, only_reference, only_labels = compare(reference, labels, "align", dim)
+    if state == "same":
+        return None
+    if state == "reordered":
+        ours = index(labels, "align", dim)
+        if not (ours.unique and index(reference, "align", dim).unique):
+            raise AlignError(f"{dim} has repeated labels in a different order on two operands; "
+                             "repeated labels cannot be matched one to one")
+        return ours.get_indexer(reference)
+    raise AlignError(f"{dim} labels differ between operands: {only_labels:,} only in one, "
+                     f"{only_reference:,} only in the other; join them first")