dataeval 1.1.0rc6__tar.gz → 1.1.2__tar.gz

{dataeval-1.1.0rc6 → dataeval-1.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dataeval
-Version: 1.1.0rc6
+Version: 1.1.2
 Summary: DataEval provides a simple interface to characterize image data and its impact on model performance across classification and object-detection tasks
 Project-URL: Homepage, https://dataeval.ai/
 Project-URL: Repository, https://github.com/aria-ml/dataeval/
@@ -35,23 +35,26 @@ Requires-Dist: xxhash>=3.4
 Provides-Extra: cpu
 Requires-Dist: torch>=2.2.0; extra == 'cpu'
 Requires-Dist: torchvision>=0.17.0; extra == 'cpu'
-Provides-Extra: cu118
-Requires-Dist: torch>=2.2.0; extra == 'cu118'
-Requires-Dist: torchvision>=0.17.0; extra == 'cu118'
-Provides-Extra: cu128
-Requires-Dist: torch>=2.2.0; extra == 'cu128'
-Requires-Dist: torchvision>=0.17.0; extra == 'cu128'
+Provides-Extra: cu126
+Requires-Dist: torch>=2.2.0; extra == 'cu126'
+Requires-Dist: torchvision>=0.17.0; extra == 'cu126'
+Provides-Extra: cu130
+Requires-Dist: torch>=2.2.0; extra == 'cu130'
+Requires-Dist: torchvision>=0.17.0; extra == 'cu130'
 Provides-Extra: litert
 Requires-Dist: ai-edge-litert>=2.0; (python_version <= '3.14') and extra == 'litert'
 Provides-Extra: onnx
 Requires-Dist: onnx>=1.14.0; extra == 'onnx'
-Requires-Dist: onnxruntime<1.24,>=1.15.0; (python_version == '3.10') and extra == 'onnx'
-Requires-Dist: onnxruntime>=1.15.0; (python_version >= '3.11') and extra == 'onnx'
-Provides-Extra: onnx-gpu
-Requires-Dist: onnx>=1.14.0; extra == 'onnx-gpu'
-Requires-Dist: onnxruntime-gpu<1.24,>=1.15.0; (python_version == '3.10') and extra == 'onnx-gpu'
-Requires-Dist: onnxruntime-gpu<1.27,>=1.15.0; (python_version >= '3.11') and extra == 'onnx-gpu'
-Requires-Dist: onnxruntime-gpu<1.27,>=1.24; (python_version >= '3.14') and extra == 'onnx-gpu'
+Requires-Dist: onnxruntime>=1.17; extra == 'onnx'
+Provides-Extra: onnx-cu126
+Requires-Dist: onnx>=1.14.0; extra == 'onnx-cu126'
+Requires-Dist: onnxruntime-gpu<1.24,>=1.17; (python_version == '3.10' and extra != 'onnx-cu130') and extra == 'onnx-cu126'
+Requires-Dist: onnxruntime-gpu<1.27,>=1.17; (python_version >= '3.11' and extra != 'onnx-cu130') and extra == 'onnx-cu126'
+Requires-Dist: onnxruntime-gpu<1.27,>=1.24; (python_version >= '3.14' and extra != 'onnx-cu130') and extra == 'onnx-cu126'
+Provides-Extra: onnx-cu130
+Requires-Dist: onnx>=1.14.0; extra == 'onnx-cu130'
+Requires-Dist: onnxruntime-gpu>=1.27; (python_version >= '3.11' and extra != 'onnx-cu126') and extra == 'onnx-cu130'
+Requires-Dist: onnxruntime>=1.17; (python_version == '3.10' and extra != 'onnx-cu126') and extra == 'onnx-cu130'
 Provides-Extra: ontology
 Requires-Dist: rdflib>=7.0; extra == 'ontology'
 Provides-Extra: opencv
@@ -143,8 +146,8 @@ variant, install `torch` from that variant's wheel index **first**, then install
 DataEval — it accepts the build already present in the environment:
 
 ```bash
-# 1. Pick your PyTorch build (cpu / cu118 / cu128)
-pip install torch --index-url https://download.pytorch.org/whl/cu128
+# 1. Pick your PyTorch build (cpu / cu126 / cu130)
+pip install torch --index-url https://download.pytorch.org/whl/cu130
 
 # 2. Install DataEval
 pip install dataeval
@@ -159,7 +162,7 @@ pip install dataeval
 > `pip install dataeval --extra-index-url https://download.pytorch.org/whl/cpu`
 > does work, because the CPU index tracks the latest release.)
 >
