feat(io.ec_data): add EcData.validate + EcData.empty

Two shape-management helpers that consumers (geckopy's pipeline,
test fixtures) need on top of the raw dataclass:

- validate(): raise ValueError when per-rxn array lengths, per-enzyme
  array lengths, or the rxn_enz_mat shape drift from one another.
  Cheap; callable after each mutation in a builder pipeline.
- EcData.empty(n_rxns, n_enzymes, *, gecko_light=False): preallocate
  with the canonical sentinels (empty strings for the string fields,
  0 for kcat, NaN for mw/concs, empty CSR matrix). Used by builders
  that allocate up-front and fill row by row.

Both methods are shape-level operations, not algorithm, so they live
with the dataclass rather than on a downstream consumer.

Tests: 6 new EcData tests covering empty's sentinels, validate's
three drift paths (per-rxn length, per-enzyme length, coupling-matrix
shape), the empty -> validate round-trip, and the gecko_light flag
on empty.

Author: edkerk

src/raven_python/io/ec_data.py

@@ -107,6 +107,80 @@ def n_rxns(self) -> int:
     def n_enzymes(self) -> int:
         return len(self.enzymes)
 
+    def validate(self) -> None:
+        """Raise ``ValueError`` if internal field lengths are inconsistent.
+
+        Cheap sanity check: catches accidental drift between the per-rxn
+        arrays, the per-enzyme arrays, and the coupling matrix shape.
+        Called by pipeline stages after they mutate the data, and by the
+        YAML loader after construction.
+        """
+        n_r, n_e = self.n_rxns, self.n_enzymes
+
+        rxn_lengths = {
+            "kcat": len(self.kcat),
+            "source": len(self.source),
+            "notes": len(self.notes),
+            "eccodes": len(self.eccodes),
+        }
+        for name, length in rxn_lengths.items():
+            if length != n_r:
+                raise ValueError(
+                    f"ec.{name} has length {length}, expected {n_r} "
+                    f"(matching ec.rxns)"
+                )
+
+        # `ec.enzymes` itself is the reference length; check the remaining
+        # per-enzyme arrays against it.
+        enz_lengths = {
+            "genes": len(self.genes),
+            "mw": len(self.mw),
+            "sequence": len(self.sequence),
+            "concs": len(self.concs),
+        }
+        for name, length in enz_lengths.items():
+            if length != n_e:
+                raise ValueError(
+                    f"ec.{name} has length {length}, expected {n_e} "
+                    f"(matching ec.enzymes)"
+                )
+
+        if self.rxn_enz_mat.shape != (n_r, n_e):
+            raise ValueError(
+                f"ec.rxn_enz_mat has shape {self.rxn_enz_mat.shape}, "
+                f"expected ({n_r}, {n_e})"
+            )
+
+    @staticmethod
+    def empty(n_rxns: int, n_enzymes: int = 0, *,
+              gecko_light: bool = False) -> "EcData":
+        """Preallocate an ``EcData`` with the canonical sentinel values.
+
+        Per-rxn fields get empty strings; per-enzyme fields get empty
+        strings and NaN arrays. ``kcat`` starts at 0 (0 marks "no kcat
+        assigned"). ``mw`` and ``concs`` start at NaN, since their
+        physical default is "unknown" rather than zero.
+
+        Used by makeEcModel-style builders that allocate the structure
+        up-front, then fill it row by row.
+        """
+        return EcData(
+            gecko_light=gecko_light,
+            rxns=[""] * n_rxns,
+            kcat=np.zeros(n_rxns, dtype=float),
+            source=[""] * n_rxns,
+            notes=[""] * n_rxns,
+            eccodes=[""] * n_rxns,
+            genes=[""] * n_enzymes,
+            enzymes=[""] * n_enzymes,
+            mw=np.full(n_enzymes, np.nan, dtype=float),
+            sequence=[""] * n_enzymes,
+            concs=np.full(n_enzymes, np.nan, dtype=float),
+            rxn_enz_mat=sparse.lil_matrix(
+                (n_rxns, n_enzymes), dtype=float,
+            ).tocsr(),
+        )
+
 
 # --------------------------------------------------------------------------- #
 # Load

tests/test_io_yaml_ec_data.py

@@ -365,3 +365,50 @@ def test_model_from_yaml_data_mutates_in_place():
     assert "ec-rxns" not in doc
     assert "ec-enzymes" not in doc
     assert "gecko_light" not in doc
+
+
+# --------------------------------------------------------------------------- #
+# EcData.validate / EcData.empty
+# --------------------------------------------------------------------------- #
+
+def test_empty_has_canonical_sentinels():
+    """`EcData.empty(n, m)` preallocates with the documented sentinels."""
+    ec = EcData.empty(3, 2)
+    assert ec.n_rxns == 3
+    assert ec.n_enzymes == 2
+    assert ec.rxns == ["", "", ""]
+    assert (ec.kcat == 0).all()
+    assert np.isnan(ec.mw).all()
+    assert np.isnan(ec.concs).all()
+    assert ec.rxn_enz_mat.shape == (3, 2)
+    assert ec.rxn_enz_mat.nnz == 0
+
+
+def test_empty_round_trips_through_validate():
+    EcData.empty(5, 4).validate()  # must not raise
+
+
+def test_validate_catches_per_rxn_length_drift():
+    ec = EcData.empty(3, 2)
+    ec.kcat = np.array([1.0, 2.0])  # length 2, should be 3
+    with pytest.raises(ValueError, match="ec.kcat has length 2, expected 3"):
+        ec.validate()
+
+
+def test_validate_catches_per_enzyme_length_drift():
+    ec = EcData.empty(3, 2)
+    ec.mw = np.array([1.0])  # length 1, should be 2
+    with pytest.raises(ValueError, match="ec.mw has length 1, expected 2"):
+        ec.validate()
+
+
+def test_validate_catches_coupling_matrix_shape_drift():
+    ec = EcData.empty(3, 2)
+    ec.rxn_enz_mat = sparse.csr_matrix((3, 5), dtype=float)
+    with pytest.raises(ValueError, match=r"ec.rxn_enz_mat has shape \(3, 5\)"):
+        ec.validate()
+
+
+def test_empty_gecko_light_flag_propagates():
+    assert EcData.empty(1, 1, gecko_light=True).gecko_light is True
+    assert EcData.empty(1, 1).gecko_light is False