tablassert 12.0.0__tar.gz → 12.1.0__tar.gz

{tablassert-12.0.0 → tablassert-12.1.0}/PKG-INFO

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

{tablassert-12.0.0 → tablassert-12.1.0}/pyproject.toml

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

@@ -2288,10 +2288,11 @@ qualifier and evidence slot the specific class declared. build_and_audit reports
   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`.
 - 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.
+  `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.
 - `effect_size` / `effect_type` are deliberate Tablassert extras pending biolink-model#1774;
   `approval_ids` is a deliberate translator-ingest pass-through extra. All three are EXEMPT from
   the validity score: a `biolink_valid_pct` below 1.0 is never caused by these intentional fields.

{tablassert-12.0.0 → tablassert-12.1.0}/src/tablassert/biolink.py

@@ -695,11 +695,13 @@ def _scalar_types(annotation: Any) -> set[type]:
 def numeric_slot_kind(field: str) -> str | None:
     """Return ``"int"`` / ``"float"`` when a Biolink association slot has a numeric range.
 
-    Tablassert stringifies its numeric annotation columns for notation control, but
-    Biolink types ``p_value`` and ``adjusted_p_value`` as ``float`` and (with
-    ``biolink/biolink-model#1770``) ``supporting_study_size`` as ``int``. Those must be
-    emitted as real JSON numbers. Derived from the installed model so the answer
-    tracks whatever version is pinned.
+    Tablassert stringifies its numeric annotation columns for notation control (p-value
+    columns are ALWAYS scientific-notation strings, which Pydantic's lax validation
+    coerces back for the ``float``-typed ``p_value`` / ``adjusted_p_value`` slots), but
+    a non-p-value column that the installed model types ``int`` (``supporting_study_size``
+    once ``biolink/biolink-model#1770`` lands) or ``float`` must be emitted as a real
+    JSON number. Derived from the installed model so the answer tracks whatever version
+    is pinned.
 
     Args:
         field: Edge column name.

{tablassert-12.0.0 → tablassert-12.1.0}/src/tablassert/errors.py

@@ -23,6 +23,7 @@ TablassertErrorCodes = Literal[
     "graph-bad-infores",
     "override-bad-publication",
     "override-bad-upstream-infores",
+    "override-bad-upstream-urls",
     "provenance-bad-pmc-id",
     "provenance-missing-publication",
     "provenance-publication-and-override",

{tablassert-12.0.0 → tablassert-12.1.0}/src/tablassert/lib.py

@@ -469,7 +469,9 @@ def inline_supporting_study(lf: pl.LazyFrame, study_id: str, sheet: str | None,
     return out.drop(drop)
 
 
-def retrieval_sources(lf: pl.LazyFrame, primary: str, upstream: list[str], urls: list[str]) -> pl.LazyFrame:
+def retrieval_sources(
+    lf: pl.LazyFrame, primary: str, upstream: list[str], urls: list[str], upstream_urls: dict[str, list[str]] | None = None
+) -> pl.LazyFrame:
     """Add the Biolink ``sources`` retrieval-provenance column.
 
     ``upstream_resource_ids`` and ``source_record_urls`` have ``domain: retrieval