-> **The `cpu` / `cu118` / `cu128` extras do not select a PyTorch variant under
+> **The `cpu` / `cu126` / `cu130` extras do not select a PyTorch variant under
 > pip.** All three declare the same requirements (`torch`, `torchvision`); what
 > distinguishes them is `[tool.uv.sources]`, which routes those packages to the
 > right wheel index. That is project metadata applied by uv when resolving **from
@@ -175,7 +178,7 @@ transform across a dataset view. If you want that class, install torchvision
 yourself, from the **same index as your torch build**:
 
 ```bash
-pip install torchvision --index-url https://download.pytorch.org/whl/cu128
+pip install torchvision --index-url https://download.pytorch.org/whl/cu130
 ```
 
 > **Do not mix indexes.** A `torchvision` from PyPI alongside a torch installed
@@ -189,7 +192,7 @@ pip install torchvision --index-url https://download.pytorch.org/whl/cu128
 ### **Installing with uv**
 
 ```bash
-uv pip install dataeval --torch-backend cpu   # or cu118 / cu128 / auto
+uv pip install dataeval --torch-backend cpu   # or cu126 / cu130 / auto
 ```
 
 ### **Installing with conda**

{dataeval-1.1.0rc6 → dataeval-1.1.2}/README.md

@@ -83,8 +83,8 @@ variant, install `torch` from that variant's wheel index **first**, then install
 DataEval — it accepts the build already present in the environment:
 
 ```bash
-# 1. Pick your PyTorch build (cpu / cu118 / cu128)
-pip install torch --index-url https://download.pytorch.org/whl/cu128
+# 1. Pick your PyTorch build (cpu / cu126 / cu130)
+pip install torch --index-url https://download.pytorch.org/whl/cu130
 
 # 2. Install DataEval
 pip install dataeval
@@ -99,7 +99,7 @@ pip install dataeval
 > `pip install dataeval --extra-index-url https://download.pytorch.org/whl/cpu`
 > does work, because the CPU index tracks the latest release.)
 >
-> **The `cpu` / `cu118` / `cu128` extras do not select a PyTorch variant under
+> **The `cpu` / `cu126` / `cu130` extras do not select a PyTorch variant under
 > pip.** All three declare the same requirements (`torch`, `torchvision`); what
 > distinguishes them is `[tool.uv.sources]`, which routes those packages to the
 > right wheel index. That is project metadata applied by uv when resolving **from
@@ -115,7 +115,7 @@ transform across a dataset view. If you want that class, install torchvision
 yourself, from the **same index as your torch build**:
 
 ```bash
-pip install torchvision --index-url https://download.pytorch.org/whl/cu128
+pip install torchvision --index-url https://download.pytorch.org/whl/cu130
 ```
 
 > **Do not mix indexes.** A `torchvision` from PyPI alongside a torch installed
@@ -129,7 +129,7 @@ pip install torchvision --index-url https://download.pytorch.org/whl/cu128
 ### **Installing with uv**
 
 ```bash
-uv pip install dataeval --torch-backend cpu   # or cu118 / cu128 / auto
+uv pip install dataeval --torch-backend cpu   # or cu126 / cu130 / auto
 ```
 
 ### **Installing with conda**

{dataeval-1.1.0rc6 → dataeval-1.1.2}/pyproject.toml

