tablassert 9.1.0__tar.gz → 10.1.0__tar.gz

{tablassert-9.1.0 → tablassert-10.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tablassert
-Version: 9.1.0
+Version: 10.1.0
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research

{tablassert-9.1.0 → tablassert-10.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tablassert"
-version = "9.1.0"
+version = "10.1.0"
 description = "Extract knowledge assertions from tabular data into NCATS Translator-compliant KGX NDJSON — declaratively, with entity resolution and quality control built in."
 authors = [
     { name = "Skye Lane Goetz", email = "sgoetz@isbscience.org" }

{tablassert-9.1.0 → tablassert-10.1.0}/src/tablassert/agent.py

@@ -2172,6 +2172,11 @@ qualifier and evidence slot the specific class declared. build_and_audit reports
   description rather than emitted on the edge. `q_value`, `fold_change`, `z_score`, `beta` and
   similar are not association slots at all and are folded into `supporting_text`. Prefer
   `p_value`, `adjusted_p_value`, `effect_size`, `effect_type`, `has_evidence`.
+- MULTIVALUED slots (`has_evidence` and friends) take a real JSON array, never a joined string:
+  declare the annotation `{method: column, encoding: <letter>, split_by: "|"}` so each cell's
+  delimited text splits into its own per-row array. `split_by` is the ONLY multivalued encoding
+  — there is no literal-list method, and a scalar bound for a multivalued slot ships to consumers
+  as one unusable "a|b|c" blob.
 - `effect_size` / `effect_type` are deliberate Tablassert extras pending biolink-model#1774 and
   are EXEMPT from the validity score: a `biolink_valid_pct` below 1.0 is never caused by them.
 - QUALIFIERS: enum-ranged qualifiers take a literal TOKEN, never a CURIE

{tablassert-9.1.0 → tablassert-10.1.0}/src/tablassert/cli.py

@@ -121,13 +121,15 @@ def build_pipeline(
     """Build a knowledge graph from a YAML configuration file.
 
     Runs the six-stage build pipeline: load tables → extract sections → build
-    Tcodes → collect instructions → build subgraphs → compile graph.
+    Tcodes → collect instructions → build subgraphs → compile graph. With ``qc``
+    enabled a seventh stage studies the final NDJSON files.
 
     Args:
         configuration_file: Path to the graph YAML file.
         progress: Pipeline progress reporter.
         release: When ``True``, emit release-mode artifacts.
-        qc: When ``True``, run quality-control audits on each section.
+        qc: When ``True``, run quality-control audits on each section and assert
+            over the final NDJSON files (failing the build on any violation).
         log: When ``True``, enable per-section verbose logging.
         head: When ``True``, preview a random sample of up to 5 rows per section (fast schema/shape check).
 
@@ -218,9 +220,35 @@ def build_pipeline(
         subgraphs, g.name, g.version, g.description, g.contributions, g.ui_explanation, g.tables, g.infores, on_phase=sub_step, on_subgraph=advance
     )
 
+    # Stage 7/7 (only with --qc): assert over the final NDJSON files.
+    if qc:
+        progress.stage("Studying Graph")
+        study_final_ndjson(g.name, g.version)
+
     logger.info("Built graph {name} v{version}: {n} sections", name=g.name, version=g.version, n=n)
 
 
+def study_final_ndjson(name: str, version: str) -> None:
+    """Run study assertions over a build's final NDJSON files (the ``--qc`` stage 7).
+
+    Args:
+        name: Graph name, used to locate ``./<name>_<version>.nodes.ndjson``.
+        version: Graph version, used to locate ``./<name>_<version>.edges.ndjson``.
+
+    Raises:
+        SystemExit: With status 1 when any study assertion is violated.
+    """
+    from tablassert.study import format_violations, study_kgx
+
+    violations = study_kgx(Path(f"./{name}_{version}.nodes.ndjson"), Path(f"./{name}_{version}.edges.ndjson"))
+    if violations:
+        summary: str = format_violations(violations)
+        print(summary, file=sys.stderr)
+        logger.warning("study assertions failed on final NDJSON:\n{summary}", summary=summary)
+        raise SystemExit(1)
+    logger.info("study assertions passed on final NDJSON")
+
+
 def validate_pipeline(table_configuration_file: Path, progress: PipelineProgress) -> None:
     """Validate section syntax from a YAML configuration file.
 
@@ -599,11 +627,14 @@ def build_kg(
 
     ``--qc`` requires the ``[qc]`` extra (``pip install "tablassert[qc]"``); it is
     checked before the build starts, because the audit stage runs LAST and a missing
-    extra would otherwise surface only after entity resolution has finished.
+    extra would otherwise surface only after entity resolution has finished. It also
+    runs a final study stage that asserts over the emitted NDJSON -- no duplicate node
+    ids, no undeclared or isolated nodes, no malformed lines or stray whitespace --
+    and fails the build (non-zero exit) when any assertion is violated.
     """
     if qc:
         extras.require("qc", required_by="--qc")
-    run(6, build_pipeline, graph_configuration_file, release=release, qc=qc, log=log, head=head)
+    run(7 if qc else 6, build_pipeline, graph_configuration_file, release=release, qc=qc, log=log, head=head)
 
 
 @APP.command(name="validate")
@@ -950,7 +981,7 @@ def _prebuilt_fullmap_urls(babel_version: str) -> tuple[str, str]:
 
     RENCI publishes a prebuilt ``fullmap.tar.zst`` (and a ``sha256sum.txt``) under
     ``{BABEL_BASE}/{babel_version}/fullmap/{tablassert_version}/``, where the version
-    directory is the INSTALLED Tablassert package version (e.g. ``9.1.0``) — resolved from
+    directory is the INSTALLED Tablassert package version (e.g. ``10.1.0``) — resolved from
     installed-package metadata, never hardcoded, so a new release looks itself up.
 
     Args:

{tablassert-9.1.0 → tablassert-10.1.0}/src/tablassert/enums.py

@@ -57,7 +57,6 @@ class Files(str, Enum):
 class EncodingMethods(str, Enum):
     VALUE = "value"
     COLUMN = "column"
-    LIST = "list"
 
 
 class FillMethods(str, Enum):

{tablassert-9.1.0 → tablassert-10.1.0}/src/tablassert/errors.py

@@ -25,14 +25,13 @@ TablassertErrorCodes = Literal[
     "provenance-bad-pmc-id",
     "provenance-missing-publication",
     "provenance-publication-and-override",
-    "encoding-list-requires-list",
-    "encoding-list-incompatible-ops",
-    "encoding-list-annotation-only",
+    "encoding-list-method-removed",
     "annotation-split-by-requires-column",
     "annotation-split-by-empty",
     "qualifier-auto-derived",
     "qualifier-bad-value",
     "qualifier-unsatisfiable",
+    "qualifier-nullable-literal",
 ]
 
 

{tablassert-9.1.0 → tablassert-10.1.0}/src/tablassert/fullmap.py

@@ -473,7 +473,7 @@ def _coalesce_expr(col: str, suffix: str, base: str, prefix: str, cast_str: bool
     return pl.when(pl.col(base).is_not_null()).then(l1).otherwise(l2).alias(col + suffix)
 
 
-def join_matches(lf: pl.LazyFrame, col: str, matches: pl.DataFrame, tag: str = "_two") -> pl.LazyFrame:
+def join_matches(lf: pl.LazyFrame, col: str, matches: pl.DataFrame, tag: str = "_two", drop_unresolved: bool = True) -> pl.LazyFrame:
     """Join ranked fullmap matches back into ``lf`` for one column.
 
     Coalesces level-one and level-two hits per row (level one wins when
@@ -486,10 +486,15 @@ def join_matches(lf: pl.LazyFrame, col: str, matches: pl.DataFrame, tag: str = "
         col: Column being resolved.
         matches: Ranked matches for this column from ``filter_and_rank``.
         tag: Suffix used to derive the level-two column name.
+        drop_unresolved: When True (default) rows whose ``col`` did not match are
+            dropped — the behavior subject/object require. When False the row is
+            kept and the column (plus its derived ``<col>_*`` columns) stays null;
+            used by ``nullable`` qualifiers so a blank/unresolvable cell keeps the
+            edge and the null-stripper omits the qualifier key.
 
     Returns:
         New LazyFrame with resolved columns; rows whose ``col`` did not match
-        are dropped.
+        are dropped unless ``drop_unresolved`` is False.
 
     Notes:
         Split out of ``resolve`` so ``resolve_batch`` can apply per-column
@@ -511,7 +516,10 @@ def join_matches(lf: pl.LazyFrame, col: str, matches: pl.DataFrame, tag: str = "
     result = result.select(pl.exclude(r"^(CURIE|PREFERRED_NAME|CATEGORY_NAME|TAXON_ID|SOURCE_NAME|SOURCE_VERSION|NLP_LEVEL|PR|FREQUENCY)(_l2)?$"))
     result = result.select(pl.exclude(col + tag))
     result = result.with_columns(pl.col(f"{col}_taxon").replace("NCBITaxon:0", None))
-    result = result.filter(pl.col(col).is_not_null())
+    if drop_unresolved:
+        # Subject/object (and strict qualifiers) drop rows that failed resolution; a
+        # nullable qualifier keeps the edge and leaves the column null for the null-stripper.
+        result = result.filter(pl.col(col).is_not_null())
 
     return result.lazy()
 
@@ -525,6 +533,12 @@ class ResolveSpec(NamedTuple):
     avoid: list[Categories] | None = None
     exclude_prefixes: list[str] | None = None
     exclude_regex: list[str] | None = None
+    nullable: bool = False
+    """When True, an unresolved/blank cell keeps its row instead of dropping the edge.
+
+    Set only for ``nullable`` qualifiers; subject/object always resolve strict so an
+    edge with a missing node is dropped, never emitted.
+    """
 
 
 def resolve_batch(
@@ -585,7 +599,7 @@ def resolve_batch(
         )
         if log:
             log_unmatched(spec.col, terms_by_col[spec.col], matches, section_hash, config_file)
-        result = join_matches(result, spec.col, matches, tag)
+        result = join_matches(result, spec.col, matches, tag, drop_unresolved=not spec.nullable)
 
     return result
 

{tablassert-9.1.0 → tablassert-10.1.0}/src/tablassert/lib.py

@@ -262,8 +262,10 @@ def prune_to_class(lf: pl.LazyFrame) -> pl.LazyFrame:
 
     Categories vary per row within a section, so this masks per row rather than
     dropping columns: values are nulled where the row's class rejects them, and the
-    Rust null-stripper then removes the key entirely. Scalars are wrapped where the
-    class declares the slot multivalued.
+    Rust null-stripper then removes the key entirely. Scalars are wrapped into
+    one-element lists when the slot is multivalued on every class that declares it
+    (a column has one dtype, so per-row wrapping is impossible; a slot Biolink
+    declares scalar on some classes and multivalued on others stays scalar).
 
     Args:
         lf: Edges LazyFrame carrying a resolved ``category`` column.
@@ -306,10 +308,18 @@ def prune_to_class(lf: pl.LazyFrame) -> pl.LazyFrame:
             # Preserve what the class refuses rather than deleting it outright; the
             # value is real evidence, it just has no slot on this association class.
             rescued.append(pl.when(ok | text.is_null()).then(None).otherwise(pl.concat_str([pl.lit(f"{col}="), text])))
-        # Biolink makes the same slot multivalued on some classes and scalar on others.
-        listed: dict[str, bool] = {cat: is_multivalued(association_class(cat), col) for cat in categories}
-        if any(listed.values()) and not isinstance(schema[col], pl.List):
-            keep = pl.when(first.replace_strict(listed, default=False)).then(pl.concat_list(keep)).otherwise(keep)
+        # A column has one dtype, so the multivalued wrap must be uniform across rows:
+        # wrap every value into a one-element list when every class declaring the slot
+        # types it multivalued. `is_multivalued` is False for classes that do not declare
+        # the slot at all, so the scan is restricted to declaring classes -- including
+        # them is what produced a spuriously mixed per-row wrap that died in
+        # strict_cast at collect. Rows whose class rejects the slot are already null and
+        # stay null. A hypothetically mixed slot keeps its scalar rather than crashing.
+        declaring: list[str] = [cat for cat in categories if accepts[cat]]
+        listed: dict[str, bool] = {cat: is_multivalued(association_class(cat), col) for cat in declaring}
+        if listed and all(listed.values()) and not isinstance(schema[col], pl.List):
+            # concat_list maps null -> [null]; the when preserves real nulls instead.
+            keep = pl.when(keep.is_null()).then(None).otherwise(pl.concat_list(keep))
         updates.append(keep.alias(col))
     if rescued:
         updates.append(pl.concat_list(rescued).list.drop_nulls().alias(PRUNED_COLUMN))
@@ -632,13 +642,12 @@ def split_list(lf: pl.LazyFrame, col: str, delimiter: str) -> pl.LazyFrame:
 
     A column encoding is scalar by construction, so a multivalued Biolink slot such as
     ``has_evidence`` fed from an aggregated cell would otherwise be emitted as a single
-    joined string -- and ``mask_illegal_edge_fields`` wraps that scalar into a
+    joined string -- and ``prune_to_class`` wraps that scalar into a
     one-element list, so the value survives Biolink validation while consumers iterate a
     single ``"a|b|c"`` blob instead of three ids.
 
-    Same split as ``explode``, minus the fan-out: this is the per-row counterpart of
-    ``method: list`` (the literal form covers a fixed array known at config time, this
-    covers an array that differs on every row).
+    Same split as ``explode``, minus the fan-out: this is the one multivalued
+    encoding (``split_by``), turning each row's cell into its own JSON array.
 
     Args:
         lf: Source LazyFrame.
@@ -930,7 +939,7 @@ class Tcode(Section):
             containing ``None`` placeholders) ready for ``clean`` to filter.
         """
         return [
-            (value, (col, x.encoding)) if x.method in (EncodingMethods.VALUE, EncodingMethods.LIST) else None,
+            (value, (col, x.encoding)) if x.method == EncodingMethods.VALUE else None,
             (column, (col, idxname(x.encoding))) if x.method == EncodingMethods.COLUMN else None,
             (column, (f"original_{col}", col)) if table_literal else None,
             (fill, (col, x.fill)) if x.fill else None,
@@ -1034,8 +1043,20 @@ class Tcode(Section):
             *[(x, x.qualifier) for x in qualifiers if x.resolved],
         ]
         literals: list[Qualifier] = [x for x in qualifiers if not x.resolved]
+        # A nullable qualifier keeps its edge when the cell is blank or unresolvable (the
+        # column stays null and the null-stripper omits the key); subject/object and
+        # strict qualifiers drop the row as before.
         specs: list[ResolveSpec] = [
-            ResolveSpec(col, str(x.taxon) if x.taxon else None, x.prioritize, x.avoid, x.exclude_prefixes, x.exclude_regex) for x, col in node_columns
+            ResolveSpec(
+                col,
+                str(x.taxon) if x.taxon else None,
+                x.prioritize,
+                x.avoid,
+                x.exclude_prefixes,
+                x.exclude_regex,
+                x.nullable if isinstance(x, Qualifier) else False,
+            )
+            for x, col in node_columns
         ]
         return [
             [self.node_prep(x, col) for x, col in node_columns],
@@ -1043,7 +1064,15 @@ class Tcode(Section):
             # which exist to feed entity resolution these columns never undergo.
             [self.encoding(x, x.qualifier) for x in literals],
             (resolve_batch, (specs, db, self.log, self.store.stem, self.config.name, True)),
-            [(fullmap_audit, (col, self.store.stem, self.config.name, "passed", True)) for _, col in node_columns] if self.qc else None,
+            # QC audits only the strict columns: a nullable qualifier's nulls are expected
+            # (blank cell / no match), not resolution errors for the audit to delete.
+            [
+                (fullmap_audit, (col, self.store.stem, self.config.name, "passed", True))
+                for x, col in node_columns
+                if not (isinstance(x, Qualifier) and x.nullable)
+            ]
+            if self.qc
+            else None,
         ]
 
     def _provenance_ops(self: Self) -> list[Any]:

{tablassert-9.1.0 → tablassert-10.1.0}/src/tablassert/models.py

@@ -19,6 +19,7 @@ from tablassert.biolink import (
     Predicates,
     Qualifiers,
 )
+from tablassert.coerce import effect_size_target, effect_type_target, pvalue_target, study_size_target
 from tablassert.enums import Comparisons, EncodingMethods, Files, FillMethods, Functions, Repositories, Tokens
 from tablassert.errors import BiolinkRelocationWarning, TablassertErrorCodes, TablassertValidationError
 
@@ -164,67 +165,40 @@ class Math(TablaBase):
 class Encoding(TablaBase):
     method: EncodingMethods = Field(
         EncodingMethods.VALUE,
-        description="Interpret `encoding` as a literal value, a list of literal values, or source column letters.",
-        examples=[EncodingMethods.VALUE, EncodingMethods.COLUMN, EncodingMethods.LIST],
-    )
-    encoding: str | int | float | list[str | int | float] = Field(
-        ...,
-        description="Literal value, list of literal values (with `method: list`), or source column letters.",
-        examples=["A", "BRCA1", 1.0, ["EFO:0001", "EFO:0002"]],
+        description="Interpret `encoding` as a literal value or source column letters.",
+        examples=[EncodingMethods.VALUE, EncodingMethods.COLUMN],
     )
+    encoding: str | int | float = Field(..., description="Literal value or source column letters.", examples=["A", "BRCA1", 1.0])
+
+    @model_validator(mode="before")
+    @classmethod
+    def reject_removed_list_method(cls, data: Any) -> Any:
+        """Fail configs still declaring the removed ``method: list`` with a migration pointer.
+
+        ``method: list`` (a literal list emitted as one fixed JSON array on every row)
+        was removed: ``split_by`` on a ``method: column`` annotation is the one
+        multivalued encoding now, and it covers the per-row case the literal never
+        could. A bare pydantic enum error would only say the value is invalid, so
+        this hook turns the stale config into the actionable coded error the
+        migration needs.
+        """
+        if isinstance(data, dict) and data.get("method") == "list":
+            raise TablassertValidationError(
+                "`method: list` was removed; for a multivalued annotation use `method: column` with `split_by` "
+                "to split each cell's delimited text into a JSON array (subject/object/qualifier nodes are single entities).",
+                code="encoding-list-method-removed",
+            )
+        return data
 
     @model_validator(mode="after")
     def excel_style_columns(self: Self) -> Self:
-        # A list encoding is only valid under `method: list` (checked by `list_method_consistency`);
-        # skip the Excel-letter check here so that case reports the clearer list error.
-        if self.method == EncodingMethods.COLUMN and not isinstance(self.encoding, list):
+        if self.method == EncodingMethods.COLUMN:
             x = self.encoding
             if not re.search(r"^[A-Z]{1,3}$", str(x)):
                 raise TablassertValidationError(f"`encoding` must be an Excel-style column name (A-ZZ), got {x!r}.", code="encoding-bad-excel-column")
 
         return self
 
-    @model_validator(mode="after")
-    def list_method_consistency(self: Self) -> Self:
-        """Enforce that ``method: list`` carries a literal list and no scalar string ops.
-
-        ``method: list`` is the multivalued counterpart of ``method: value``: the
-        ``encoding`` is a literal list emitted as a real JSON array (for multivalued
-        Biolink slots such as ``has_evidence``). The scalar string ops
-        (``regex``/``remove``/``prefix``/``suffix``/``transformations``/``fill``/``explode_by``)
-        operate on a single string per row and would mangle a list column, so they are
-        rejected here — encode the final values directly instead.
-        """
-        is_list: bool = isinstance(self.encoding, list)
-        if self.method == EncodingMethods.LIST:
-            if not is_list:
-                raise TablassertValidationError("`method: list` requires `encoding` to be a list of values.", code="encoding-list-requires-list")
-            scalar_ops: list[str] = []
-            if self.regex:
-                scalar_ops.append("regex")
-            if self.fill is not None:
-                scalar_ops.append("fill")
-            if self.explode_by is not None:
-                scalar_ops.append("explode_by")
-            if self.remove:
-                scalar_ops.append("remove")
-            if self.prefix:
-                scalar_ops.append("prefix")
-            if self.suffix:
-                scalar_ops.append("suffix")
-            if self.transformations:
-                scalar_ops.append("transformations")
-            if scalar_ops:
-                raise TablassertValidationError(
-                    f"`method: list` is a literal list and is incompatible with the scalar string ops "
-                    f"({', '.join(scalar_ops)}); apply them upstream or encode the final values directly.",
-                    code="encoding-list-incompatible-ops",
-                )
-        elif is_list:
-            raise TablassertValidationError("A list `encoding` requires `method: list`.", code="encoding-list-requires-list")
-
-        return self
-
     regex: list[Regex] | None = Field(
         None,
         description="Ordered regex replacements applied to encoded text.",
@@ -306,23 +280,6 @@ class NodeEncoding(Encoding):
 
         return exclude_regex
 
-    @model_validator(mode="after")
-    def reject_list_method(self: Self) -> Self:
-        """Reject ``method: list`` on node encodings (subject/object/qualifiers).
-
-        ``method: list`` is the multivalued counterpart of ``method: value`` and only
-        makes sense on an annotation (a multivalued Biolink slot). A subject/object/
-        qualifier is a single entity: a list node column crashes resolution deep in the
-        pipeline (a polars list-to-string cast) instead of failing at config time, and an
-        enum-ranged qualifier would silently emit a list where Biolink expects one token.
-        """
-        if self.method == EncodingMethods.LIST:
-            raise TablassertValidationError(
-                "`method: list` is only valid on annotations (multivalued Biolink slots); subject/object/qualifier nodes are single entities.",
-                code="encoding-list-annotation-only",
-            )
-        return self
-
 
 class Qualifier(NodeEncoding):
     qualifier: Qualifiers = Field(
@@ -330,6 +287,15 @@ class Qualifier(NodeEncoding):
         description="Qualifier predicate key used as the output qualifier column.",
         examples=[Qualifiers.OBJECT_DIRECTION_QUALIFIER, Qualifiers.SUBJECT_CONTEXT_QUALIFIER],
     )
+    nullable: bool = Field(
+        False,
+        description=(
+            "When True, a blank or unresolvable ``method: column`` cell keeps the edge and omits the "
+            "qualifier for that row (the column stays null and the null-stripper drops the key); when "
+            "False (default) such a row is dropped, exactly like an unresolved subject/object. Only "
+            "meaningful for ``method: column`` — a literal qualifier can never be null."
+        ),
+    )
 
     @property
     def vocabulary(self: Self) -> frozenset[str] | None:
@@ -400,6 +366,23 @@ class Qualifier(NodeEncoding):
             )
         return self
 
+    @model_validator(mode="after")
+    def reject_nullable_literal_qualifiers(self: Self) -> Self:
+        """Reject ``nullable: true`` on literal qualifiers.
+
+        ``nullable`` only has meaning for a ``method: column`` qualifier: a blank or
+        unresolved cell keeps the edge and the qualifier is omitted for that row. A
+        ``method: value`` qualifier is a config-time constant that can never be blank,
+        so ``nullable`` would be dead config that misleads the reader. Fail loudly at
+        config time instead (the removed ``method: list`` is already rejected upstream
+        by :meth:`Encoding.reject_removed_list_method`).
+        """
+        if self.nullable and self.method != EncodingMethods.COLUMN:
+            raise TablassertValidationError(
+                "`nullable` only applies to `method: column` qualifiers; a literal qualifier can never be null.", code="qualifier-nullable-literal"
+            )
+        return self
+
 
 class Statement(TablaBase):
     subject: NodeEncoding = Field(..., description="Subject node encoding and mapping configuration.")
@@ -508,19 +491,15 @@ class Annotation(Encoding):
     def split_by_requires_a_column(self) -> Self:
         """Enforce that ``split_by`` carries a real separator and a ``method: column`` encoding.
 
-        ``split_by`` is the per-row counterpart of ``method: list``: it turns each cell's
-        own delimited text into a real JSON array, which is the one multivalued shape a
-        literal cannot express (a list ``encoding`` is fixed at config time, so it emits
-        the same array on every row). A ``value``/``list`` encoding therefore declares its
-        members directly rather than round-tripping them through a separator.
+        ``split_by`` is the one multivalued encoding: it turns each cell's own
+        delimited text into a real JSON array, per row. A ``value`` encoding is a
+        scalar literal with no per-row text to split, so it rejects ``split_by``.
         """
         if self.split_by is None:
             return self
         if self.method != EncodingMethods.COLUMN:
             raise TablassertValidationError(
-                "`split_by` splits a column's per-row text and requires `method: column`; "
-                "declare a literal multivalued annotation with `method: list` instead.",
-                code="annotation-split-by-requires-column",
+                "`split_by` splits a column's per-row text and requires `method: column`.", code="annotation-split-by-requires-column"
             )
         if not self.split_by:
             # An empty separator splits into individual characters -- exactly the
@@ -536,18 +515,24 @@ class Annotation(Encoding):
         # is the real problem -- an author asking for `supporting_study_size` has no way to discover
         # that Biolink attaches it to no class and the pipeline rerouted it.
         name: str = str(self.annotation)
-        if name in UNSATISFIABLE_EDGE_FIELDS:
+        # Judge the coerced target, not the raw alias: the clean-phase column coercions rename
+        # statistical aliases to their canonical slot before any relocation runs, so
+        # `adjusted p value` reaches the edge as `adjusted_p_value` and warning on the alias
+        # is a false positive.
+        target: str = pvalue_target(name) or study_size_target(name) or effect_size_target(name) or effect_type_target(name) or name
+        shown: str = f"`{name}` (coerced to `{target}`)" if target != name else f"`{name}`"
+        if target in UNSATISFIABLE_EDGE_FIELDS:
             warnings.warn(
-                f"`{name}` is declared in biolink-model {BIOLINK_VERSION} but attached to no association class, "
+                f"{shown} is declared in biolink-model {BIOLINK_VERSION} but attached to no association class, "
                 "so it cannot be emitted on an edge; its value is routed onto the inlined supporting study "
                 "instead. Use a slot a Biolink association declares (e.g. `p_value`, `adjusted_p_value`) if you "
                 "need it on the edge itself.",
                 BiolinkRelocationWarning,
                 stacklevel=2,
             )
-        elif name not in ALLOWED_EDGE_FIELDS:
+        elif target not in ALLOWED_EDGE_FIELDS:
             warnings.warn(
-                f"`{name}` is not a Biolink association slot, so it is folded into `supporting_text` as a "
+                f"{shown} is not a Biolink association slot, so it is folded into `supporting_text` as a "
                 f'"{name}: <value>" string rather than emitted as its own edge field.',
                 BiolinkRelocationWarning,
                 stacklevel=2,

tablassert-10.1.0/src/tablassert/study.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import json
+from collections import Counter
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from tablassert.log import cat
+
+logger = cat("QC")
+
+# Human-readable phrasing for each assertion, used by format_violations.
+_MESSAGES: dict[str, str] = {
+    "file-missing": "file not found",
+    "malformed-lines": "empty or malformed JSON lines",
+    "whitespace-values": "values with leading/trailing whitespace",
+    "duplicate-node-ids": "duplicate node ids",
+    "undeclared-nodes": "nodes referenced by edges but not declared in the nodes file",
+    "isolated-nodes": "declared nodes participating in no edge",
+}
+
+
+@dataclass
+class StudyViolation:
+    """One failed study assertion over the final KGX NDJSON files.
+
+    Attributes:
+        check: Assertion key into ``_MESSAGES`` (e.g. ``"duplicate-node-ids"``).
+        label: Which file the violation belongs to (``"nodes"`` or ``"edges"``).
+        count: Exact number of offending records/values.
+        examples: Capped list of example offenders for the stderr summary.
+    """
+
+    check: str
+    label: str
+    count: int
+    examples: list[str] = field(default_factory=list)
+
+
+@dataclass
+class _FileScan:
+    """Accumulated facts from one streamed pass over an NDJSON file."""
+
+    ids: set[str]
+    duplicate_ids: Counter[str]
+    whitespace: Counter[str]
+    malformed: int
+    missing: bool
+    path: Path
+
+
+def _scan_ndjson(path: Path, *, edge: bool) -> _FileScan:
+    """Stream one NDJSON file, collecting the facts the study assertions need.
+
+    Args:
+        path: Path to a ``.nodes.ndjson`` or ``.edges.ndjson`` file.
+        edge: ``True`` to collect referenced ids from ``subject``/``object``;
+            ``False`` to collect declared node ``id``s and track duplicates.
+
+    Returns:
+        A :class:`_FileScan`; ``missing`` is set (and nothing else) when the
+        file does not exist, so a typo'd path can never read as a clean pass.
+    """
+    scan: _FileScan = _FileScan(set(), Counter(), Counter(), 0, not path.is_file(), path)
+    if scan.missing:
+        return scan
+    with path.open(encoding="utf-8") as handle:
+        for line in handle:
+            if not line.strip():
+                scan.malformed += 1
+                continue
+            try:
+                record: object = json.loads(line)
+            except json.JSONDecodeError:
+                scan.malformed += 1
+                continue
+            if not isinstance(record, dict):
+                scan.malformed += 1
+                continue
+            for key, value in record.items():
+                if isinstance(value, str) and value != value.strip():
+                    scan.whitespace[key] += 1
+            if edge:
+                for role in ("subject", "object"):
+                    ident: object = record.get(role)
+                    if isinstance(ident, str):
+                        scan.ids.add(ident)
+            else:
+                ident = record.get("id")
+                if isinstance(ident, str):
+                    # Rust dedup only removes byte-identical lines, so a repeated id
+                    # here means two nodes share an id with different content.
+                    if ident in scan.ids:
+                        scan.duplicate_ids[ident] += 1
+                    scan.ids.add(ident)
+    return scan
+
+
+def study_kgx(nodes_path: Path, edges_path: Path, *, example_limit: int = 10) -> list[StudyViolation]:
+    """Assert over the final KGX NDJSON files, in the spirit of studyKGtsvs.pl.
+
+    Streams both files once each and checks: duplicate node ids, nodes referenced
+    by edges but never declared (``undeclared``), declared nodes participating in
+    no edge (``isolated``), empty/malformed lines, and string values carrying
+    leading/trailing whitespace. Every check is an assertion -- the caller decides
+    whether violations fail the build.
+
+    Args:
+        nodes_path: Path to ``<name>_<version>.nodes.ndjson``.
+        edges_path: Path to ``<name>_<version>.edges.ndjson``.
+        example_limit: Maximum number of examples retained per violation.
+
+    Returns:
+        A list of :class:`StudyViolation`; empty when every assertion passes.
+    """
+    nodes: _FileScan = _scan_ndjson(nodes_path, edge=False)
+    edges: _FileScan = _scan_ndjson(edges_path, edge=True)
+
+    violations: list[StudyViolation] = []
+    for label, scan in (("nodes", nodes), ("edges", edges)):
+        if scan.missing:
+            violations.append(StudyViolation("file-missing", label, 1, [str(scan.path)]))
+            continue
+        if scan.malformed:
+            violations.append(StudyViolation("malformed-lines", label, scan.malformed))
+        if scan.whitespace:
+            examples: list[str] = [f"{field_name} ({n})" for field_name, n in scan.whitespace.most_common(example_limit)]
+            violations.append(StudyViolation("whitespace-values", label, sum(scan.whitespace.values()), examples))
+    if nodes.duplicate_ids:
+        examples = [ident for ident, _ in nodes.duplicate_ids.most_common(example_limit)]
+        violations.append(StudyViolation("duplicate-node-ids", "nodes", len(nodes.duplicate_ids), examples))
+    if not nodes.missing and not edges.missing:
+        undeclared: list[str] = sorted(edges.ids - nodes.ids)
+        if undeclared:
+            violations.append(StudyViolation("undeclared-nodes", "edges", len(undeclared), undeclared[:example_limit]))
+        isolated: list[str] = sorted(nodes.ids - edges.ids)
+        if isolated:
+            violations.append(StudyViolation("isolated-nodes", "nodes", len(isolated), isolated[:example_limit]))
+    return violations
+
+
+def format_violations(violations: list[StudyViolation]) -> str:
+    """Render violations as a human-readable, one-line-per-assertion summary.
+
+    Args:
+        violations: The failed assertions returned by :func:`study_kgx`.
+
+    Returns:
+        Newline-joined summary lines, e.g.
+        ``nodes: 3 duplicate node ids (e.g. HGNC:5, HGNC:6)``.
+    """
+    lines: list[str] = []
+    for violation in violations:
+        line: str = f"{violation.label}: {violation.count} {_MESSAGES[violation.check]}"
+        if violation.examples:
+            line += f" (e.g. {', '.join(violation.examples)})"
+        lines.append(line)
+    return "\n".join(lines)