@@ -478,21 +480,30 @@ def retrieval_sources(lf: pl.LazyFrame, primary: str, upstream: list[str], urls:
     validation with ``extra_forbidden``.
 
     Mirrors ``build_association_knowledge_sources()`` from
-    ``translator-ingests/util/biolink.py``: the primary knowledge source carries the
-    source record URLs and lists the upstream resources, and each upstream resource
-    additionally appears as its own ``supporting_data_source`` entry.
+    ``translator-ingests/util/biolink.py``: the primary knowledge source lists the
+    upstream resources, and each upstream resource additionally appears as its own
+    ``supporting_data_source`` entry. By default the primary entry carries the
+    section's source record URLs; when ``upstream_urls`` is given, URL placement is
+    fully determined by that mapping instead -- each listed upstream entry carries
+    its own ``source_record_urls`` and the primary entry emits none (the primary is
+    the transforming resource, not a downloadable record).
 
     Args:
         lf: Source LazyFrame.
         primary: Infores CURIE of the primary knowledge source.
         upstream: Infores CURIEs of upstream/supporting data sources.
-        urls: Source record URLs for the primary entry.
+        urls: Source record URLs for the primary entry (ignored when ``upstream_urls`` is set).
+        upstream_urls: Optional per-upstream source record URLs keyed by infores CURIE.
 
     Returns:
         LazyFrame with a ``sources`` ``list[struct]`` column appended.
     """
-    entries: list[pl.Expr] = [_retrieval_source(primary, "primary_knowledge_source", upstream, urls)]
-    entries.extend(_retrieval_source(x, "supporting_data_source") for x in upstream)
+    if upstream_urls is not None:
+        entries: list[pl.Expr] = [_retrieval_source(primary, "primary_knowledge_source", upstream)]
+        entries.extend(_retrieval_source(x, "supporting_data_source", urls=upstream_urls.get(x)) for x in upstream)
+    else:
+        entries = [_retrieval_source(primary, "primary_knowledge_source", upstream, urls)]
+        entries.extend(_retrieval_source(x, "supporting_data_source") for x in upstream)
     return lf.with_columns(pl.concat_list(entries).alias("sources"))
 
 
@@ -592,15 +603,19 @@ def clean_numeric(lf: pl.LazyFrame) -> pl.LazyFrame:
 def format_numeric(lf: pl.LazyFrame) -> pl.LazyFrame:
     """Normalize numeric annotation columns for output.
 
-    Columns that map to a numeric Biolink slot are emitted as real JSON numbers:
-    ``p_value`` and ``adjusted_p_value`` are typed ``float`` in the model (and
-    ``supporting_study_size`` ``integer`` once ``biolink/biolink-model#1770`` lands),
-    so writing ``"6.5200e-06"`` produces a file that strict consumers reject even
-    though Pydantic's lax mode happens to coerce it.
-
-    Columns with no numeric Biolink slot keep the controlled string notation --
-    p-value-like names use scientific (``{:.4e}``), others decimal general
-    (``{:.4g}``) -- because they end up in human-readable text (the inlined
+    P-value columns (any name containing ``p_value``) are always emitted as
+    controlled scientific-notation strings (``{:.4e}``, e.g. ``"1.0000e-03"``):
+    notation is part of the output contract (see the tutorial's edge example), and
+    shortest-repr JSON numbers would render the same values as ``0.0001`` / ``0.05``.
+    Biolink types ``p_value`` / ``adjusted_p_value`` as ``float``, but the validation
+    here and downstream runs in Pydantic's lax mode, which coerces the numeric string
+    back -- so the notation control costs no KGX validity.
+
+    Remaining numeric columns (``effect_size`` / ``supporting_study_size``) that a
+    future biolink model types ``int`` / ``float`` (e.g. once
+    ``biolink/biolink-model#1770`` / ``#1774`` land) are emitted as real JSON numbers;
+    today's untyped ones keep the controlled decimal general string notation
+    (``{:.4g}``) because they end up in human-readable text (the inlined
     ``StudyResult`` description or ``supporting_text``). Null values stay null.
 
     Args:
@@ -617,15 +632,20 @@ def format_numeric(lf: pl.LazyFrame) -> pl.LazyFrame:
     # Collection point: batch formatting for notation control.
     df: pl.DataFrame = lf.collect()
     for c in numeric_columns(df.columns):
-        kind: str | None = numeric_slot_kind(c)
-        if kind == "float":
-            df = df.with_columns(pl.col(c).cast(pl.Float64, strict=False).alias(c))
-            continue
-        if kind == "int":
-            df = df.with_columns(pl.col(c).cast(pl.Float64, strict=False).round().cast(pl.Int64, strict=False).alias(c))
-            continue
         df = df.with_columns(pl.col(c).cast(pl.Float64, strict=False).alias(c))
-        fmt: str = "{:.4e}" if "p_value" in c.lower() else "{:.4g}"
+        if "p_value" in c.lower():
+            # Scientific notation is the p-value output contract; the branch ordering is
+            # the guard, so the numeric-slot short-circuits below can never fire for
+            # these columns even though the model types them ``float``.
+            fmt: str = "{:.4e}"
+        else:
+            kind: str | None = numeric_slot_kind(c)
+            if kind == "float":
+                continue
+            if kind == "int":
+                df = df.with_columns(pl.col(c).round().cast(pl.Int64, strict=False).alias(c))
+                continue
+            fmt = "{:.4g}"
         formatted: list[str | None] = [None if v is None else fmt.format(v) for v in df[c].to_list()]
         df = df.with_columns(pl.Series(c, formatted))
     return df.lazy()
@@ -1132,6 +1152,11 @@ class Tcode(Section):
         # name, so a RIG and its edges can never disagree about the source identity.
         primary_knowledge_source: str | None = self.infores
         upstream_ids = override.upstream_resource_ids if override else upstream_resource_ids(self.provenance.repo)
+        upstream_urls: dict[str, list[str]] | None = (
+            {key: [str(u) for u in urls] for key, urls in override.upstream_source_record_urls.items()}
+            if override and override.upstream_source_record_urls is not None
+            else None
+        )
         knowledge_level = override.knowledge_level if override else self.provenance.knowledge_level
         agent_type = override.agent_type if override else self.provenance.agent_type
         publication_values = override.publications if override else [publication_curie(self.provenance.repo, self.provenance.publication or "")]
@@ -1151,8 +1176,12 @@ class Tcode(Section):
             (value, ("agent_type", agent_type)),
             # Retrieval provenance lives only in the nested `sources` list (Biolink
             # RetrievalSource); current translator-ingests emits no flat
-            # `primary_knowledge_source` scalar, so neither do we.
-            (retrieval_sources, (primary_knowledge_source, upstream_ids, [str(u) for u in self.source.url])) if primary_knowledge_source else None,
+            # `primary_knowledge_source` scalar, so neither do we. A per-upstream URL
+            # mapping (override.upstream_source_record_urls) re-homes the record URLs
+            # from the primary entry onto the matching supporting entries.
+            (retrieval_sources, (primary_knowledge_source, upstream_ids, [str(u) for u in self.source.url], upstream_urls))
+            if primary_knowledge_source
+            else None,
             (publications, (publication_values,)) if publication_values else None,
             # Prune first so class-rejected values are handed to the study rather than lost.
             (prune_to_class, ()),

{tablassert-12.0.0 → tablassert-12.1.0}/src/tablassert/models.py

@@ -119,7 +119,7 @@ class BaseSource(TablaBase):
     url: list[HttpUrl] = Field(
         ...,
         min_length=1,
-        description="One or more remote source URL(s) recorded as provenance; emitted in the edge `sources` list under the primary entry's `source_record_urls` list and in the RIG. Format-validated only; not fetched.",
+        description="One or more remote source URL(s) recorded as provenance; emitted in the edge `sources` list under the primary entry's `source_record_urls` list and in the RIG. When `provenance.override.upstream_source_record_urls` is set, these URLs serve the RIG only and the per-upstream mapping determines edge placement instead. Format-validated only; not fetched.",
     )
 
     rows: list[NonNegativeInt] | None = Field(None, description="Zero-based row indices kept after any row_slice crop.", examples=[[0, 2, 5]])
@@ -464,6 +464,11 @@ class ManualProvenance(TablaBase):
         description="Manual upstream source infores CURIEs emitted instead of the repo-derived source map; the sanctioned place for manual infores.",
         examples=[["infores:my-upstream"]],
     )
+    upstream_source_record_urls: dict[str, list[HttpUrl]] | None = Field(
+        None,
+        description="Per-upstream source record URLs keyed by infores CURIE; every key must appear in `upstream_resource_ids`. When set, the section's `source.url` values are NOT emitted on the primary `sources` entry (RIG use only) — each listed upstream supporting entry carries its own `source_record_urls` instead.",
+        examples=[{"infores:my-upstream": ["https://example.org/dataset"]}],
+    )
     publications: list[str] | None = Field(
         None,
         description="Publication CURIEs emitted verbatim; currently PMCID CURIEs are required for manual provenance.",
@@ -493,6 +498,19 @@ class ManualProvenance(TablaBase):
                 )
         return values
 
+    @model_validator(mode="after")
+    def upstream_urls_match_resource_ids(self: Self) -> Self:
+        if self.upstream_source_record_urls is None:
+            return self
+        for key in self.upstream_source_record_urls:
+            validate_infores_curie(key, "override-bad-upstream-urls")
+        unknown = sorted(set(self.upstream_source_record_urls) - set(self.upstream_resource_ids))
+        if unknown:
+            raise TablassertValidationError(
+                f"`upstream_source_record_urls` keys must appear in `upstream_resource_ids`, got {unknown}.", code="override-bad-upstream-urls"
+            )
+        return self
+
 
 class Provenance(TablaBase):
     repo: Repositories = Field(Repositories.PUBMED_CENTRAL, description="Publication identifier namespace prefix.")