@platforma-sdk/model 1.65.10 → 1.67.0

package/src/components/PlDatasetSelector/build_dataset_options.ts

@@ -0,0 +1,56 @@
+import type {
+  DatasetOption,
+  Option,
+  PColumnSelector,
+  PObjectSpec,
+} from "@milaboratories/pl-model-common";
+import type { DeriveLabelsOptions } from "../../labels/derive_distinct_labels";
+import type { RenderCtxBase } from "../../render";
+import { ColumnCollectionBuilder } from "../../columns/column_collection_builder";
+import { collectCtxColumnSnapshotProviders } from "../../columns/ctx_column_sources";
+import { buildRefMap, filterMatchesToOptions, findFilterColumns } from "./filter_discovery";
+
+export type BuildDatasetOptions = {
+  /** Which result pool columns qualify as datasets. Defaults to all. */
+  selector?: PColumnSelector | PColumnSelector[] | ((spec: PObjectSpec) => boolean);
+  /** Formatting options for filter labels. */
+  labelOptions?: DeriveLabelsOptions;
+};
+
+/**
+ * Usage:
+ * ```ts
+ * .output("datasetOptions", (ctx) => buildDatasetOptions(ctx))
+ * ```
+ */
+export function buildDatasetOptions(
+  ctx: RenderCtxBase,
+  opts?: BuildDatasetOptions,
+): DatasetOption[] | undefined {
+  const predicate = opts?.selector ?? (() => true);
+  const options = ctx.resultPool.getOptions(predicate, { refsWithEnrichments: true });
+  if (options.length === 0) return [];
+
+  const columnSources = collectCtxColumnSnapshotProviders(ctx);
+  const refMap = buildRefMap(ctx.resultPool.getSpecs().entries);
+  const pframeSpec = ctx.getService("pframeSpec");
+
+  return options.map((o: Option): DatasetOption => {
+    const datasetSpec = ctx.resultPool.getPColumnSpecByRef(o.ref);
+    if (!datasetSpec) return o;
+
+    const builder = new ColumnCollectionBuilder(pframeSpec);
+    for (const src of columnSources) builder.addSource(src);
+    const collection = builder.build({ anchors: { main: datasetSpec } });
+    if (!collection) return o;
+
+    try {
+      const matches = findFilterColumns(collection);
+      if (matches.length === 0) return o;
+      const filters = filterMatchesToOptions(matches, refMap, opts?.labelOptions);
+      return { ...o, filters };
+    } finally {
+      collection.dispose();
+    }
+  });
+}

package/src/components/PlDatasetSelector/filter_discovery.test.ts

