tablassert 14.0.0__tar.gz → 15.0.0__tar.gz

{tablassert-14.0.0 → tablassert-15.0.0}/PKG-INFO

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

{tablassert-14.0.0 → tablassert-15.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tablassert"
-version = "14.0.0"
+version = "15.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-14.0.0 → tablassert-15.0.0}/src/tablassert/agent.py

@@ -1299,11 +1299,11 @@ def _biolink_report(nodes: Path, edges: Path) -> dict[str, object]:
     Wraps ``biolink.validate_kgx`` (the same check ``tablassert validate-kgx`` runs) into the
     flat, JSON-safe keys ``build_and_audit`` returns, plus the ``_notes`` list the caller
     folds into its own. ``biolink_valid_pct`` excludes the known-pending fields Tablassert
-    emits on purpose (``approval_ids`` as a translator-ingest pass-through and the KGX
-    denormalized carryovers -- the set is derived, and emptied itself of ``effect_size`` /
-    ``effect_type`` when biolink-model 4.4.4 shipped them as real Association slots) so the
-    scored number reflects the agent's decisions rather than a deliberate gap;
-    ``biolink_valid_pct_strict`` keeps that gap visible.
+    emits on purpose (the KGX denormalized carryovers -- the set is derived, and emptied
+    itself of ``approval_ids`` when the curated pass-through override was removed and of
+    ``effect_size`` / ``effect_type`` when biolink-model 4.4.4 shipped them as real
+    Association slots) so the scored number reflects the agent's decisions rather than a
+    deliberate gap; ``biolink_valid_pct_strict`` keeps that gap visible.
 
     Never raises: an unreadable or unparseable artifact degrades to ``None`` metrics and a
     note, exactly like the coverage measurement above it.
@@ -2349,19 +2349,13 @@ qualifier and evidence slot the specific class declared. build_and_audit reports
   `effect_type`), `q value` / `padj` -> `adjusted_p_value`. Names nothing claims
   (`fold_change` alone, `z_score`, `lfsr`, `standard_error`, free-form notes) are folded
   into `supporting_text`. Prefer `p_value`, `adjusted_p_value`, `effect_size`,
-  `effect_type`, `has_evidence`. For FDA application numbers, `approval_ids` is a deliberate
-  translator-ingest pass-through: keep the pipe-joined value as a scalar and do not add
-  `split_by`.
+  `effect_type`, `has_evidence`.
 - MULTIVALUED slots (`has_evidence` and friends) take a real JSON array, never a joined string:
   `split_by` is the ONLY multivalued encoding — there is no literal-list method. INSPECT the
   column's cells first (read_table shows them); the separator they ACTUALLY use — `|`, `,`, or
   `;` — is the one you declare: `{method: column, encoding: <letter>, split_by: "<separator>"}`.
   A SINGLE-value cell gets NO `split_by`: its scalar wraps into a one-element array, the correct
   shape. Cells that DO join multiple values but OMIT `split_by` ship as one unusable joined blob.
-- `approval_ids` is a deliberate translator-ingest pass-through extra, EXEMPT from the
-  validity score: a `biolink_valid_pct` below 1.0 is never caused by it. (`effect_size` /
-  `effect_type` were exempt only until biolink-model 4.4.4 shipped them as real Association
-  slots; they now validate like any other slot.)
 - QUALIFIERS: enum-ranged qualifiers take a literal TOKEN, never a CURIE
   (`object_direction_qualifier: increased`, not a UMLS id), and `species_context_qualifier` is
   disabled — never author it as a qualifier or annotation.

{tablassert-14.0.0 → tablassert-15.0.0}/src/tablassert/biolink.py

