tablassert 9.1.0__tar.gz → 10.0.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tablassert
-Version: 9.1.0
+Version: 10.0.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.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tablassert"
-version = "9.1.0"
+version = "10.0.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.0.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.0.0}/src/tablassert/cli.py

@@ -950,7 +950,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.0.0``) — resolved from
     installed-package metadata, never hardcoded, so a new release looks itself up.
 
     Args:

{tablassert-9.1.0 → tablassert-10.0.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.0.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.0.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.0.0}/src/tablassert/lib.py

@@ -636,9 +636,8 @@ def split_list(lf: pl.LazyFrame, col: str, delimiter: str) -> pl.LazyFrame:
     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 +929,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 +1033,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 +1054,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.0.0}/src/tablassert/models.py

@@ -164,67 +164,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 +279,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 +286,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 +365,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 +490,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