@@ -0,0 +1,156 @@
+import { Annotation, createPlRef } from "@milaboratories/pl-model-common";
+import type { AxisSpec, PColumnSpec, PlRef, PObjectId } from "@milaboratories/pl-model-common";
+import { SpecDriver } from "@milaboratories/pf-spec-driver";
+import canonicalize from "canonicalize";
+import { afterEach, describe, expect, test } from "vitest";
+import type { ColumnSnapshot } from "../../columns/column_snapshot";
+import { ColumnCollectionBuilder } from "../../columns/column_collection_builder";
+import { buildRefMap, filterMatchesToOptions, findFilterColumns } from "./filter_discovery";
+
+const drivers: SpecDriver[] = [];
+
+function createSpecFrameCtx() {
+  const driver = new SpecDriver();
+  drivers.push(driver);
+  return driver;
+}
+
+afterEach(async () => {
+  for (const driver of drivers) await driver.dispose();
+  drivers.length = 0;
+});
+
+function axis(name: string): AxisSpec {
+  return { name, type: "String" } as AxisSpec;
+}
+
+function spec(
+  name: string,
+  axesSpec: AxisSpec[],
+  annotations: Record<string, string> = {},
+): PColumnSpec {
+  return { kind: "PColumn", name, valueType: "Int", axesSpec, annotations } as PColumnSpec;
+}
+
+function snap(id: string, s: PColumnSpec): ColumnSnapshot<PObjectId> {
+  return { id: id as PObjectId, spec: s, dataStatus: "ready", data: { get: () => ({}) as never } };
+}
+
+// anchor defines the key space: [sample, gene]
+const anchorAxes = [axis("sample"), axis("gene")];
+const anchorSpec = spec("anchor", anchorAxes);
+const anchorSnap = snap("anchor-id", anchorSpec);
+
+describe("findFilterColumns", () => {
+  test("returns columns with pl7.app/isSubset annotation", () => {
+    const filter = snap("f1", spec("filter1", [axis("sample")], { [Annotation.IsSubset]: "true" }));
+    const regular = snap("r1", spec("regular1", [axis("sample")]));
+
+    const builder = new ColumnCollectionBuilder(createSpecFrameCtx());
+    builder.addSource([filter, regular, anchorSnap]);
+    const collection = builder.build({ anchors: { main: anchorSpec } })!;
+
+    const results = findFilterColumns(collection);
+    expect(results.every((m) => m.column.spec.name !== "regular1")).toBe(true);
+    expect(results.some((m) => m.column.spec.name === "filter1")).toBe(true);
+  });
+
+  test("axes subset: excludes filter whose axes are not a subset of anchor axes", () => {
+    // filter with axis "other" — not a subset of anchor axes [sample, gene]
+    const badFilter = snap(
+      "f2",
+      spec("bad-filter", [axis("other")], { [Annotation.IsSubset]: "true" }),
+    );
+
+    const builder = new ColumnCollectionBuilder(createSpecFrameCtx());
+    builder.addSource([badFilter, anchorSnap]);
+    const collection = builder.build({ anchors: { main: anchorSpec } })!;
+
+    const results = findFilterColumns(collection);
+    expect(results.every((m) => m.column.spec.name !== "bad-filter")).toBe(true);
+  });
+
+  test("empty result when no filters exist", () => {
+    const regular = snap("r1", spec("regular1", [axis("sample")]));
+
+    const builder = new ColumnCollectionBuilder(createSpecFrameCtx());
+    builder.addSource([regular, anchorSnap]);
+    const collection = builder.build({ anchors: { main: anchorSpec } })!;
+
+    expect(findFilterColumns(collection)).toHaveLength(0);
+  });
+});
+
+describe("buildRefMap", () => {
+  test("maps canonicalized PlRef to original ref", () => {
+    const ref1 = createPlRef("b1", "out1");
+    const ref2 = createPlRef("b2", "out2", true);
+    const entries = [{ ref: ref1 }, { ref: ref2 }];
+
+    const map = buildRefMap(entries);
+
+    expect(map.get(canonicalize(ref1)! as PObjectId)).toBe(ref1);
+    expect(map.get(canonicalize(ref2)! as PObjectId)).toBe(ref2);
+    expect(map.size).toBe(2);
+  });
+
+  test("returns empty map for empty entries", () => {
+    expect(buildRefMap([]).size).toBe(0);
+  });
+});
+
+describe("filterMatchesToOptions", () => {
+  test("converts filter matches to Option[] with derived labels", () => {
+    const filterRef1 = createPlRef("b1", "filter-top1000");
+    const filterRef2 = createPlRef("b1", "filter-highconf");
+
+    // Build ref map from entries (simulating result pool)
+    const refMap = buildRefMap([
+      { ref: anchorSnap.id as unknown as PlRef }, // anchor — won't be looked up
+      { ref: filterRef1 },
+      { ref: filterRef2 },
+    ]);
+
+    // Build filter specs with isSubset annotation
+    const filterSpec1 = spec("filter1", [axis("sample")], { [Annotation.IsSubset]: "true" });
+    const filterSpec2 = spec("filter2", [axis("sample")], { [Annotation.IsSubset]: "true" });
+
+    // Use the canonical PlRef as the PObjectId (matches how result pool works)
+    const f1Snap = snap(canonicalize(filterRef1)! as string, filterSpec1);
+    const f2Snap = snap(canonicalize(filterRef2)! as string, filterSpec2);
+
+    const builder = new ColumnCollectionBuilder(createSpecFrameCtx());
+    builder.addSource([f1Snap, f2Snap, anchorSnap]);
+    const collection = builder.build({ anchors: { main: anchorSpec } })!;
+
+    const matches = findFilterColumns(collection);
+    expect(matches.length).toBe(2);
+
+    const options = filterMatchesToOptions(matches, refMap);
+    expect(options).toHaveLength(2);
+    // Each option has a ref and label
+    for (const opt of options) {
+      expect(opt.ref).toBeDefined();
+      expect(opt.label).toBeDefined();
+      expect(typeof opt.label).toBe("string");
+    }
+  });
+
+  test("returns empty array for empty matches", () => {
+    expect(filterMatchesToOptions([], new Map())).toEqual([]);
+  });
+
+  test("throws when ref not found in map", () => {
+    const filterSpec1 = spec("orphan", [axis("sample")], { [Annotation.IsSubset]: "true" });
+    const f1Snap = snap("orphan-id", filterSpec1);
+
+    const builder = new ColumnCollectionBuilder(createSpecFrameCtx());
+    builder.addSource([f1Snap, anchorSnap]);
+    const collection = builder.build({ anchors: { main: anchorSpec } })!;
+
+    const matches = findFilterColumns(collection);
+    expect(matches.length).toBe(1);
+
+    expect(() => filterMatchesToOptions(matches, new Map())).toThrow(/no PlRef found/);
+  });
+});