@@ -396,11 +396,6 @@ def resolve_association_class(category: str, predicate: str) -> type[Any]:
 #   - ``taxon`` -- a node property; no species-context edge is synthesized from it.
 TABLASERT_EDGE_EXTRAS: frozenset[str] = frozenset(
     [
-        # FDA application numbers from translator-ingests (DAKP precedent): the ingest
-        # emits them as a pipe-joined scalar (e.g. ``"011111|022222"``) with no
-        # ``split_by``, so the curated extra carries the scalar to the final edge
-        # verbatim instead of folding it into ``supporting_text``.
-        "approval_ids",
         "broad_synonym",
         "equivalent_identifiers",
         "evidence_direction",
@@ -574,9 +569,9 @@ against the resolved class is done by ``lib.prune_to_class()``.
 KNOWN_PENDING_EDGE_FIELDS: frozenset[str] = TABLASERT_EDGE_EXTRAS - frozenset(_association_model_fields())
 """Curated edge extras the installed Biolink Model does not (yet) declare on any association.
 
-Tablassert emits these deliberately -- ``approval_ids`` as a translator-ingest pass-through,
-plus the KGX denormalized carryovers (``synonym``, ``xref``, ``relation``, ...) -- so a Biolink
-class rejects them as ``extra_forbidden`` even though the build is behaving as designed. The
+Tablassert emits these deliberately -- the KGX denormalized carryovers (``synonym``,
+``xref``, ``relation``, ...) -- so a Biolink class rejects them as ``extra_forbidden`` even
+though the build is behaving as designed. The
 statistical ``effect_size`` / ``effect_type`` pair is no longer pending since
 biolink-model 4.4.4 shipped PR #1774.
 :func:`is_pending_problem` uses this set
@@ -765,7 +760,7 @@ def validate_kgx(nodes_path: Path, edges_path: Path, limit: int = 20) -> dict[st
     Two pass rates are reported. ``valid`` is strict and drives ``ok`` (the CLI's
     non-zero exit). ``valid_excluding_pending`` additionally counts records whose *every*
     failure is a :func:`is_pending_problem` -- the score to optimize against, so a
-    deliberate gap like the curated ``approval_ids`` pass-through is not mistaken for a
+    deliberate gap like the KGX denormalized carryovers is not mistaken for a
     malformed record. The two converge as future model releases absorb curated extras.
 
     Args:

{tablassert-14.0.0 → tablassert-15.0.0}/src/tablassert/lib.py

@@ -222,7 +222,7 @@ def predicate_options(subject_category: str, object_category: str) -> frozenset[
     return legal_predicates(derived_edge_category(subject_category, object_category))
 
 
-def edge_category(lf: pl.LazyFrame, predicate: str | None = None) -> pl.LazyFrame:
+def edge_category(lf: pl.LazyFrame, predicate: str | None = None, category_override: dict[str, str] | None = None) -> pl.LazyFrame:
     """Add the derived ``category`` column using native polars replace operations.
 
     The ``(subject role, object role)`` lookup alone routinely produces a category
@@ -233,10 +233,18 @@ def edge_category(lf: pl.LazyFrame, predicate: str | None = None) -> pl.LazyFram
     by :func:`biolink.resolve_association_class`, which walks up the association
     hierarchy only as far as the predicate requires.
 
+    ``category_override`` pins the association class per *object* category (the
+    config's ``statement.category_override``): a row whose raw object category --
+    before the role rollup that merges e.g. ``Disease`` and ``PhenotypicFeature``
+    into one pair key -- appears in the map carries the pinned class instead of the
+    pair-derived one. Pinned classes pass through the same predicate reconciliation.
+
     Args:
         lf: Source LazyFrame with ``subject category`` and ``object category``
             columns (biolink-prefixed).
         predicate: Section predicate CURIE used to reconcile the derived category.
+        category_override: ``{object category (bare name): biolink: CURIE}`` map
+            applied per row in place of the pair lookup.
 
     Returns:
         LazyFrame with a new list-typed ``category`` column containing the
@@ -252,12 +260,20 @@ def edge_category(lf: pl.LazyFrame, predicate: str | None = None) -> pl.LazyFram
         # small raw-category -> resolved-category remap resolved once at plan time.
         edge_lookup = {k: f"biolink:{resolve_association_class(v, predicate).__name__}" for k, v in edge_lookup.items()}
         default = f"biolink:{resolve_association_class(default, predicate).__name__}"
+        if category_override:
+            category_override = {k: f"biolink:{resolve_association_class(v, predicate).__name__}" for k, v in category_override.items()}
     names: list[str] = lf.collect_schema().names()
     subject_col: str = "subject_category" if "subject_category" in names else "subject category"
     object_col: str = "object_category" if "object_category" in names else "object category"
     sr: pl.Expr = pl.col(subject_col).str.replace("biolink:", "").replace(cat_role).fill_null("")
     or_: pl.Expr = pl.col(object_col).str.replace("biolink:", "").replace(cat_role).fill_null("")
-    return lf.with_columns(pl.concat_list(pl.concat_str([sr, pl.lit("|"), or_]).replace_strict(edge_lookup, default=default)).alias("category"))
+    derived: pl.Expr = pl.concat_str([sr, pl.lit("|"), or_]).replace_strict(edge_lookup, default=default)
+    if category_override:
+        # Key on the RAW object category: the role rollup above collapses exactly the
+        # distinction (Disease vs PhenotypicFeature) the override exists to preserve.
+        hit: pl.Expr = pl.col(object_col).str.replace("biolink:", "").replace_strict(category_override, default=None, return_dtype=pl.String)
+        derived = pl.when(hit.is_not_null()).then(hit).otherwise(derived)
+    return lf.with_columns(pl.concat_list(derived).alias("category"))
 
 
 def prune_to_class(lf: pl.LazyFrame) -> pl.LazyFrame:
@@ -1177,7 +1193,7 @@ class Tcode(Section):
             [
                 op
                 for x in self.annotations
-                for op in [*self.encoding(x, x.annotation.lower()), *([(split_list, (x.annotation.lower(), x.split_by))] if x.split_by else [])]
+                for op in [*self.encoding(x, x.annotation), *([(split_list, (x.annotation, x.split_by))] if x.split_by else [])]
             ]
             if self.annotations
             else None,
@@ -1297,9 +1313,13 @@ class Tcode(Section):
         study_name: str | None = sheet if sheet is not None else Path(self.source.local).name
         if study_name == study_id:
             study_name = None
+        # `use_enum_values` stores the override's enum keys/values as plain strings.
+        category_override: dict[str, str] | None = (
+            {obj: f"biolink:{pinned}" for obj, pinned in self.statement.category_override.items()} if self.statement.category_override else None
+        )
         return [
             (value, ("predicate", "biolink:" + self.statement.predicate)),
-            (edge_category, ("biolink:" + self.statement.predicate,)),
+            (edge_category, ("biolink:" + self.statement.predicate, category_override)),
             (value, ("knowledge_level", knowledge_level)),
             (value, ("agent_type", agent_type)),
             # Retrieval provenance lives only in the nested `sources` list (Biolink

{tablassert-14.0.0 → tablassert-15.0.0}/src/tablassert/models.py

@@ -17,9 +17,11 @@ from tablassert.biolink import (
     UNSATISFIABLE_EDGE_FIELDS,
     AgentTypes,
     Categories,
+    EdgeCategories,
     KnowledgeLevels,
     Predicates,
     Qualifiers,
+    resolve_association_class,
 )
 from tablassert.coerce import coerced_target
 from tablassert.enums import (
@@ -435,6 +437,14 @@ class Statement(TablaBase):
     object: NodeEncoding = Field(..., description="Object node encoding and mapping configuration.")
     predicate: Predicates = Field(Predicates.RELATED_TO, description="Predicate connecting subject and object nodes.")
     qualifiers: list[Qualifier] | None = Field(None, description="Optional qualifier nodes attached to the statement.")
+    category_override: dict[Categories, EdgeCategories] | None = Field(
+        None,
+        description=(
+            "Optional per-object-category association-class override: maps a resolved object category (bare name, e.g. `Disease`) "
+            "to the association category its rows carry (e.g. `EntityToDiseaseAssociation`), used in place of the derived "
+            "(subject, object) pair lookup. Rows whose object category is absent from the map derive as before."
+        ),
+    )
 
     @model_validator(mode="after")
     def reject_duplicate_qualifiers(self: Self) -> Self:
@@ -458,6 +468,30 @@ class Statement(TablaBase):
             seen.add(key)
         return self
 
+    @model_validator(mode="after")
+    def warn_when_an_override_is_demoted_by_the_predicate(self: Self) -> Self:
+        """Warn when a pinned association class cannot carry the section predicate.
+
+        A ``category_override`` value still passes through
+        :func:`biolink.resolve_association_class` at build time: when the pinned class
+        restricts its ``predicate`` slot and the section predicate is not in it, the
+        emitted category silently walks up to an ancestor -- taking every subclass-only
+        slot the author pinned the class *for* with it. The value is never lost (the
+        reconciliation keeps the edge valid), so this is a warning, not an error.
+        """
+        for obj_category, pinned in (self.category_override or {}).items():
+            # `use_enum_values` stores both sides as plain strings.
+            resolved: str = resolve_association_class(f"biolink:{pinned}", f"biolink:{self.predicate}").__name__
+            if resolved != pinned:
+                warnings.warn(
+                    f"category_override pins `{pinned}` for `{obj_category}` objects, but that class does not accept "
+                    f"predicate `{self.predicate}`, so those rows are emitted as `{resolved}` instead -- any slots only "
+                    f"`{pinned}` declares are pruned off the edge.",
+                    BiolinkRelocationWarning,
+                    stacklevel=2,
+                )
+        return self
+
 
 def validate_infores_curie(value: str, code: TablassertErrorCodes) -> str:
     """Validate an ``infores:`` CURIE used for Biolink knowledge-source fields."""
@@ -674,7 +708,13 @@ class Annotation(Encoding):
     @field_validator("annotation", mode="after")
     @classmethod
     def clean_annotation(cls, annotation: str) -> str:
-        return annotation.lower().strip()
+        cleaned: str = annotation.strip()
+        lowered: str = cleaned.lower()
+        # Allow-listed slots may carry uppercase (Biolink's ``FDA_regulatory_approvals``):
+        # any casing the author declares canonicalizes onto the allow-listed spelling
+        # verbatim, so the emitted edge field preserves its case exactly instead of being
+        # lowercased into an unknown name.
+        return next((field for field in ALLOWED_EDGE_FIELDS if field.lower() == lowered), lowered)
 
     @model_validator(mode="after")
     def reject_disabled_annotations(self: Self) -> Self: