@platforma-sdk/model 1.80.0 → 1.80.8

package/src/labels/linked_column_postfix.test.ts

@@ -0,0 +1,112 @@
+import { Annotation, type AxisSpec, type PColumnSpec } from "@milaboratories/pl-model-common";
+import { describe, expect, test } from "vitest";
+import { derivePostfixes } from "./linked_column_postfix";
+
+// Shared target axis: it's on the hit column, and every linker's hit-facing side carries it — this
+// is what lets `extractRoots` tell the source side (the "рут") from the target side.
+const TARGET: AxisSpec = { type: "String", name: "hitAxis" };
+
+const hit: PColumnSpec = {
+  kind: "PColumn",
+  name: "counts",
+  valueType: "Int",
+  axesSpec: [TARGET],
+  annotations: { [Annotation.Label]: "Counts" },
+} as PColumnSpec;
+
+/** A source-side axis, lives INSIDE a linker's axesSpec (never standalone). */
+function sourceAxis(name: string, label?: string, domain?: Record<string, string>): AxisSpec {
+  return {
+    type: "String",
+    name,
+    ...(domain ? { domain } : {}),
+    ...(label ? { annotations: { [Annotation.Label]: label } } : {}),
+  } as AxisSpec;
+}
+
+/** Linker column: bridges a source axis → the shared target axis; carries a LinkLabel. */
+function linker(linkLabel: string, src: AxisSpec, name = linkLabel): PColumnSpec {
+  return {
+    kind: "PColumn",
+    name,
+    valueType: "Int",
+    axesSpec: [src, TARGET],
+    annotations: { [Annotation.LinkLabel]: linkLabel },
+  } as PColumnSpec;
+}
+
+describe("prototype — structural postfix (difference of sources)", () => {
+  const axSample = sourceAxis("sampleId", "Sample");
+  const axClone = sourceAxis("cloneId", "Clone");
+
+  test("case 1 — same linker (label), different roots → postfix = root", () => {
+    const labels = derivePostfixes([
+      { stem: "Counts", hit, linkers: [linker("MapperA", axSample)] },
+      { stem: "Counts", hit, linkers: [linker("MapperA", axClone)] },
+    ]);
+    expect(labels).toEqual(["Counts via Sample", "Counts via Clone"]);
+  });
+
+  test("case 2 — different linkers, same root → postfix = linker", () => {
+    const labels = derivePostfixes([
+      { stem: "Counts", hit, linkers: [linker("MapperA", axSample)] },
+      { stem: "Counts", hit, linkers: [linker("MapperB", axSample)] },
+    ]);
+    expect(labels).toEqual(["Counts via MapperA", "Counts via MapperB"]);
+  });
+
+  test("case 3 — different linkers, different roots → root suffices (linker not added)", () => {
+    const labels = derivePostfixes([
+      { stem: "Counts", hit, linkers: [linker("MapperA", axSample)] },
+      { stem: "Counts", hit, linkers: [linker("MapperB", axClone)] },
+    ]);
+    expect(labels).toEqual(["Counts via Sample", "Counts via Clone"]);
+  });
+
+  test("roots share a Label but differ by domain → render only the differing domain key", () => {
+    const donorA = sourceAxis("donor", "Donor", { batch: "A" });
+    const donorB = sourceAxis("donor", "Donor", { batch: "B" });
+    const labels = derivePostfixes([
+      { stem: "Counts", hit, linkers: [linker("MapperA", donorA)] },
+      { stem: "Counts", hit, linkers: [linker("MapperA", donorB)] },
+    ]);
+    expect(labels).toEqual(["Counts via Donor[batch=A]", "Counts via Donor[batch=B]"]);
+  });
+
+  test("no collision → no postfix", () => {
+    const labels = derivePostfixes([
+      { stem: "Read counts" },
+      { stem: "Coverage", hit, linkers: [linker("MapperA", axSample)] },
+    ]);
+    expect(labels).toEqual(["Read counts", "Coverage"]);
+  });
+
+  test("collision only on a subset → bare row stays bare (direct column has no path)", () => {
+    const labels = derivePostfixes([
+      { stem: "Counts" }, // direct column, no path
+      { stem: "Counts", hit, linkers: [linker("MapperA", axSample)] },
+    ]);
+    expect(labels).toEqual(["Counts", "Counts via Sample"]);
+  });
+
+  test("mixed group — root+linker both needed globally; symmetric render, all unique", () => {
+    // A: MapperA+Sample, B: MapperA+Clone, C: MapperB+Clone
+    // root separates A from {B,C}; B vs C share root(Clone) → linker needed too.
+    const labels = derivePostfixes([
+      { stem: "Counts", hit, linkers: [linker("MapperA", axSample)] },
+      { stem: "Counts", hit, linkers: [linker("MapperA", axClone)] },
+      { stem: "Counts", hit, linkers: [linker("MapperB", axClone)] },
+    ]);
+    expect(labels).toEqual([
+      "Counts via Sample MapperA",
+      "Counts via Clone MapperA",
+      "Counts via Clone MapperB",
+    ]);
+  });
+
+  // Refinement (deferred): per-row minimal trim — row A only needs the root, so its ideal label is
+  // "Counts via Sample" without the redundant "MapperA". Requires an occurrence-count pass.
+  test.todo(
+    "per-row minimal trim: A should drop the non-load-bearing linker → 'Counts via Sample'",
+  );
+});

package/src/labels/linked_column_postfix.ts

@@ -0,0 +1,312 @@
+/**
+ * Structural postfix derivation for linked columns (phase 2 of `deriveDistinctLabels`).
+ *
+ * A linked column is
+ * reached by a CHAIN of linkers, and we distinguish two such columns by the same ideology the main
+ * algorithm uses — "find the minimal difference, escalate until unique" — over two dimensions:
+ *
+ *   - root:    the single source axis of the chain, derived from `linkers[0]` (one of its axesSpec).
+ *              This is "the source" — it's what we prefer to show ("difference of sources").
+ *   - linkers: the linker chain itself (by `LinkLabel`), a per-step fallback used only where roots
+ *              coincide.
+ *
+ * Nothing is stored redundantly: the caller passes the linker path (`linkers`) and the hit spec;
+ * root and every token are computed on the fly. The caller also supplies the `stem` (label+trace+
+ * quals from the existing single-entity machinery); this module only adds the path postfix, and
+ * only where stems collide.
+ */
+import {
+  Annotation,
+  canonicalizeJson,
+  getAxisId,
+  readAnnotation,
+  type AxisSpec,
+  type PColumnSpec,
+} from "@milaboratories/pl-model-common";
+import { isNil } from "es-toolkit";
+
+/**
+ * One entry to label: its stem plus the linker path that reached it (`linkers[0]` source-most) and
+ * the hit spec used to orient the chain. Plain columns pass neither.
+ */
+export type PostfixEntry = { stem: string; hit?: PColumnSpec; linkers?: PColumnSpec[] };
+
+/**
+ * One distinguishing piece of the postfix: the full source spec (axis or linker column — no info
+ * lost) plus `text`, the minimal text that sets it apart from the siblings (a label, or only the
+ * differing domain keys). Custom formatters may use `spec` freely; `text` is the default rendering.
+ */
+export type LinkerPart<Spec> = { spec: Spec; text: string };
+
+/** The distinguishing source of one column: its root axis (when it differs) + the linker chain. */
+export type LinkerParts = {
+  root?: LinkerPart<AxisSpec>;
+  linkers: LinkerPart<PColumnSpec>[];
+};
+
+/**
+ * Renders the postfix zone from the distinguishing sources. Default:
+ * `via ${[root, linkers.join(" > ")].filter(Boolean).join(" ")}` (using each piece's `text`).
+ * Returning `undefined` — or the empty string `""` — suppresses the postfix entirely (the column
+ * keeps just its stem); the two are treated identically.
+ */
+export type LinkerFormatter = (
+  parts: LinkerParts,
+  hit: PColumnSpec | undefined,
+  index: number,
+) => string | undefined;
+
+function defaultLinkerFormatter(parts: LinkerParts): string {
+  const chain = parts.linkers.map((l) => l.text).join(" > ");
+  const pieces = [parts.root?.text, chain || undefined].filter((p): p is string => !isNil(p));
+  return pieces.length === 0 ? "" : `via ${pieces.join(" ")}`;
+}
+
+type AxisIdentity = { label?: string } & Pick<AxisSpec, "name" | "domain" | "contextDomain">;
+
+function extractAxisIdentity(axis: AxisSpec): AxisIdentity {
+  const id = getAxisId(axis);
+  return {
+    label: readAnnotation(axis, Annotation.Label)?.trim() || undefined,
+    name: id.name,
+    domain: id.domain,
+    contextDomain: id.contextDomain,
+  };
+}
+
+/**
+ * A linker is named ONLY by its human label (`LinkLabel`/`Label`) — never by its technical column
+ * name. Returns `undefined` for an unlabeled linker, which callers treat as "not renderable": such a
+ * step is skipped, and disambiguation falls to another step or the root.
+ */
+function extractLinkerIdentity(linker: PColumnSpec): AxisIdentity | undefined {
+  const label = (
+    readAnnotation(linker, Annotation.LinkLabel) ?? readAnnotation(linker, Annotation.Label)
+  )?.trim();
+  return label ? { label, name: label } : undefined;
+}
+
+/** Domain keys where `mine` differs from at least one competitor. */
+function differingKeys(
+  mine: Record<string, string> | undefined,
+  others: (Record<string, string> | undefined)[],
+): string[] {
+  const my = mine ?? {};
+  const diffKeys = new Set<string>();
+  for (const o of others) {
+    const od = o ?? {};
+    for (const k of Object.keys(my)) {
+      if (my[k] !== od[k]) {
+        diffKeys.add(k);
+      }
+    }
+    for (const k of Object.keys(od)) {
+      if (my[k] !== od[k]) {
+        diffKeys.add(k);
+      }
+    }
+  }
+  return [...diffKeys];
+}
+
+function renderWithDomain(
+  base: string,
+  keys: string[],
+  domain: Record<string, string> | undefined,
+): string {
+  if (keys.length === 0) return base;
+  const d = domain ?? {};
+  const pairs = keys.map((k) => `${k}=${d[k] ?? "∅"}`).join(", ");
+  return `${base}[${pairs}]`;
+}
+
+/**
+ * Minimal token distinguishing `mine` from `others`: label → name → only the differing domain keys.
+ * Falls back to the bare label/name when indistinguishable at this dimension (another one covers it).
+ */
+function deriveToken(mine: AxisIdentity, others: AxisIdentity[]): string {
+  const base = mine.label ?? mine.name;
+  if (mine.label !== undefined && others.every((o) => o.label !== mine.label)) return mine.label;
+  if (others.every((o) => o.name !== mine.name)) return base;
+  const dk = differingKeys(
+    mine.domain,
+    others.map((o) => o.domain),
+  );
+  if (dk.length > 0) return renderWithDomain(base, dk, mine.domain);
+  const ck = differingKeys(
+    mine.contextDomain,
+    others.map((o) => o.contextDomain),
+  );
+  if (ck.length > 0) return renderWithDomain(base, ck, mine.contextDomain);
+  return base;
+}
+
+/**
+ * The chain's single root: the source-side axis of `linkers[0]`. A linker bridges two axis groups;
+ * the side facing the next hop (`linkers[1]`, or the hit for a single-linker chain) is the target,
+ * the other side is the source → its axis is the root. `undefined` if `linkers[0]` is not a
+ * well-formed two-group linker.
+ */
+export function extractRoot(hit: PColumnSpec, linkers: PColumnSpec[]): AxisSpec | undefined {
+  const first = linkers[0];
+  if (first === undefined) return undefined;
+  const axes = first.axesSpec;
+  if (axes.length !== 2) return undefined;
+  const second = linkers[1] ?? hit;
+  return axes.find((a) => !second.axesSpec.some((b) => b.name === a.name));
+}
+
+type Slot = { kind: "root" } | { kind: "linker"; i: number };
+
+const ABSENT = "__ABSENT__"; // sentinel for "this row has no value at this slot"
+
+/** A colliding group: entries + their derived roots + original indices + the postfix formatter. */
+type Group = {
+  entries: PostfixEntry[];
+  roots: (AxisSpec | undefined)[];
+  indices: number[];
+  format: LinkerFormatter;
+};
+
+function deriveSlotKey(group: Group, slot: Slot, row: number): string {
+  if (slot.kind === "root") {
+    const r = group.roots[row];
+    return r === undefined ? ABSENT : canonicalizeJson(getAxisId(r));
+  } else {
+    const l = group.entries[row].linkers?.[slot.i];
+    const id = l && extractLinkerIdentity(l);
+    return isNil(id) ? ABSENT : canonicalizeJson(id);
+  }
+}
+
+function deriveSlotToken(group: Group, slot: Slot, row: number): string | undefined {
+  if (slot.kind === "root") {
+    const r = group.roots[row];
+    if (r === undefined) return undefined;
+    const comp = group.roots
+      .filter((o, j) => j !== row && !isNil(o))
+      .map((o) => extractAxisIdentity(o!));
+    return deriveToken(extractAxisIdentity(r), comp);
+  }
+  const l = group.entries[row].linkers?.[slot.i];
+  const id = l && extractLinkerIdentity(l);
+  if (isNil(id)) return undefined; // unlabeled / absent linker → not renderable, skip
+  const comp = group.entries
+    .filter((_, j) => j !== row)
+    .map((e) => e.linkers?.[slot.i])
+    .map((x) => (x ? extractLinkerIdentity(x) : undefined))
+    .filter((x): x is AxisIdentity => !isNil(x));
+  return deriveToken(id, comp);
+}
+
+function getDiscriminates(group: Group, slot: Slot): boolean {
+  return new Set(group.entries.map((_, r) => deriveSlotKey(group, slot, r))).size > 1;
+}
+
+/** Render one row against a chosen slot set: the distinguishing root + linker pieces, formatted. */
+function renderRow(group: Group, slots: Slot[], row: number): string {
+  const rootSpec = group.roots[row];
+  const rootText = slots.some((s) => s.kind === "root")
+    ? deriveSlotToken(group, { kind: "root" }, row)
+    : undefined;
+  const root: LinkerPart<AxisSpec> | undefined =
+    rootSpec !== undefined && rootText !== undefined
+      ? { spec: rootSpec, text: rootText }
+      : undefined;
+
+  const linkers = slots
+    .filter((s): s is { kind: "linker"; i: number } => s.kind === "linker")
+    .sort((a, b) => a.i - b.i)
+    .map((s) => {
+      const spec = group.entries[row].linkers?.[s.i];
+      const text = deriveSlotToken(group, s, row);
+      return spec !== undefined && text !== undefined ? { spec, text } : undefined;
+    })
+    .filter((l): l is LinkerPart<PColumnSpec> => !isNil(l));
+
+  // No distinguishing pieces for this row → no postfix (don't invoke the formatter with empties).
+  if (root === undefined && linkers.length === 0) return "";
+  // A formatter may suppress the postfix by returning `undefined` or `""`; `|| ""` collapses both
+  // to the same empty value so neither counts as a distinguishing token during slot escalation.
+  return group.format({ root, linkers }, group.entries[row].hit, group.indices[row]) || "";
+}
+
+function renderAll(group: Group, slots: Slot[]): string[] {
+  return group.entries.map((_, r) => renderRow(group, slots, r));
+}
+
+function allUnique(rendered: string[]): boolean {
+  return new Set(rendered).size === rendered.length;
+}
+
+/**
+ * Minimal slot set that makes the group unique. Escalate by priority (root, then linkers by step),
+ * then drop any redundant slot; render every row symmetrically against the result.
+ *
+ * KNOWN LIMITATION (review point): symmetric render can over-decorate a row in a mixed group (e.g.
+ * `via Sample MapperA` where `via Sample` alone is already unique for that row). Per-row trimming is
+ * a generalized `dropRedundantLinkerSuffix`; naive greedy trimming is unstable, so it's deferred.
+ */
+function resolveGroup(
+  entries: PostfixEntry[],
+  indices: number[],
+  format: LinkerFormatter,
+): string[] {
+  const group: Group = {
+    entries,
+    roots: entries.map((e) =>
+      e.hit && e.linkers?.length ? extractRoot(e.hit, e.linkers) : undefined,
+    ),
+    indices,
+    format,
+  };
+  const maxLen = Math.max(0, ...entries.map((e) => e.linkers?.length ?? 0));
+
+  const slots: Slot[] = [
+    { kind: "root" },
+    ...Array.from({ length: maxLen }, (_, i): Slot => ({ kind: "linker", i })),
+  ];
+
+  const escalated = slots.reduce<Slot[]>(
+    (acc, slot) =>
+      allUnique(renderAll(group, acc)) || !getDiscriminates(group, slot)
+        ? acc
+        : (acc.push(slot), acc),
+    [],
+  );
+  const chosen = escalated.reduce<Slot[]>((acc, slot) => {
+    const trial = acc.filter((s) => s !== slot);
+    return allUnique(renderAll(group, trial)) ? trial : acc;
+  }, escalated);
+
+  return renderAll(group, chosen);
+}
+
+/**
+ * Full label per entry: `stem` plus, where stems collide, a minimal postfix distinguishing the
+ * linked columns by the difference between their sources.
+ */
+export function derivePostfixes(
+  entries: PostfixEntry[],
+  format: LinkerFormatter = defaultLinkerFormatter,
+): string[] {
+  const groups = entries.reduce<Map<string, number[]>>(
+    (acc, e, idx) => acc.set(e.stem, [...(acc.get(e.stem) ?? []), idx]),
+    new Map(),
+  );
+
+  const postfix = [...groups.values()].reduce<Map<number, string>>((acc, idxs) => {
+    if (idxs.length < 2) return acc; // stem already unique — no postfix
+    const resolved = resolveGroup(
+      idxs.map((i) => entries[i]),
+      idxs,
+      format,
+    );
+    return idxs.reduce((m, i, k) => m.set(i, resolved[k]), acc);
+  }, new Map());
+
+  return entries.map((e, i) => {
+    const p = postfix.get(i);
+    return p ? `${e.stem} ${p}` : e.stem;
+  });
+}