@@ -47,20 +47,24 @@ dependencies = [
 
 [project.optional-dependencies]
 cpu = ["torch>=2.2.0", "torchvision>=0.17.0"]
-cu118 = ["torch>=2.2.0", "torchvision>=0.17.0"]
-cu128 = ["torch>=2.2.0", "torchvision>=0.17.0"]
+cu126 = ["torch>=2.2.0", "torchvision>=0.17.0"]
+cu130 = ["torch>=2.2.0", "torchvision>=0.17.0"]
 litert = ["ai-edge-litert>=2.0; python_version <= '3.14'"]
 opencv = ["opencv-python-headless>=4.8.0"]
 onnx = [
   "onnx>=1.14.0",
-  "onnxruntime>=1.15.0,<1.24; python_version == '3.10'",
-  "onnxruntime>=1.15.0; python_version >= '3.11'",
+  "onnxruntime>=1.17",
 ]
-onnx-gpu = [
+onnx-cu126 = [
   "onnx>=1.14.0",
-  "onnxruntime-gpu>=1.15.0,<1.24; python_version == '3.10'",
-  "onnxruntime-gpu>=1.15.0,<1.27; python_version >= '3.11'",  # 1.27+ requires CUDA 13.0
-  "onnxruntime-gpu>=1.24,<1.27; python_version >= '3.14'",  # 1.24+ for cp314 wheels
+  "onnxruntime-gpu>=1.17,<1.24; python_version == '3.10' and extra != 'onnx-cu130'",
+  "onnxruntime-gpu>=1.17,<1.27; python_version >= '3.11' and extra != 'onnx-cu130'",  # 1.27+ requires CUDA 13.0
+  "onnxruntime-gpu>=1.24,<1.27; python_version >= '3.14' and extra != 'onnx-cu130'",  # 1.24+ for cp314 wheels
+]
+onnx-cu130 = [
+  "onnx>=1.14.0",
+  "onnxruntime>=1.17; python_version == '3.10' and extra != 'onnx-cu126'",  # CUDA 13.0 is not supported on Python 3.10
+  "onnxruntime-gpu>=1.27; python_version >= '3.11' and extra != 'onnx-cu126'",
 ]
 ontology = ["rdflib>=7.0"]
 
@@ -106,12 +110,13 @@ docsync = [
 test = [
   "coverage[toml]>=7.6",
   "filelock>=3.20.3",
-  "onnx>=1.14.0",
-  "onnxscript>=0.6.0",
   "pytest>=8.3",
   "pytest-cov>=6.1",
   "pytest-xdist>=3.6.1",
-  "rdflib>=7.0",
+]
+test-onnx = [
+  { include-group = "test" },
+  "onnxscript>=0.6.0",
 ]
 verify = [
   "pytest>=8.3",
@@ -168,7 +173,7 @@ security = [  # keep in sync with [tool.uv.constraint-dependencies]
 dev = [
   { include-group = "base" },
   { include-group = "lint" },
-  { include-group = "test" },
+  { include-group = "test-onnx" },
   { include-group = "type" },
   { include-group = "docs" },
   "nox>=2025.5.1",
@@ -181,8 +186,13 @@ dev = [
 conflicts = [
   [
     { extra = "cpu" },
-    { extra = "cu118" },
-    { extra = "cu128" },
+    { extra = "cu126" },
+    { extra = "cu130" },
+  ],
+  [
+    { extra = "onnx" },
+    { extra = "onnx-cu126" },
+    { extra = "onnx-cu130" },
   ],
 ]
 constraint-dependencies = [
@@ -208,25 +218,25 @@ url = "https://download.pytorch.org/whl/cpu"
 explicit = true
 
 [[tool.uv.index]]
-name = "pytorch-cu118"
-url = "https://download.pytorch.org/whl/cu118"
+name = "pytorch-cu126"
+url = "https://download.pytorch.org/whl/cu126"
 explicit = true
 
 [[tool.uv.index]]
-name = "pytorch-cu128"
-url = "https://download.pytorch.org/whl/cu128"
+name = "pytorch-cu130"
+url = "https://download.pytorch.org/whl/cu130"
 explicit = true
 
 [tool.uv.sources]
 torch = [
   { index = "pytorch-cpu", extra = "cpu" },
-  { index = "pytorch-cu118", extra = "cu118" },
-  { index = "pytorch-cu128", extra = "cu128" },
+  { index = "pytorch-cu126", extra = "cu126" },
+  { index = "pytorch-cu130", extra = "cu130" },
 ]
 torchvision = [
   { index = "pytorch-cpu", extra = "cpu" },
-  { index = "pytorch-cu118", extra = "cu118" },
-  { index = "pytorch-cu128", extra = "cu128" },
+  { index = "pytorch-cu126", extra = "cu126" },
+  { index = "pytorch-cu130", extra = "cu130" },
 ]
 
 [tool.uv.extra-build-dependencies]
@@ -242,6 +252,7 @@ priority = "supplemental"
 
 [tool.poetry.dependencies]
 torch = { version = ">=2.2.0", source = "pytorch-cpu" }
+torchvision = { version = ">=0.17.0", source = "pytorch-cpu" }
 
 [tool.hatch.build.targets.sdist]
 include = ["src/dataeval"]
@@ -264,12 +275,16 @@ vcs = "git"
 style = "pep440"
 pattern = "^v?(?P<base>\\d+\\.\\d+\\.\\d+)"
 
+[tool.pyproject2conda]
+# maite is only published on conda-forge; the defaults channel cannot resolve it.
+channels = ["conda-forge"]
+
 [tool.pyproject2conda.dependencies]
 numpy = { skip = true, packages = "numpy>=1.24.2" }
 scikit-learn = { skip = true, packages = "scikit-learn>=1.5.0" }
 scipy = { skip = true, packages = "scipy>=1.10.0" }
 torch = { pip = true }  # PyTorch is no longer maintained on conda-forge
-xxhash = { skip = true, packages = "python-xxhash>=3.3" }
+xxhash = { skip = true, packages = "python-xxhash>=3.4" }
 
 [tool.pyright]
 include = ["src", "tests", "verification", "docs/source/notebooks"]
@@ -312,7 +327,12 @@ omit = ["src/dataeval/_version.py"]
 exclude_also = [
   "raise NotImplementedError",
   ": \\.\\.\\.",
-  "if TYPE_CHECKING:"
+  "if TYPE_CHECKING:",
+  # Debug reprs carry no logic worth asserting on, and pinning their exact text in a
+  # test makes the string harder to improve than it is worth. coverage.py documents
+  # `def __repr__` as a canonical exclusion.
+  "def __repr__",
+  "def __str__",
 ]
 include = ["*/src/dataeval/*"]
 omit = [
@@ -345,7 +365,12 @@ extend-include = ["*.ipynb"]
 select = ["F", "E", "W", "C90", "I", "N", "D", "UP", "YTT", "ANN", "S", "BLE", "B", "A",
           "COM", "C4", "T10", "ISC", "ICN", "PYI", "PT", "Q", "RSE", "RET", "SLF", "SIM",
           "TID252", "ARG", "FIX", "PD", "FLY", "NPY", "RUF027", "RUF100", "PERF"]
-ignore = ["ANN401", "C408", "C416", "COM812", "NPY002", "SLF001"]
+# ANN101/ANN102 were removed in Ruff 0.8, so ignoring them is inert and Ruff warns as much.
+# They stay because the JATIC program-standards Ruff config requires them verbatim in
+# lint.ignore, and verify_ruff_config.py matches against the parsed TOML -- a comment
+# cannot satisfy it, and the only other accepted spelling is bare "ANN", which would
+# disable every annotation rule.
+ignore = ["ANN101", "ANN102", "ANN401", "C408", "C416", "COM812", "NPY002", "SLF001"]
 fixable = ["ALL"]
 unfixable = []
 dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"

{dataeval-1.1.0rc6 → dataeval-1.1.2}/src/dataeval/_metadata/_columns.py

@@ -101,14 +101,38 @@ def split_by_dimensionality(
     return kept, [name for name in arrays if name not in kept]
 
 
+# The two suffixes binning appends, and the namespace they define between them. Named
+# rather than spelled inline because :func:`is_companion_name` has to answer for the
+# same characters these build with, and a suffix that drifted between the two would
+# reopen exactly the collision that function exists to close.
+BINNED_SUFFIX = "↕"
+DIGITIZED_SUFFIX = "#"
+COMPANION_SUFFIXES: tuple[str, ...] = (BINNED_SUFFIX, DIGITIZED_SUFFIX)
+
+
 def binned(name: str) -> str:
     """Name of the companion column holding ``name``'s bin indices."""
-    return f"{name}↕"
+    return f"{name}{BINNED_SUFFIX}"
 
 
 def digitized(name: str) -> str:
     """Name of the companion column holding ``name``'s category ordinals."""
-    return f"{name}#"
+    return f"{name}{DIGITIZED_SUFFIX}"
+
+
+def is_companion_name(name: str) -> bool:
+    """Whether ``name`` sits in the namespace binning writes its companion columns into.
+
+    Every reader that resolves a companion does it by construction — ``binned(col)`` and
+    ``digitized(col)`` over the columns actually present — so a *factor* holding one of
+    those names is indistinguishable from the companion of its stem. A column named
+    ``w#`` alongside a factor ``w`` makes ``Metadata._bin`` skip ``w`` as already binned,
+    makes ``_reset_bins`` and the serializer's ``_without_companions`` drop the caller's
+    values as derived, and leaves ``factor_names`` a name longer than ``factor_data`` is
+    wide. Reserving the namespace is what keeps all three honest, so this is consulted
+    wherever a factor is named — see ``safe_column_name`` in ``_structurers._reserved``.
+    """
+    return name.endswith(COMPANION_SUFFIXES)
 
 
 def to_col(name: str, info: FactorInfo, is_binned: bool = True) -> str:

{dataeval-1.1.0rc6 → dataeval-1.1.2}/src/dataeval/_metadata/_keyed.py

@@ -61,6 +61,11 @@ def _item_values(md: "Metadata", factors: Mapping[str, Any], rows: int, key: str
     ``track_stats`` describes a single sequence and says nothing about which, so a dataset
     holding exactly one item can supply the answer itself. A dataset holding several cannot:
     track ids restart per sequence, so a bare id names a row in every one of them.
+
+    Which item a value belongs to has to be *said*, whether the caller attaches every
+    sequence at once or one per call. Repeated calls fold into one column rather than
+    colliding — see ``Metadata._merge_keyed`` — but each still has to name the item its
+    keys are scoped to.
     """
     if _ITEM in factors:
         return np.asarray(factors[_ITEM], dtype=np.intp).reshape(-1)
@@ -70,8 +75,10 @@ def _item_values(md: "Metadata", factors: Mapping[str, Any], rows: int, key: str
     raise ValueError(
         f"key={key!r} matches on (item_index, {key}), and {key} restarts per item, so values "
         f"for a dataset with {len(items)} items have to say which item each belongs to. Add an "
-        f"'item_index' entry to the factors, or add one item's values per call. track_stats "
-        "describes one sequence at a time.",
+        f"'item_index' entry to the factors — one entry per value, naming the item that value's "
+        f"{key} is scoped to. track_stats describes one sequence at a time, so attaching a "
+        "dataset's worth of them means saying which sequence each result came from, whether "
+        "they go in one call or one call per sequence.",
     )
 
 
@@ -80,13 +87,17 @@ def resolve_keyed(
     factors: Mapping[str, Any],
     level: FactorLevel,
     key: str,
-) -> list[tuple[str, FactorLevel, pl.Series]]:
+) -> tuple[list[tuple[str, FactorLevel, pl.Series]], NDArray[np.bool_]]:
     """Place each factor on the rows whose ``(item_index, key)`` its values name.
 
     A row the incoming values do not name is null rather than absent, so the column still
     has one entry per row at ``level`` and every downstream reader — binning, projection,
     the flat frame — sees the shape it expects.
 
+    Which rows *were* named is returned alongside, because it is the difference between a
+    write that leaves the rest of the column alone and one that blanks it. Every factor in
+    a call is placed by the same keys, so one mask covers them all.
+
     Parameters
     ----------
     md : Metadata
@@ -103,6 +114,8 @@ def resolve_keyed(
     -------
     list[tuple[str, str, pl.Series]]
         One entry per remaining factor, already in the level's row order.
+    NDArray[np.bool_]
+        One flag per row at ``level``, True where the incoming keys named it.
 
     Raises
     ------
@@ -148,4 +161,7 @@ def resolve_keyed(
     source = {pair: position for position, pair in enumerate(incoming)}
     wanted = zip(frame["item_index"].to_list(), frame[key].to_list(), strict=True)
     positions = np.fromiter((source.get(pair, -1) for pair in wanted), dtype=np.intp, count=frame.height)
-    return [(name, level, gather_nulling(name, values, positions)) for name, values in payload.items()]
+    placed: list[tuple[str, FactorLevel, pl.Series]] = [
+        (name, level, gather_nulling(name, values, positions)) for name, values in payload.items()
+    ]
+    return placed, positions >= 0

{dataeval-1.1.0rc6 → dataeval-1.1.2}/src/dataeval/_metadata/_metadata.py

@@ -66,6 +66,7 @@ from dataeval.core._bin import (
     level_budget,
 )
 from dataeval.core._compute_stats import StatsResult
+from dataeval.core._track_stats import TrackStatsResult
 from dataeval.exceptions import NotFittedError, ShapeMismatchError
 from dataeval.protocols import (
     AnnotatedDataset,
@@ -1476,7 +1477,7 @@ class Metadata(DeprecatedMetadataAPI, Array, FeatureExtractor):
         -------
         Metadata
             A copy whose :attr:`view` is ``level``, sharing this instance's structuring
-            and binning work. The original is untouched.
+            and binning work.
 
         Raises
         ------
@@ -1490,6 +1491,14 @@ class Metadata(DeprecatedMetadataAPI, Array, FeatureExtractor):
         the metadata is being handed to an evaluator, so that two evaluators can read
         two levels of the same dataset at once.
 
+        The original reports every value it reported before, but it is not left alone:
+        structuring and binning run on it here if they have not run already, so that the
+        copy shares that work instead of repeating it on a store of its own. Binning adds
+        companion columns and bins each factor at its own level, so nothing readable
+        moves — what moves is *when*. A warning a factor would have raised at the copy's
+        first factor access is raised at this call instead, and a binning configuration
+        that cannot be applied fails here rather than there.
+
         Examples
         --------
         >>> metadata = Metadata(dataset)
@@ -1501,6 +1510,7 @@ class Metadata(DeprecatedMetadataAPI, Array, FeatureExtractor):
         50
         """
         self._structure()
+        self._bin()
         resolved = self._resolve_level(level)
 
         view = copy.copy(self)
@@ -2059,10 +2069,25 @@ class Metadata(DeprecatedMetadataAPI, Array, FeatureExtractor):
         -------
         pl.DataFrame
             DataFrame with columns for level, item_index, target_index, class_label,
-            scores, bounding boxes (when applicable), a ``level`` tag naming the
+            score, bounding boxes (when applicable), a ``level`` tag naming the
             level each row belongs to, that level's own key columns, and all
             processed metadata factors.
 
+            ``score`` holds whatever layout the dataset's targets carried: one
+            confidence per labelled row, or a per-class array as wide as the
+            vocabulary that produced it.
+
+            .. note::
+                v1.2 reads ``score`` down to one ``Float32`` per row — the row's
+                confidence in its **own** class — and spells an unreadable one as
+                null. A per-class array's width is a property of the dataset's class
+                count, which is why two datasets with different vocabularies cannot
+                be stacked into one frame today. Code recovering per-class
+                probabilities from this column should read them from the target
+                instead. :class:`~dataeval.data.Relabel` takes
+                ``reduce_detection_scores`` to adopt the new column shape now, or to
+                keep this one through v1.2.
+
         See Also
         --------
         :meth:`~dataeval.Metadata.rows_at` : Filter to any level
@@ -2086,6 +2111,7 @@ class Metadata(DeprecatedMetadataAPI, Array, FeatureExtractor):
         still — neither goes through this.
         """
         self._structure()
+        self._bin()
         if self._flat is None:
             self._flat = self._store.flat()
         return self._flat
@@ -2733,6 +2759,7 @@ class Metadata(DeprecatedMetadataAPI, Array, FeatureExtractor):
         50
         """
         self._structure()
+        self._bin()
         return self._store.resolve(self._resolve_level(level))
 
     def _empty_projection(self, dtype: Any) -> NDArray[Any]:
@@ -3462,17 +3489,63 @@ class Metadata(DeprecatedMetadataAPI, Array, FeatureExtractor):
         self._announce_derived_encodings(factor_info)
         self._announce_fit(factor_info)
 
+    def _merge_keyed(
+        self,
+        name: str,
+        level: FactorLevel,
+        values: Any,
+        named: NDArray[np.bool_],
+        overwrite: bool,
+    ) -> tuple[str, pl.Series] | None:
+        """Fold a keyed write into a column of the same name already held at that level.
+
+        A keyed write names *rows*. Reaching rows that no earlier write reached is not a
+        name collision even though the column exists — it is the rest of the same column
+        arriving. Attaching per-sequence results one item at a time has exactly that
+        shape, and :func:`~dataeval.core.track_stats` describes one sequence at a time, so
+        it is the shape a caller naturally writes. Treating it as a collision instead
+        leaves two half-null columns under two names and says nothing about it.
+
+        Returns
+        -------
+        tuple[str, pl.Series] or None
+            The column to write and its merged values, or None when there is nothing to
+            fold into or the write collides for real.
+
+        Notes
+        -----
+        None comes back in two cases. The level holds no such factor, so this is a first
+        write and there is nothing to merge; or a row this write names already holds a
+        value while `overwrite` is False, which is two values for one row and so a real
+        collision — left to :meth:`_resolve_factor_name` to rename, like any other.
+
+        Under ``overwrite=True`` the named rows are replaced and the rest are kept, rather
+        than the whole column being replaced. Rows this write does not name are not rows
+        it says anything about.
+        """
+        safe = safe_column_name(name)
+        if safe not in self._factors_by_level.get(level, ()):
+            return None
+        existing = self._store.frame(level)[safe]
+        written = pl.Series(named)
+        if not overwrite and existing.filter(written).is_not_null().any():
+            return None
+        return safe, to_series(safe, values).zip_with(written, existing)
+
     def _resolve_factor_name(self, name: str, taken: set[str], overwrite: bool, append_string: str) -> str:
         """Pick the dataframe column a new factor should be written to.
 
         Reserved columns are load-bearing — ``level`` drives every level filter — so a
-        colliding factor is renamed rather than allowed to overwrite one.
+        colliding factor is renamed rather than allowed to overwrite one. So is one named
+        into the namespace binning writes its companions into, which ``taken`` cannot
+        speak for: it holds the columns present *now*, and a companion this factor would
+        be mistaken for may not have been written yet.
         """
         safe = safe_column_name(name)
         if safe != name:
             _logger.warning(
-                f"The factor name '{name}' collides with a reserved metadata column and has been "
-                f"stored as '{safe}' instead.",
+                f"The factor name '{name}' collides with a column name DataEval reserves and has "
+                f"been stored as '{safe}' instead.",
             )
 
         if safe not in taken or overwrite:
@@ -3658,7 +3731,7 @@ class Metadata(DeprecatedMetadataAPI, Array, FeatureExtractor):
 
     def add_factors(
         self,
-        factors: Mapping[str, Array1D[Any]] | StatsResult,
+        factors: Mapping[str, Array1D[Any]] | StatsResult | TrackStatsResult,
         level: FactorLevel | Literal["auto", "target", "combined", "image"] = "auto",
         overwrite: bool = False,
         append_string: str = "_added",
@@ -3724,6 +3797,9 @@ class Metadata(DeprecatedMetadataAPI, Array, FeatureExtractor):
         overwrite : bool, default False
             Whether to overwrite factors of the same name already present in the metadata.
             When False, a colliding factor is stored under a new name instead (see `append_string`).
+
+            Under `key` a collision is decided per row rather than per name, since a keyed
+            write names rows: see the `key` description below.
         append_string : str, default "_added"
             Suffix appended to a factor name that collides with an existing column when
             `overwrite` is False. If the suffixed name is also taken, an incrementing
@@ -3752,6 +3828,15 @@ class Metadata(DeprecatedMetadataAPI, Array, FeatureExtractor):
             ``track_ids``, and both that and the singular column name are accepted. A row
             no incoming key names is null, so the column still has one value per row.
 
+            Because a keyed write names rows, a second one adding a factor already present
+            **folds into that column** rather than colliding with it: rows the new keys
+            name take the new values, and rows they do not are left as they were. Attaching
+            one sequence per call therefore builds a single column across the whole dataset,
+            which is what ``track_stats`` invites, describing one sequence at a time. A name
+            collision is reported only when a row that already holds a value is named again,
+            and `overwrite` then decides it as it does anywhere else — replacing just the
+            named rows rather than the whole column.
+
         Raises
         ------
         ShapeMismatchError
@@ -3852,14 +3937,19 @@ class Metadata(DeprecatedMetadataAPI, Array, FeatureExtractor):
 
         taken = set(self._store.columns)
         resolved: list[_ResolvedFactor] = []
+        named: NDArray[np.bool_] | None = None
         if key is not None:
             # _reject_unusable_key has already refused "auto" and "combined", the only
             # spellings resolving to something other than a level, so this is one.
-            placed, vacuous = resolve_keyed(self, kept, cast("FactorLevel", resolved_level), key), []
+            (placed, named), vacuous = resolve_keyed(self, kept, cast("FactorLevel", resolved_level), key), []
         else:
             placed, vacuous = self._resolve_factor_levels(kept, resolved_level, source_index)
         for name, factor_level, values in placed:
-            col_name = self._resolve_factor_name(name, taken, overwrite, append_string)
+            merged = None if named is None else self._merge_keyed(name, factor_level, values, named, overwrite)
+            if merged is not None:
+                col_name, values = merged
+            else:
+                col_name = self._resolve_factor_name(name, taken, overwrite, append_string)
             taken.add(col_name)
             # One value per entity at the factor's own level: descendant rows read them by
             # the store's gather, so there is no expanded copy to build and no dtype to

{dataeval-1.1.0rc6 → dataeval-1.1.2}/src/dataeval/_metadata/_structurers/_reserved.py

@@ -4,7 +4,8 @@ A dataframe row carries two kinds of column. Factors are observations — anythi
 dataset or the caller measured — and are binned, correlated and reported on. The
 reserved columns are the row's own identity: the level it belongs to, the item it came
 from, and where it sits within each of its parents. A factor whose name would collide
-with one of them is renamed rather than allowed to overwrite it.
+with one of them is renamed rather than allowed to overwrite it, and so is one that
+would be taken for a companion column binning writes — see :func:`safe_column_name`.
 
 Sole producer of that layout: every structurer and
 :meth:`~dataeval.Metadata.from_factors` builds its blocks through
@@ -20,6 +21,7 @@ from typing import Any
 import numpy as np
 from numpy.typing import NDArray
 
+from dataeval._metadata._columns import is_companion_name
 from dataeval.types import FactorLevel
 
 # Columns the metadata dataframe has always carried. Retained verbatim because
@@ -149,7 +151,22 @@ def _as_column(values: Any) -> Sequence[Any] | NDArray[Any]:
 
 
 def safe_column_name(name: str) -> str:
-    """Prefix a factor name that would clobber a reserved dataframe column.
+    """Rename a factor that would be taken for a column DataEval owns.
+
+    Two namespaces are reserved, and a factor is moved out of either rather than allowed
+    to occupy it. :data:`RESERVED_COLUMNS` is the row's own identity, collided with head-on
+    and escaped by prefix. The companion namespace — anything ending in one of
+    ``COMPANION_SUFFIXES`` — is the one binning writes into, so a name lands in it by its
+    *tail* and has to be escaped there; see ``is_companion_name`` in ``_metadata._columns``
+    for what mistaking the two costs.
+
+    Sole entry point for both: every factor name reaches a frame through here, whether it
+    came from a dataset's metadata dictionaries, from
+    :meth:`~dataeval.Metadata.from_factors`, or from
+    :meth:`~dataeval.Metadata.add_factors` and :meth:`~dataeval.Metadata.agg` by way of
+    ``_resolve_factor_name``. Placed here rather than in each caller because the check has
+    to hold before anything is binned: a writer that resolves its name against the columns
+    currently present cannot see a companion binning has not written yet.
 
     Parameters
     ----------
@@ -159,7 +176,9 @@ def safe_column_name(name: str) -> str:
     Returns
     -------
     str
-        ``name`` unchanged, or ``metadata_<name>`` when it is in
-        :data:`RESERVED_COLUMNS`.
+        ``name`` unchanged; ``metadata_<name>`` when it is in :data:`RESERVED_COLUMNS`;
+        or ``<name>_metadata`` when it ends in a companion suffix.
     """
-    return f"metadata_{name}" if name in RESERVED_COLUMNS else name
+    if name in RESERVED_COLUMNS:
+        return f"metadata_{name}"
+    return f"{name}_metadata" if is_companion_name(name) else name