package/src/components/PlDatasetSelector/filter_discovery.ts

@@ -0,0 +1,77 @@
+import { Annotation } from "@milaboratories/pl-model-common";
+import type { Option, PlRef, PObjectId } from "@milaboratories/pl-model-common";
+import canonicalize from "canonicalize";
+import type {
+  AnchoredColumnCollection,
+  ColumnMatch,
+} from "../../columns/column_collection_builder";
+import {
+  deriveDistinctLabels,
+  type DeriveLabelsOptions,
+  type Entry,
+} from "../../labels/derive_distinct_labels";
+
+/**
+ * Matches columns annotated `pl7.app/isSubset: "true"` whose axes ⊆ anchor axes.
+ *
+ * The axes-subset constraint is enforced by `mode: "enrichment"`, which sets
+ * `allowFloatingHitAxes: false` — every axis of the matched column must be
+ * present in the anchor's axes. See `matchingModeToConstraints()` in
+ * `column_collection_builder.ts`.
+ */
+export function findFilterColumns(collection: AnchoredColumnCollection): ColumnMatch[] {
+  return collection.findColumns({
+    mode: "enrichment",
+    include: {
+      annotations: { [Annotation.IsSubset]: "true" },
+    },
+  });
+}
+
+/**
+ * Derive labeled options from filter column matches, for use in DatasetOption.filters.
+ *
+ * @param matches - from findFilterColumns()
+ * @param refsByObjectId - from {@link buildRefMap}
+ * @param labelOptions - forwarded to deriveDistinctLabels()
+ */
+export function filterMatchesToOptions(
+  matches: ColumnMatch[],
+  refsByObjectId: ReadonlyMap<PObjectId, PlRef>,
+  labelOptions?: DeriveLabelsOptions,
+): Option[] {
+  if (matches.length === 0) return [];
+
+  // Each ColumnMatch can be reached via multiple variants (different linker
+  // paths / qualifications). We emit one Option per variant so the user can
+  // pick a specific path — `deriveDistinctLabels` disambiguates labels by
+  // path.
+  const flattened = matches.flatMap((m) => m.variants.map((v) => ({ match: m, variant: v })));
+
+  const entries: Entry[] = flattened.map(({ match, variant }) => ({
+    spec: match.column.spec,
+    linkerPath: variant.path.map((p) => ({ spec: p.linker.spec })),
+  }));
+
+  const labels = deriveDistinctLabels(entries, labelOptions);
+
+  return flattened.map(({ match }, i) => {
+    const ref = refsByObjectId.get(match.column.id);
+    if (ref === undefined)
+      throw new Error(
+        `no PlRef found for filter column ${match.column.spec.name} (id: ${match.column.id})`,
+      );
+    return { ref, label: labels[i] };
+  });
+}
+
+/**
+ * Usage: `buildRefMap(ctx.resultPool.getSpecs().entries)`
+ */
+export function buildRefMap(entries: readonly { readonly ref: PlRef }[]): Map<PObjectId, PlRef> {
+  const map = new Map<PObjectId, PlRef>();
+  for (const entry of entries) {
+    map.set(canonicalize(entry.ref)! as PObjectId, entry.ref);
+  }
+  return map;
+}

package/src/components/PlDatasetSelector/index.ts

@@ -0,0 +1,2 @@
+export * from "./filter_discovery";
+export * from "./build_dataset_options";

package/src/components/index.ts

@@ -1,5 +1,6 @@
 export * from "./PFrameForGraphs";
 export * from "./PlAnnotations";
+export * from "./PlDatasetSelector";
 export * from "./PlDataTable";
 export * from "./PlMultiSequenceAlignment";
 export * from "./PlSelectionModel";

package/src/filters/distill.test.ts

@@ -188,4 +188,95 @@ describe("distillFilterSpec", () => {
     const filter: F = { type: "and", filters: [a, b] };
     expect(distillFilterSpec(filter)).toBeNull();
   });
+
+  // --- per-type required-field checks ---
+
+  it("keeps patternFuzzyContainSubsequence without optional fields", () => {
+    const filter: F = { type: "patternFuzzyContainSubsequence", column: "c1", value: "abc" };
+    expect(distillFilterSpec(filter)).toEqual(filter);
+  });
+
+  it("keeps patternFuzzyContainSubsequence when optional fields undefined", () => {
+    const filter: F = {
+      type: "patternFuzzyContainSubsequence",
+      column: "c1",
+      value: "abc",
+      maxEdits: undefined,
+      substitutionsOnly: undefined,
+      wildcard: undefined,
+    };
+    expect(distillFilterSpec(filter)).toEqual(filter);
+  });
+
+  it("preserves optional fields on patternFuzzyContainSubsequence when filled", () => {
+    const filter: F = {
+      type: "patternFuzzyContainSubsequence",
+      column: "c1",
+      value: "abc",
+      maxEdits: 2,
+      substitutionsOnly: true,
+      wildcard: "*",
+    };
+    expect(distillFilterSpec(filter)).toEqual(filter);
+  });
+
+  it("keeps lessThanColumn without optional minDiff", () => {
+    const filter: F = { type: "lessThanColumn", column: "c1", rhs: "c2" };
+    expect(distillFilterSpec(filter)).toEqual(filter);
+  });
+
+  it("returns null for lessThanColumn with missing required rhs", () => {
+    const filter: F = {
+      type: "lessThanColumn",
+      column: "c1",
+      rhs: undefined as unknown as string,
+    };
+    expect(distillFilterSpec(filter)).toBeNull();
+  });
+
+  it("returns null for ifNa with missing required replacement", () => {
+    const filter: F = {
+      type: "ifNa",
+      column: "c1",
+      replacement: undefined as unknown as string,
+    };
+    expect(distillFilterSpec(filter)).toBeNull();
+  });
+
+  // --- isFilledValue edge cases ---
+
+  it("returns null for empty-string value after trim", () => {
+    const filter: F = { type: "patternEquals", column: "c1", value: "   " };
+    expect(distillFilterSpec(filter)).toBeNull();
+  });
+
+  it("returns null for inSet with empty array", () => {
+    const filter: F = { type: "inSet", column: "c1", value: [] };
+    expect(distillFilterSpec(filter)).toBeNull();
+  });
+
+  it("returns null for inSet with array containing empty string", () => {
+    const filter: F = { type: "inSet", column: "c1", value: ["a", "  "] };
+    expect(distillFilterSpec(filter)).toBeNull();
+  });
+
+  it("keeps inSet with non-empty string items", () => {
+    const filter: F = { type: "inSet", column: "c1", value: ["a", "b"] };
+    expect(distillFilterSpec(filter)).toEqual(filter);
+  });
+
+  it("keeps equal with x=0 (falsy but filled)", () => {
+    const filter: F = { type: "equal", column: "c1", x: 0 };
+    expect(distillFilterSpec(filter)).toEqual(filter);
+  });
+
+  it("keeps isNA (single required column)", () => {
+    const filter: F = { type: "isNA", column: "c1" };
+    expect(distillFilterSpec(filter)).toEqual(filter);
+  });
+
+  it("returns null for isNA with missing column", () => {
+    const filter: F = { type: "isNA", column: undefined as unknown as string };
+    expect(distillFilterSpec(filter)).toBeNull();
+  });
 });

