@platforma-sdk/model 1.68.5 → 1.68.7

package/src/labels/derive_distinct_labels.test.ts

@@ -1,5 +1,10 @@
-import { Annotation, type PColumnSpec } from "@milaboratories/pl-model-common";
-import { expect, test } from "vitest";
+import {
+  Annotation,
+  type AxisQualification,
+  type PColumnSpec,
+  type PObjectId,
+} from "@milaboratories/pl-model-common";
+import { describe, expect, test } from "vitest";
 import { deriveDistinctLabels, type Entry, type Trace } from "./derive_distinct_labels";
 
 function tracesToSpecs(traces: Trace[]) {
@@ -284,8 +289,6 @@ test.each<{ name: string; traces: Trace[]; labels: string[]; forceTraceElements:
   },
 );
 
-// --- Entry with { spec, extraTrace } ---
-
 test("Entry with extraTrace (suffix, default) appends to labels", () => {
   const spec = createSpec({
     annotations: {
@@ -314,92 +317,84 @@ test("Entry with extraTrace position prefix prepends to labels", () => {
   expect(labels).toEqual(["P1", "P2"]);
 });
 
-// --- linkerPath ---
-
-test("linkerPath appends default 'via' suffix", () => {
+test("linkerPath appends default 'via' suffix when needed for uniqueness", () => {
   const entries: Entry[] = [
     {
       spec: createSpec({
-        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col1" }]) },
+        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col" }]) },
       }),
-      linkerPath: [
-        {
-          spec: createSpec({
-            annotations: { [Annotation.LinkLabel]: "MyLinker" },
-          }),
-        },
-      ],
     },
     {
       spec: createSpec({
-        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col2" }]) },
+        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col" }]) },
       }),
+      linkerPath: [{ spec: createSpec({ annotations: { [Annotation.LinkLabel]: "MyLinker" } }) }],
     },
   ];
   const labels = deriveDistinctLabels(entries);
-  expect(labels).toEqual(["Col1 via MyLinker", "Col2"]);
+  expect(labels).toEqual(["Col", "Col via MyLinker"]);
 });
 
 test("linkerPath with multiple steps joins with ' > '", () => {
   const entries: Entry[] = [
     {
       spec: createSpec({
-        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col1" }]) },
+        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col" }]) },
       }),
-      linkerPath: [
-        { spec: createSpec({ annotations: { [Annotation.LinkLabel]: "L1" } }) },
-        { spec: createSpec({ annotations: { [Annotation.LinkLabel]: "L2" } }) },
-      ],
     },
     {
       spec: createSpec({
-        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col2" }]) },
+        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col" }]) },
       }),
+      linkerPath: [
+        { spec: createSpec({ annotations: { [Annotation.LinkLabel]: "L1" } }) },
+        { spec: createSpec({ annotations: { [Annotation.LinkLabel]: "L2" } }) },
+      ],
     },
   ];
   const labels = deriveDistinctLabels(entries);
-  expect(labels).toEqual(["Col1 via L1 > L2", "Col2"]);
+  expect(labels).toEqual(["Col", "Col via L1 > L2"]);
 });
 
 test("linkerPath skips steps without labels", () => {
   const entries: Entry[] = [
     {
       spec: createSpec({
-        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col1" }]) },
+        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col" }]) },
       }),
-      linkerPath: [
-        { spec: createSpec() },
-        { spec: createSpec({ annotations: { [Annotation.LinkLabel]: "L2" } }) },
-      ],
     },
     {
       spec: createSpec({
-        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col2" }]) },
+        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col" }]) },
       }),
+      linkerPath: [
+        { spec: createSpec() },
+        { spec: createSpec({ annotations: { [Annotation.LinkLabel]: "L2" } }) },
+      ],
     },
   ];
   const labels = deriveDistinctLabels(entries);
-  expect(labels).toEqual(["Col1 via L2", "Col2"]);
+  expect(labels).toEqual(["Col", "Col via L2"]);
 });
 
 test("linkerPath with custom linkerLabelFormatter", () => {
   const entries: Entry[] = [
     {
       spec: createSpec({
-        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col1" }]) },
+        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col" }]) },
       }),
-      linkerPath: [{ spec: createSpec({ annotations: { [Annotation.LinkLabel]: "L1" } }) }],
     },
     {
       spec: createSpec({
-        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col2" }]) },
+        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col" }]) },
       }),
+      linkerPath: [{ spec: createSpec({ annotations: { [Annotation.LinkLabel]: "L1" } }) }],
     },
   ];
   const labels = deriveDistinctLabels(entries, {
-    linkerLabelFormatter: (linkerLabels) => `[${linkerLabels.join(", ")}]`,
+    formatters: { linker: (linkerLabels) => `[${linkerLabels.join(", ")}]` },
   });
-  expect(labels).toEqual(["Col1 [L1]", "Col2"]);
+  expect(labels).toEqual(["Col", "Col [L1]"]);
 });
 
 test("linkerPath with linkerLabelFormatter returning undefined suppresses suffix", () => {
@@ -417,7 +412,7 @@ test("linkerPath with linkerLabelFormatter returning undefined suppresses suffix
     },
   ];
   const labels = deriveDistinctLabels(entries, {
-    linkerLabelFormatter: () => undefined,
+    formatters: { linker: () => undefined },
   });
   expect(labels).toEqual(["Col1", "Col2"]);
 });
@@ -426,21 +421,140 @@ test("linkerPath falls back to Label when LinkLabel is absent", () => {
   const entries: Entry[] = [
     {
       spec: createSpec({
-        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col1" }]) },
+        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col" }]) },
       }),
-      linkerPath: [{ spec: createSpec({ annotations: { [Annotation.Label]: "FallbackLabel" } }) }],
     },
     {
       spec: createSpec({
-        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col2" }]) },
+        annotations: { [Annotation.Trace]: JSON.stringify([{ type: "t1", label: "Col" }]) },
       }),
+      linkerPath: [{ spec: createSpec({ annotations: { [Annotation.Label]: "FallbackLabel" } }) }],
     },
   ];
   const labels = deriveDistinctLabels(entries);
-  expect(labels).toEqual(["Col1 via FallbackLabel", "Col2"]);
+  expect(labels).toEqual(["Col", "Col via FallbackLabel"]);
+});
+
+test("formatters.native customizes label rendering", () => {
+  const s = ((label: string) =>
+    ({
+      kind: "PColumn",
+      name: "n",
+      valueType: "Int",
+      axesSpec: [],
+      annotations: { [Annotation.Label]: label },
+    }) as PColumnSpec)("Counts");
+  const labels = deriveDistinctLabels([{ spec: s }, { spec: s }], {
+    formatters: { native: (l) => `<<${l}>>` },
+  });
+  expect(labels).toEqual(["<<Counts>>", "<<Counts>>"]);
+});
+
+test("formatters.native returning undefined drops label entry", () => {
+  const traces: Trace[] = [[{ type: "t1", label: "X" }], [{ type: "t1", label: "Y" }]];
+  const labels = deriveDistinctLabels(tracesToSpecs(traces), {
+    includeNativeLabel: true,
+    formatters: { native: () => undefined },
+  });
+  expect(labels).toEqual(["X", "Y"]);
+});
+
+test("formatters.hitQualification customizes hit zone", () => {
+  const s = {
+    kind: "PColumn",
+    name: "n",
+    valueType: "Int",
+    axesSpec: [],
+    annotations: { [Annotation.Label]: "Expr" },
+  } as PColumnSpec;
+  const entries: Entry[] = [
+    {
+      spec: s,
+      qualifications: {
+        forQueries: {},
+        forHit: [{ axis: { name: "gene" }, contextDomain: { gene: "BRCA1" } }],
+      },
+    },
+    {
+      spec: s,
+      qualifications: {
+        forQueries: {},
+        forHit: [{ axis: { name: "gene" }, contextDomain: { gene: "TP53" } }],
+      },
+    },
+  ];
+  const labels = deriveDistinctLabels(entries, {
+    formatters: { hitQualification: (qs) => `<hit:${qs[0].contextDomain.gene}>` },
+  });
+  expect(labels).toEqual(["Expr <hit:BRCA1>", "Expr <hit:TP53>"]);
+});
+
+test("formatters.anchorQualification receives anchorId", () => {
+  const s = {
+    kind: "PColumn",
+    name: "n",
+    valueType: "Int",
+    axesSpec: [],
+    annotations: { [Annotation.Label]: "Counts" },
+  } as PColumnSpec;
+  const A = "A" as PObjectId;
+  const entries: Entry[] = [
+    {
+      spec: s,
+      qualifications: {
+        forQueries: { [A]: [{ axis: { name: "sample" }, contextDomain: { batch: "X" } }] },
+        forHit: [],
+      },
+    },
+    {
+      spec: s,
+      qualifications: {
+        forQueries: { [A]: [{ axis: { name: "sample" }, contextDomain: { batch: "Y" } }] },
+        forHit: [],
+      },
+    },
+  ];
+  const labels = deriveDistinctLabels(entries, {
+    formatters: {
+      anchorQualification: (id, qs) => `(${id}=${qs[0].contextDomain.batch})`,
+    },
+  });
+  expect(labels).toEqual(["Counts (A=X)", "Counts (A=Y)"]);
 });
 
-// --- addLabelAsSuffix ---
+test("formatters.linkerStepQualification controls inline step quals", () => {
+  const s = {
+    kind: "PColumn",
+    name: "n",
+    valueType: "Int",
+    axesSpec: [],
+    annotations: { [Annotation.Label]: "Counts" },
+  } as PColumnSpec;
+  const entries: Entry[] = [
+    {
+      spec: s,
+      linkerPath: [
+        {
+          spec: createSpec({ annotations: { [Annotation.LinkLabel]: "Mapper" } }),
+          qualifications: [{ axis: { name: "sample" }, contextDomain: { batch: "X" } }],
+        },
+      ],
+    },
+    {
+      spec: s,
+      linkerPath: [
+        {
+          spec: createSpec({ annotations: { [Annotation.LinkLabel]: "Mapper" } }),
+          qualifications: [{ axis: { name: "sample" }, contextDomain: { batch: "Y" } }],
+        },
+      ],
+    },
+  ];
+  const labels = deriveDistinctLabels(entries, {
+    formatters: { linkerStepQualification: (qs) => `(${qs[0].contextDomain.batch})` },
+  });
+  expect(labels).toEqual(["Counts via Mapper (X)", "Counts via Mapper (Y)"]);
+});
 
 test("addLabelAsSuffix places native label at the end", () => {
   const specs = tracesToSpecs([[{ type: "t1", label: "L1" }], [{ type: "t1", label: "L2" }]]);
@@ -451,8 +565,6 @@ test("addLabelAsSuffix places native label at the end", () => {
   expect(labels).toEqual(["L1 / Label", "L2 / Label"]);
 });
 
-// --- separator ---
-
 test("custom separator is used between label parts", () => {
   const specs = tracesToSpecs([
     [
@@ -472,16 +584,12 @@ test("custom separator is used between label parts", () => {
   expect(labels).toEqual(["A - X", "A - Y", "B - Y"]);
 });
 
-// --- single value ---
-
 test("single value gets its trace label", () => {
   const specs = tracesToSpecs([[{ type: "t1", label: "Only" }]]);
   const labels = deriveDistinctLabels(specs);
   expect(labels).toEqual(["Only"]);
 });
 
-// --- Unlabeled fallback ---
-
 test("Unlabeled fallback when no trace entries match", () => {
   // Two identical specs with identical traces — fallback path
   const spec = createSpec({
@@ -502,8 +610,6 @@ test("Unlabeled when no traces and no label", () => {
   expect(result.every((r) => r === "Unlabeled")).toBe(true);
 });
 
-// --- repeated type occurrences (secondaryTypes path) ---
-
 test("repeated type occurrences are used as secondary types", () => {
   // Two records where "t1" appears twice in each, with different labels on 2nd occurrence
   const specs = tracesToSpecs([
@@ -522,8 +628,6 @@ test("repeated type occurrences are used as secondary types", () => {
   expect(labels).toEqual(["A", "B"]);
 });
 
-// --- spec without Annotation.Label (only Trace) ---
-
 test("spec without native label uses only trace entries", () => {
   const specs = [
     createSpec({
@@ -557,3 +661,243 @@ test("includeNativeLabel with no native label does not break", () => {
   const labels = deriveDistinctLabels(specs, { includeNativeLabel: true });
   expect(labels).toEqual(["X", "Y"]);
 });
+
+describe("deriveDistinctLabels v2 — linker path & qualifications", () => {
+  function labeledSpec(label: string, name = "col"): PColumnSpec {
+    return {
+      kind: "PColumn",
+      name,
+      valueType: "Int",
+      axesSpec: [],
+      annotations: { [Annotation.Label]: label },
+    } as PColumnSpec;
+  }
+
+  function linkerSpec(label: string, name = "linker"): PColumnSpec {
+    return {
+      kind: "PColumn",
+      name,
+      valueType: "Int",
+      axesSpec: [],
+      annotations: { [Annotation.LinkLabel]: label },
+    } as PColumnSpec;
+  }
+
+  function qual(axis: string, ctx: Record<string, string> = {}): AxisQualification {
+    return { axis: { name: axis }, contextDomain: ctx };
+  }
+
+  const A = "anchor-main" as PObjectId;
+  const B = "anchor-other" as PObjectId;
+
+  test("linkerPath not appended when name alone is unique", () => {
+    const entries: Entry[] = [
+      { spec: labeledSpec("Read counts") },
+      { spec: labeledSpec("Coverage"), linkerPath: [{ spec: linkerSpec("Sample mapper") }] },
+    ];
+    expect(deriveDistinctLabels(entries)).toEqual(["Read counts", "Coverage"]);
+  });
+
+  test("linkerPath appended only when needed for uniqueness", () => {
+    const entries: Entry[] = [
+      { spec: labeledSpec("Read counts") },
+      { spec: labeledSpec("Read counts"), linkerPath: [{ spec: linkerSpec("Sample mapper") }] },
+    ];
+    expect(deriveDistinctLabels(entries)).toEqual(["Read counts", "Read counts via Sample mapper"]);
+  });
+
+  test("two linker paths → both get distinguishing via-suffix", () => {
+    const s = labeledSpec("Counts");
+    const entries: Entry[] = [
+      { spec: s, linkerPath: [{ spec: linkerSpec("Path A") }] },
+      { spec: s, linkerPath: [{ spec: linkerSpec("Path B") }] },
+    ];
+    expect(deriveDistinctLabels(entries)).toEqual(["Counts via Path A", "Counts via Path B"]);
+  });
+
+  test("multi-step paths joined with ' > '", () => {
+    const s = labeledSpec("Counts");
+    const entries: Entry[] = [
+      { spec: s, linkerPath: [{ spec: linkerSpec("Hub") }, { spec: linkerSpec("Tail X") }] },
+      { spec: s, linkerPath: [{ spec: linkerSpec("Hub") }, { spec: linkerSpec("Tail Y") }] },
+    ];
+    expect(deriveDistinctLabels(entries)).toEqual([
+      "Counts via Hub > Tail X",
+      "Counts via Hub > Tail Y",
+    ]);
+  });
+
+  test("hit qualifications used when nothing else differs", () => {
+    const s = labeledSpec("Expression");
+    const entries: Entry[] = [
+      { spec: s, qualifications: { forQueries: {}, forHit: [qual("gene", { gene: "BRCA1" })] } },
+      { spec: s, qualifications: { forQueries: {}, forHit: [qual("gene", { gene: "TP53" })] } },
+    ];
+    expect(deriveDistinctLabels(entries)).toEqual([
+      "Expression [gene=BRCA1]",
+      "Expression [gene=TP53]",
+    ]);
+  });
+
+  test("per-anchor qualifications named by anchor key", () => {
+    const s = labeledSpec("Counts");
+    const entries: Entry[] = [
+      {
+        spec: s,
+        qualifications: { forQueries: { [A]: [qual("sample", { batch: "X" })] }, forHit: [] },
+      },
+      {
+        spec: s,
+        qualifications: { forQueries: { [A]: [qual("sample", { batch: "Y" })] }, forHit: [] },
+      },
+    ];
+    expect(deriveDistinctLabels(entries)).toEqual([
+      "Counts [anchor-main: sample batch=X]",
+      "Counts [anchor-main: sample batch=Y]",
+    ]);
+  });
+
+  test("linker-step qualifications used to disambiguate identical linker labels", () => {
+    const s = labeledSpec("Counts");
+    const entries: Entry[] = [
+      {
+        spec: s,
+        linkerPath: [
+          { spec: linkerSpec("Mapper"), qualifications: [qual("sample", { batch: "X" })] },
+        ],
+      },
+      {
+        spec: s,
+        linkerPath: [
+          { spec: linkerSpec("Mapper"), qualifications: [qual("sample", { batch: "Y" })] },
+        ],
+      },
+    ];
+    expect(deriveDistinctLabels(entries)).toEqual([
+      "Counts via Mapper [sample batch=X]",
+      "Counts via Mapper [sample batch=Y]",
+    ]);
+  });
+
+  test("layers compose only as far as needed; no over-decoration", () => {
+    const entries: Entry[] = [
+      { spec: labeledSpec("Read counts") },
+      { spec: labeledSpec("Coverage") },
+      {
+        spec: labeledSpec("Coverage"),
+        qualifications: { forQueries: { [A]: [qual("sample", { batch: "X" })] }, forHit: [] },
+      },
+    ];
+    expect(deriveDistinctLabels(entries)).toEqual([
+      "Read counts",
+      "Coverage",
+      "Coverage [anchor-main: sample batch=X]",
+    ]);
+  });
+
+  test("hit and anchor qualifications combined when both needed", () => {
+    const s = labeledSpec("Counts");
+    const entries: Entry[] = [
+      {
+        spec: s,
+        qualifications: {
+          forQueries: { [A]: [qual("sample", { batch: "X" })] },
+          forHit: [qual("gene", { gene: "BRCA1" })],
+        },
+      },
+      {
+        spec: s,
+        qualifications: {
+          forQueries: { [A]: [qual("sample", { batch: "X" })] },
+          forHit: [qual("gene", { gene: "TP53" })],
+        },
+      },
+      {
+        spec: s,
+        qualifications: {
+          forQueries: { [A]: [qual("sample", { batch: "Y" })] },
+          forHit: [qual("gene", { gene: "BRCA1" })],
+        },
+      },
+    ];
+    expect(deriveDistinctLabels(entries)).toEqual([
+      "Counts [anchor-main: sample batch=X] [gene=BRCA1]",
+      "Counts [anchor-main: sample batch=X] [gene=TP53]",
+      "Counts [anchor-main: sample batch=Y] [gene=BRCA1]",
+    ]);
+  });
+
+  test("only distinctive anchor qualifications appear in the label", () => {
+    const s = labeledSpec("Counts");
+    const sharedB = [qual("project", { id: "P1" })];
+    const entries: Entry[] = [
+      {
+        spec: s,
+        qualifications: {
+          forQueries: { [A]: [qual("sample", { batch: "X" })], [B]: sharedB },
+          forHit: [],
+        },
+      },
+      {
+        spec: s,
+        qualifications: {
+          forQueries: { [A]: [qual("sample", { batch: "Y" })], [B]: sharedB },
+          forHit: [],
+        },
+      },
+    ];
+    expect(deriveDistinctLabels(entries)).toEqual([
+      "Counts [anchor-main: sample batch=X]",
+      "Counts [anchor-main: sample batch=Y]",
+    ]);
+  });
+
+  test("full decoration when every layer carries information", () => {
+    const sA: PColumnSpec = {
+      ...labeledSpec("Counts"),
+      annotations: {
+        [Annotation.Label]: "Counts",
+        [Annotation.Trace]: JSON.stringify([{ type: "stage", label: "RNAseq" }]),
+      },
+    } as PColumnSpec;
+    const sB: PColumnSpec = {
+      ...labeledSpec("Counts"),
+      annotations: {
+        [Annotation.Label]: "Counts",
+        [Annotation.Trace]: JSON.stringify([{ type: "stage", label: "ATACseq" }]),
+      },
+    } as PColumnSpec;
+    const entries: Entry[] = [
+      { spec: sA, linkerPath: [{ spec: linkerSpec("Mapper") }] },
+      {
+        spec: sA,
+        linkerPath: [{ spec: linkerSpec("Mapper") }],
+        qualifications: { forQueries: { [A]: [qual("sample", { batch: "X" })] }, forHit: [] },
+      },
+      { spec: sB, linkerPath: [{ spec: linkerSpec("Mapper") }] },
+    ];
+    expect(deriveDistinctLabels(entries)).toEqual([
+      "Counts / RNAseq via Mapper",
+      "Counts / RNAseq via Mapper [anchor-main: sample batch=X]",
+      "Counts / ATACseq via Mapper",
+    ]);
+  });
+
+  test("identical variants produce identical labels (cannot disambiguate)", () => {
+    const s = labeledSpec("Counts");
+    const entries: Entry[] = [{ spec: s }, { spec: s }];
+    expect(deriveDistinctLabels(entries)).toEqual(["Counts", "Counts"]);
+  });
+
+  test("axis-only qualification (no contextDomain) renders as axis name", () => {
+    const s = labeledSpec("Counts");
+    const entries: Entry[] = [
+      { spec: s, qualifications: { forQueries: { [A]: [qual("sample")] }, forHit: [] } },
+      { spec: s, qualifications: { forQueries: { [A]: [qual("gene")] }, forHit: [] } },
+    ];
+    expect(deriveDistinctLabels(entries)).toEqual([
+      "Counts [anchor-main: sample]",
+      "Counts [anchor-main: gene]",
+    ]);
+  });
+});