package/src/filters/distill.ts

@@ -1,4 +1,4 @@
-import { DistributiveKeys, UnionToTuples } from "@milaboratories/helpers";
+import { DistributiveKeys, isNil, UnionToTuples } from "@milaboratories/helpers";
 import {
   RootFilterSpec,
   type FilterSpec,
@@ -8,51 +8,6 @@ import { traverseFilterSpec } from "./traverse";
 import { InferFilterSpecLeaf } from "@milaboratories/pl-model-common";
 import { isEmpty } from "es-toolkit/compat";
 
-/** All possible field names that can appear in any FilterSpecLeaf variant. */
-type FilterSpecLeafKey = DistributiveKeys<FilterSpecLeaf<string>>;
-
-/** Compile-time check: every key in the tuple is a valid leaf key (via satisfies). */
-const KNOWN_LEAF_KEYS_TUPLE: UnionToTuples<FilterSpecLeafKey> = [
-  "n",
-  "x",
-  "rhs",
-  "type",
-  "value",
-  "column",
-  "minDiff",
-  "maxEdits",
-  "wildcard",
-  "replacement",
-  "substitutionsOnly",
-];
-const KNOWN_LEAF_KEYS: Set<FilterSpecLeafKey> = new Set(KNOWN_LEAF_KEYS_TUPLE);
-
-/** Returns true if the leaf is filled — type is defined and no required fields are undefined. */
-function isFilledLeaf<T>(node: FilterSpecLeaf<T>): boolean {
-  if (node.type == null) return false;
-  return !Object.values(node).some((value) => {
-    switch (typeof value) {
-      case "number":
-      case "boolean":
-        return false;
-      case "string":
-        return value.trim() === "";
-      default: // undefined, null, empty objects/arrays
-        return isEmpty(value);
-    }
-  });
-}
-
-function distillLeaf<T>(node: FilterSpecLeaf<T>): FilterSpecLeaf<T> {
-  const result: Record<string, unknown> = {};
-  for (const [key, value] of Object.entries(node)) {
-    if (KNOWN_LEAF_KEYS.has(key as FilterSpecLeafKey)) {
-      result[key] = value;
-    }
-  }
-  return result as FilterSpecLeaf<T>;
-}
-
 /**
  * Strips non-FilterSpec metadata (whitelist approach) and removes
  * unfilled leaves (type is undefined or any required field is undefined).
@@ -80,3 +35,104 @@ export function distillFilterSpec<
     not: (result) => (result === null ? null : ({ type: "not", filter: result } as R)),
   });
 }
+
+function distillLeaf<T>(node: FilterSpecLeaf<T>): FilterSpecLeaf<T> {
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(node)) {
+    if (KNOWN_LEAF_KEYS.has(key as FilterSpecLeafKey)) {
+      result[key] = value;
+    }
+  }
+  return result as FilterSpecLeaf<T>;
+}
+
+/** Returns true if the leaf is filled — type is defined and every required field per-type is filled. */
+function isFilledLeaf<T>(node: FilterSpecLeaf<T>): boolean {
+  if (isNil(node.type)) return false;
+  const required = REQUIRED_KEYS_BY_TYPE[node.type];
+  const record = node as Record<string, unknown>;
+  return required.every((key) => isFilledValue(record[key]));
+}
+
+/**
+ * Returns true if the value is considered "filled":
+ * - primitives (number, boolean): always true
+ * - string: non-empty after trim
+ * - array: non-empty AND every item is filled
+ * - plain object: non-empty AND every field value is filled
+ * - null/undefined: false
+ */
+function isFilledValue(value: unknown): boolean {
+  if (isNil(value)) return false;
+  switch (typeof value) {
+    case "number":
+    case "boolean":
+      return true;
+    case "string":
+      return value.trim() !== "";
+    default:
+      if (isEmpty(value)) return false;
+      if (Array.isArray(value)) return value.every(isFilledValue);
+      return Object.values(value as Record<string, unknown>).every(isFilledValue);
+  }
+}
+
+/** All possible field names that can appear in any FilterSpecLeaf variant. */
+type FilterSpecLeafKey = DistributiveKeys<FilterSpecLeaf<string>>;
+
+/** Leaf type discriminators (excludes the placeholder `undefined` variant). */
+type FilterSpecLeafType = Exclude<FilterSpecLeaf<unknown>, { type: undefined }>["type"];
+
+type LeafOfType<T extends FilterSpecLeafType> = Extract<FilterSpecLeaf<unknown>, { type: T }>;
+
+type RequiredKeys<O> = { [K in keyof O]-?: {} extends Pick<O, K> ? never : K }[keyof O];
+
+/** Required field keys of a given leaf variant (excluding the `type` discriminator). */
+type RequiredLeafKeys<T extends FilterSpecLeafType> = Exclude<RequiredKeys<LeafOfType<T>>, "type">;
+
+/** Exact per-type shape — adding a key not required by that variant becomes a type error. */
+type RequiredKeysByType = { readonly [T in FilterSpecLeafType]: readonly RequiredLeafKeys<T>[] };
+
+/** Compile-time check: every key in the tuple is a valid leaf key (via satisfies). */
+const KNOWN_LEAF_KEYS_TUPLE: UnionToTuples<FilterSpecLeafKey> = [
+  "n",
+  "x",
+  "rhs",
+  "type",
+  "value",
+  "column",
+  "minDiff",
+  "maxEdits",
+  "wildcard",
+  "replacement",
+  "substitutionsOnly",
+];
+const KNOWN_LEAF_KEYS: Set<FilterSpecLeafKey> = new Set(KNOWN_LEAF_KEYS_TUPLE);
+
+/** Required fields per leaf type. Optional fields (e.g. minDiff, maxEdits) excluded. */
+const REQUIRED_KEYS_BY_TYPE = {
+  isNA: ["column"],
+  isNotNA: ["column"],
+  ifNa: ["column", "replacement"],
+  patternEquals: ["column", "value"],
+  patternNotEquals: ["column", "value"],
+  patternContainSubsequence: ["column", "value"],
+  patternNotContainSubsequence: ["column", "value"],
+  patternMatchesRegularExpression: ["column", "value"],
+  patternFuzzyContainSubsequence: ["column", "value"],
+  inSet: ["column", "value"],
+  notInSet: ["column", "value"],
+  topN: ["column", "n"],
+  bottomN: ["column", "n"],
+  equal: ["column", "x"],
+  notEqual: ["column", "x"],
+  lessThan: ["column", "x"],
+  greaterThan: ["column", "x"],
+  lessThanOrEqual: ["column", "x"],
+  greaterThanOrEqual: ["column", "x"],
+  equalToColumn: ["column", "rhs"],
+  lessThanColumn: ["column", "rhs"],
+  greaterThanColumn: ["column", "rhs"],
+  lessThanColumnOrEqual: ["column", "rhs"],
+  greaterThanColumnOrEqual: ["column", "rhs"],
+} as const satisfies RequiredKeysByType;