@morscherlab/mint-sdk 1.2.0-beta.3 → 1.2.0-beta.5

package/src/composables/autoGroup/classify.ts

@@ -0,0 +1,205 @@
+import type { SampleClass, SampleClassKind, ClassDisposition } from '../../types/auto-group'
+import { classKey } from './classKey'
+import vocabData from './vocab.json'
+
+export interface ClassVocab {
+  blankPattern: RegExp
+  iqcPattern: RegExp
+  eqcPattern: RegExp
+  standardPattern: RegExp
+  standardAllow: Set<string>
+  spikeInPattern: RegExp
+  stockPattern: RegExp
+  /**
+   * Matrix lookup: lowercase token → canonical display name. Matching is
+   * case-insensitive, and several aliases can collapse to one display name
+   * (cell → Cells, medium → Medium).
+   */
+  matrixVocab: Map<string, string>
+  /** Lowercase polarity tokens → POS / NEG. */
+  ionizationModes: Map<string, 'POS' | 'NEG'>
+  /** Lowercase tokens that flag the next token as the organ subKind. */
+  tissueParentTokens: Set<string>
+}
+
+type VocabFile = typeof vocabData
+type IonMode = 'POS' | 'NEG'
+
+function compileVocab(data: VocabFile): ClassVocab {
+  return {
+    blankPattern: new RegExp(data.patterns.blank, 'i'),
+    iqcPattern: new RegExp(data.patterns.iqc, 'i'),
+    eqcPattern: new RegExp(data.patterns.eqc, 'i'),
+    standardPattern: new RegExp(data.patterns.standard, 'i'),
+    spikeInPattern: new RegExp(data.patterns.spikeIn, 'i'),
+    stockPattern: new RegExp(data.patterns.stock, 'i'),
+    standardAllow: new Set(data.standardAllow),
+    matrixVocab: new Map(Object.entries(data.matrixVocab)),
+    ionizationModes: new Map(
+      Object.entries(data.ionizationModes).map(([k, v]) => [k, v as IonMode]),
+    ),
+    tissueParentTokens: new Set(data.tissueParentTokens),
+  }
+}
+
+export const classVocab: ClassVocab = compileVocab(vocabData)
+
+function matrixCanonical(token: string, vocab: ClassVocab): string | undefined {
+  return vocab.matrixVocab.get(token.toLowerCase())
+}
+
+function isTissueParentToken(token: string, vocab: ClassVocab): boolean {
+  return vocab.tissueParentTokens.has(token.toLowerCase())
+}
+
+export interface DetectClassOptions {
+  vocab?: Partial<ClassVocab>
+  /** Per-sample explicit `sample_type` hint (e.g. from experiment design data). */
+  sampleTypeHints?: (string | undefined)[]
+}
+
+const DEFAULT_DISPOSITION: Record<SampleClassKind, ClassDisposition> = {
+  biological: 'group',
+  iqc: 'overlay',
+  eqc: 'overlay',
+  standard: 'overlay',
+  'spike-in': 'overlay',
+  stock: 'overlay',
+  blank: 'overlay',
+  unknown: 'group',
+}
+
+function classifyTokens(
+  tokens: string[],
+  vocab: ClassVocab,
+): { kind: SampleClassKind; subKind?: string; tagPositions: number[] } {
+  // First-match-wins ordering: Blank → IQC → EQC → Standard → SpikeIn → Stock → Biological → Unknown.
+  for (let i = 0; i < tokens.length; i++) {
+    if (vocab.blankPattern.test(tokens[i])) return { kind: 'blank', tagPositions: [i] }
+  }
+  for (let i = 0; i < tokens.length; i++) {
+    if (vocab.iqcPattern.test(tokens[i])) return { kind: 'iqc', tagPositions: [i] }
+  }
+  for (let i = 0; i < tokens.length; i++) {
+    if (vocab.eqcPattern.test(tokens[i])) return { kind: 'eqc', tagPositions: [i] }
+  }
+  for (let i = 0; i < tokens.length; i++) {
+    if (vocab.standardPattern.test(tokens[i]) || vocab.standardAllow.has(tokens[i])) {
+      return { kind: 'standard', tagPositions: [i] }
+    }
+  }
+  for (let i = 0; i < tokens.length; i++) {
+    if (vocab.spikeInPattern.test(tokens[i])) return { kind: 'spike-in', tagPositions: [i] }
+  }
+  for (let i = 0; i < tokens.length; i++) {
+    if (vocab.stockPattern.test(tokens[i])) return { kind: 'stock', tagPositions: [i] }
+  }
+  for (let i = 0; i < tokens.length; i++) {
+    const canonical = matrixCanonical(tokens[i], vocab)
+    if (canonical) {
+      const isTissueParent = isTissueParentToken(tokens[i], vocab)
+      const tagPositions = [i]
+      if (isTissueParent) {
+        // "Tissues"/"Tissue" is the parent group; tag the next token (organ name) as well.
+        if (i + 1 < tokens.length) tagPositions.push(i + 1)
+        return { kind: 'biological', subKind: 'Tissues', tagPositions }
+      }
+      // Non-parent matrix token: tag any immediately preceding "Tissues"/"Tissue" parent.
+      if (i > 0 && isTissueParentToken(tokens[i - 1], vocab)) {
+        tagPositions.unshift(i - 1)
+        return { kind: 'biological', subKind: 'Tissues', tagPositions }
+      }
+      return { kind: 'biological', subKind: canonical, tagPositions }
+    }
+  }
+  return { kind: 'unknown', tagPositions: [] }
+}
+
+/**
+ * LC-MS batches run positive- and negative-ion-mode acquisitions separately,
+ * and the two produce different feature tables that should never be grouped
+ * together. When a POS / NEG / positive / negative token is present we suffix
+ * it to the class label so the schema builder treats each mode as its own class.
+ */
+function ionizationModeFor(
+  tokens: string[],
+  vocab: ClassVocab,
+): { mode: IonMode; position: number } | undefined {
+  for (let i = 0; i < tokens.length; i++) {
+    const mode = vocab.ionizationModes.get(tokens[i].toLowerCase())
+    if (mode) return { mode, position: i }
+  }
+  return undefined
+}
+
+function labelFor(kind: SampleClassKind, subKind?: string): string {
+  const base: Record<SampleClassKind, string> = {
+    biological: 'Biological',
+    iqc: 'IQC',
+    eqc: 'EQC',
+    standard: 'Standard',
+    'spike-in': 'SpikeIn',
+    stock: 'Stock',
+    blank: 'Blank',
+    unknown: 'Unknown',
+  }
+  return subKind ? `${base[kind]} / ${subKind}` : base[kind]
+}
+
+/** Classify each tokenized sample into a SampleClass. */
+export function detectClass(
+  tokenizedSamples: string[][],
+  options: DetectClassOptions,
+): SampleClass[] {
+  const vocab = { ...classVocab, ...(options.vocab ?? {}) }
+  const hints = options.sampleTypeHints ?? []
+  const buckets = new Map<string, SampleClass>()
+
+  for (let i = 0; i < tokenizedSamples.length; i++) {
+    const hint = hints[i]?.toLowerCase()
+    let kind: SampleClassKind
+    let subKind: string | undefined
+    let tagPositions: number[]
+
+    if (hint === 'qc') {
+      kind = 'iqc'
+      tagPositions = []
+    } else if (hint === 'blank') {
+      kind = 'blank'
+      tagPositions = []
+    } else {
+      const r = classifyTokens(tokenizedSamples[i], vocab)
+      kind = r.kind
+      subKind = r.subKind
+      tagPositions = r.tagPositions
+    }
+
+    // Split classes by ionization mode (POS / NEG) so the two acquisitions get
+    // independent schemas even when they share a matrix and sample-type vocab.
+    const mode = ionizationModeFor(tokenizedSamples[i], vocab)
+    if (mode) {
+      subKind = subKind ? `${subKind} / ${mode.mode}` : mode.mode
+      if (!tagPositions.includes(mode.position)) tagPositions.push(mode.position)
+    }
+
+    const key = classKey({ kind, subKind })
+    const bucket = buckets.get(key)
+    if (bucket) {
+      bucket.members.push(i)
+      for (const p of tagPositions) {
+        if (!bucket.classTagPositions.includes(p)) bucket.classTagPositions.push(p)
+      }
+    } else {
+      buckets.set(key, {
+        kind,
+        subKind,
+        label: labelFor(kind, subKind),
+        members: [i],
+        classTagPositions: [...tagPositions],
+        disposition: DEFAULT_DISPOSITION[kind],
+      })
+    }
+  }
+
+  return [...buckets.values()]
+}

package/src/composables/autoGroup/colors.ts

@@ -0,0 +1,6 @@
+export const DEFAULT_COLORS = [
+  '#3B82F6', '#10B981', '#F59E0B', '#EF4444', '#8B5CF6',
+  '#EC4899', '#06B6D4', '#84CC16', '#F97316', '#6366F1',
+]
+
+export const QC_OVERLAY_COLOR = '#6B7280'

package/src/composables/autoGroup/columns.ts

@@ -0,0 +1,226 @@
+import type {
+  ColumnInfo,
+  ColumnRole,
+  ClassSchema,
+  NumericParse,
+  SampleClassKind,
+} from '../../types/auto-group'
+
+const NUMERIC_VALUE_UNIT = /^(\d+(?:dot\d+)?)([A-Za-z%/μ]+)$/
+const RATIO = /^(\d+)to(\d+)$/
+const RUN_ORDER_PATTERN = /^\d{2,4}[A-Z]?$/
+// Explicit replicate-token vocabulary: rep1 / Rep2 / REP3 / replicate1 / R1.
+// These tokens almost always identify a within-group replicate dimension that
+// users do NOT want in the default group key — e.g. ctrl/rep1, ctrl/rep2
+// should land in one Ctrl group with two replicates, not two singleton groups.
+const REPLICATE_TOKEN_PATTERN = /^(?:rep(?:licate)?|r)\d+$/i
+
+// Real-world LC-MS batches often have 30+ distinct conditions (subject IDs,
+// calibration levels, treatment combinations) in a single class. The earlier
+// cutoff of 20 routed everything above it to `ignore`, leaving such columns
+// out of the default groupBy — meaning a single giant group with no useful
+// split. 50 covers the common cases without making singleton-heavy columns
+// (sample IDs, timestamps) into factors.
+const DEFAULT_FACTOR_CARDINALITY_MAX = 50
+// Numerics with only a handful of distinct levels (e.g. `5min` / `10min`,
+// `1nM` / `5nM` / `25nM`) read as factor levels by default. Users opt into
+// numeric binning explicitly via the column popover when they want it.
+const LOW_CARDINALITY_NUMERIC_AS_FACTOR_MAX = 5
+
+export function parseNumeric(token: string): NumericParse | null {
+  const ratio = RATIO.exec(token)
+  if (ratio) {
+    const num = Number(ratio[1])
+    const den = Number(ratio[2])
+    if (den === 0) return null
+    return { value: num / den, unit: 'ratio', raw: token }
+  }
+  const m = NUMERIC_VALUE_UNIT.exec(token)
+  if (!m) return null
+  const valueStr = m[1].replace(/dot/g, '.')
+  const value = Number(valueStr)
+  if (Number.isNaN(value)) return null
+  return { value, unit: m[2], raw: token }
+}
+
+export interface InferRoleInput {
+  values: string[]
+  position: number
+  totalPositions: number
+  classSize: number
+}
+
+export function inferRole(input: InferRoleInput): ColumnRole {
+  const { values, position, totalPositions, classSize } = input
+  const unique = new Set(values)
+  const cardinality = unique.size
+
+  if (cardinality === 1) return 'constant'
+
+  // run-order: trailing position, all values match \d{2,4}[A-Z]? and cardinality is high.
+  if (position === totalPositions - 1) {
+    const allRunLike = values.every(v => RUN_ORDER_PATTERN.test(v))
+    if (allRunLike && cardinality >= classSize * 0.5) return 'run-order'
+  }
+
+  // numeric: every value parses as value+unit (or ratio).
+  const allNumeric = values.every(v => parseNumeric(v) !== null)
+  if (allNumeric) {
+    // A column like 5min / 10min reads as a factor in practice — users want to
+    // group on the timepoint, not bin it. Numeric binning UI is opt-in via the
+    // column popover for columns the user explicitly wants binned.
+    if (cardinality <= LOW_CARDINALITY_NUMERIC_AS_FACTOR_MAX) return 'factor'
+    return 'numeric'
+  }
+
+  // replicate by explicit name (rep1, Rep2, replicate3, R1) — regardless of
+  // cardinality. The cardinality-based ID_PATTERN check that used to live
+  // here (allId && cardinality >= classSize * 0.5) was removed: with the
+  // replicate pre-grouping pass running upstream, real replicates have
+  // already been collapsed by name, so a column like C1/C2/M1/M2 reaching
+  // role inference is almost certainly a distinct-condition factor, not a
+  // replicate. Users who want a residual replicate column can still mark
+  // it via the Workspace popover.
+  const allReplicateNamed = values.every(v => REPLICATE_TOKEN_PATTERN.test(v))
+  if (allReplicateNamed) return 'replicate'
+
+  if (cardinality <= DEFAULT_FACTOR_CARDINALITY_MAX) return 'factor'
+
+  return 'ignore'
+}
+
+/**
+ * Auto-detect a friendlier column name from the column's values + role.
+ * Returns null when nothing matches, so callers can fall back to "Token N".
+ *
+ * Heuristics are content-derived and deterministic. They cover the common
+ * LC-MS / proteomics naming conventions; users can override anything via
+ * the column popover (rename input).
+ */
+function inferColumnName(
+  values: string[],
+  uniqueValues: string[],
+  role: ColumnRole,
+): string | null {
+  if (uniqueValues.length === 0) return null
+
+  // Numeric+unit columns name themselves by the dominant unit category.
+  // We tally all values so a mixed-unit column (`1uL`, `1nM`) picks the
+  // majority rather than the first sample's unit.
+  const allNumeric = (role === 'numeric' || role === 'factor') && values.every(v => parseNumeric(v) !== null)
+  if (allNumeric) {
+    const categoryFor = (u: string): string | null => {
+      const ul = u.toLowerCase()
+      if (['min', 'sec', 's', 'hr', 'h', 'd', 'day', 'days', 'wk', 'week', 'hour', 'hours'].includes(ul)) return 'Timepoint'
+      if (['nm', 'um', 'mm', 'm', 'molar', 'mol'].includes(ul)) return 'Concentration'
+      if (['mg', 'g', 'kg', 'ng', 'ug', 'pg'].includes(ul)) return 'Mass'
+      if (['ml', 'l', 'ul', 'nl', 'pl'].includes(ul)) return 'Volume'
+      if (ul === '%') return 'Percentage'
+      if (['c', 'k', 'celsius', 'kelvin'].includes(ul)) return 'Temperature'
+      return null
+    }
+    const tally = new Map<string, number>()
+    for (const v of values) {
+      const p = parseNumeric(v)
+      const cat = p ? categoryFor(p.unit) : null
+      if (cat) tally.set(cat, (tally.get(cat) ?? 0) + 1)
+    }
+    let best: { cat: string; count: number } | null = null
+    for (const [cat, count] of tally) {
+      if (!best || count > best.count) best = { cat, count }
+    }
+    if (best && best.count >= values.length / 2) return best.cat
+  }
+
+  // Date-like all-digits tokens (YYMMDD or YYYYMMDD).
+  if (values.every(v => /^\d{6}$/.test(v) || /^\d{8}$/.test(v))) return 'Date'
+
+  // Run-order column = the trailing injection / acquisition sequence number.
+  if (role === 'run-order') return 'Injection #'
+
+  // Polarity tokens (POS/NEG/positive/negative).
+  if (values.every(v => /^(pos|neg|positive|negative)$/i.test(v))) return 'Polarity'
+
+  // Common biological matrices — kept in sync with classify.ts matrixVocab.
+  if (values.every(v => /^(plasma|serum|tissue|tissues|kidney|liver|tumor|urine|brain|muscle|adipose|csf|feces|faeces|cells?|media|medium|extract)$/i.test(v))) {
+    return 'Matrix'
+  }
+
+  // Experiment / study identifiers (exp268, study42, expt7).
+  if (values.every(v => /^(exp|expt|study)\d+$/i.test(v))) return 'Experiment'
+
+  // Operator / Username (2-3 uppercase letters per value, low cardinality).
+  // Constant or small-set 2-3-letter all-caps columns are almost always
+  // operator initials (LCK, JD, AB). Larger 2-4-letter columns could be
+  // project codes — disambiguation happens after the loop via the
+  // `Username → Project` post-pass.
+  if (uniqueValues.length <= 4 && values.every(v => /^[A-Z]{2,3}$/.test(v))) return 'Username'
+
+  return null
+}
+
+export function buildClassSchema(
+  tokenizedMembers: string[][],
+  classKind: SampleClassKind,
+  subKind: string | undefined,
+  classTagPositions: number[],
+): ClassSchema {
+  const totalPositions = tokenizedMembers[0]?.length ?? 0
+  const classSize = tokenizedMembers.length
+
+  const columns: ColumnInfo[] = []
+  const tagSet = new Set(classTagPositions)
+
+  for (let pos = 0; pos < totalPositions; pos++) {
+    const values = tokenizedMembers.map(t => t[pos] ?? '')
+    const uniqueValues = [...new Set(values)]
+
+    let role: ColumnRole
+    if (tagSet.has(pos) && uniqueValues.length === 1) {
+      // Only constant tag positions become class-tag; multi-valued positions (e.g. organ
+      // type within a Tissues class) fall through to normal role inference so they can be
+      // used as factor columns for grouping.
+      role = 'class-tag'
+    } else {
+      role = inferRole({ values, position: pos, totalPositions, classSize })
+    }
+
+    const numeric =
+      role === 'numeric'
+        ? {
+            byValue: Object.fromEntries(
+              uniqueValues
+                .map(v => [v, parseNumeric(v)] as const)
+                .filter((e): e is readonly [string, NumericParse] => e[1] !== null),
+            ),
+          }
+        : undefined
+
+    const inferredName = inferColumnName(values, uniqueValues, role)
+    columns.push({
+      index: pos,
+      name: inferredName ?? `Token ${pos + 1}`,
+      sourceIndices: [pos],
+      uniqueValues,
+      cardinality: uniqueValues.length,
+      role,
+      numeric,
+      // Legacy field
+      type: pos === 0 ? 'prefix' : 'suffix',
+    })
+  }
+
+  // Disambiguate Username when there are multiple constant 2-4 letter columns:
+  // first hit stays "Username", subsequent ones become "Project".
+  let usernameAssigned = false
+  for (const c of columns) {
+    if (c.name === 'Username') {
+      if (usernameAssigned) c.name = 'Project'
+      else usernameAssigned = true
+    }
+  }
+
+  const groupBy = columns.filter(c => c.role === 'factor').map(c => c.index)
+
+  return { classKind, subKind, columns, groupBy }
+}

package/src/composables/autoGroup/compose.ts

@@ -0,0 +1,244 @@
+import type {
+  AutoGroupResult,
+  ClassSchema,
+  ColumnInfo,
+  MetadataRow,
+  NumericBinning,
+  SampleClass,
+} from '../../types/auto-group'
+import type { SampleGroup } from '../../types/components'
+import type { TreeNode } from '../../types/componentLabTypes'
+import { DEFAULT_COLORS, QC_OVERLAY_COLOR } from './colors'
+import { classKey } from './classKey'
+
+export interface ComposeInput {
+  tokenizedSamples: string[][]
+  sampleNames: string[]
+  schemas: Record<string, ClassSchema>
+  classes: SampleClass[]
+  prefixClassLabels?: boolean
+  missingGroupName?: string
+}
+
+/** Apply the operation pipeline to a single raw token value:
+ *   numeric-parse → alias → exclude → bin
+ *  Returns null if the row is excluded.
+ */
+function applyOps(col: ColumnInfo, raw: string): string | null {
+  let value = raw
+
+  // alias (operates on raw source value)
+  if (col.ops?.alias && raw in col.ops.alias) {
+    value = col.ops.alias[raw]
+  }
+
+  // exclude (post-alias)
+  if (col.ops?.exclude?.includes(raw) || col.ops?.exclude?.includes(value)) {
+    return null
+  }
+
+  // bin (only when role === 'numeric' and binning.mode === 'binned')
+  if (col.role === 'numeric' && col.binning?.mode === 'binned') {
+    const parsed = col.numeric?.byValue[raw]
+    if (parsed && col.binning.edges) {
+      const bin = pickBin(parsed.value, col.binning)
+      if (bin !== null) value = bin
+    }
+  }
+
+  return value
+}
+
+function pickBin(value: number, b: NumericBinning): string | null {
+  if (!b.edges || b.edges.length === 0) return null
+  for (let i = 0; i < b.edges.length; i++) {
+    if (value < b.edges[i]) {
+      return b.labels?.[i] ?? `< ${b.edges[i]}`
+    }
+  }
+  const last = b.edges[b.edges.length - 1]
+  return b.labels?.[b.edges.length] ?? `> ${last}`
+}
+
+export function composeGroups(input: ComposeInput): AutoGroupResult {
+  const experimentalGroups: SampleGroup[] = []
+  const qcGroups: SampleGroup[] = []
+  const excludedSamples: string[] = []
+  const metadata: MetadataRow[] = []
+  let colorIdx = 0
+
+  // Class-label prefixing exists ONLY to disambiguate group names when several
+  // experimental classes could emit the same factor key (e.g. a Liver class and
+  // a Kidney class both producing "5min / High"). With a single experimental
+  // class there is nothing to disambiguate, so groups start directly at the
+  // user's first layer and the sample selector's major-group slot is not
+  // wasted on a constant root. When a prefix IS needed it should occupy ONE
+  // hierarchy layer, so prefer the short distinguishing `subKind` ("Liver")
+  // over the full label ("Biological / Liver") — falling back to the full
+  // label when two classes share a subKind (e.g. token-length splits).
+  const experimentalClasses = input.classes.filter(
+    c => c.disposition === 'group' && input.schemas[classKey(c)],
+  )
+  const classPrefix = new Map<SampleClass, string>()
+  if (input.prefixClassLabels !== false && experimentalClasses.length > 1) {
+    const shortCounts = new Map<string, number>()
+    for (const c of experimentalClasses) {
+      const short = c.subKind ?? c.label
+      shortCounts.set(short, (shortCounts.get(short) ?? 0) + 1)
+    }
+    for (const c of experimentalClasses) {
+      const short = c.subKind ?? c.label
+      classPrefix.set(c, (shortCounts.get(short) ?? 0) > 1 ? c.label : short)
+    }
+  }
+
+  // Nested hierarchy (class → groupBy levels → sample leaves) built alongside
+  // the flat groups. `treeIndex` lets repeated members reuse the same path node.
+  // PATH_SEP is a control char so it never collides with a real token value.
+  const PATH_SEP = String.fromCharCode(1)
+  const groupTree: TreeNode[] = []
+  const treeIndex = new Map<string, TreeNode>()
+  let treeColorIdx = 0
+
+  for (const cls of input.classes) {
+    const schema = input.schemas[classKey(cls)]
+    if (!schema) continue
+
+    if (cls.disposition === 'exclude') {
+      for (const m of cls.members) excludedSamples.push(input.sampleNames[m])
+      continue
+    }
+
+    // Per-class group map. group key built from enabled (groupBy) columns,
+    // joined with ' / ' for hierarchical display.
+    const groupMap = new Map<string, { name: string; samples: string[] }>()
+    const colByIdx = new Map(schema.columns.map(c => [c.index, c]))
+
+    // Only experimental (group) classes form the nested tree; overlay/QC stay flat.
+    const buildsTree = cls.disposition === 'group'
+    const runCol = schema.columns.find(c => c.role === 'run-order')
+    const classNodeId = classKey(cls)
+    let classNode: TreeNode | null = null
+
+    for (const m of cls.members) {
+      const tokens = input.tokenizedSamples[m]
+      const rowName = input.sampleNames[m]
+      let excluded = false
+      const fieldValues: Record<string, string> = {}
+
+      for (const col of schema.columns) {
+        const sourceValues = col.sourceIndices.map(idx => tokens[idx] ?? '')
+        const raw = sourceValues.join('_') // merged columns join their source tokens
+        const display = applyOps(col, raw)
+        if (display === null) {
+          excluded = true
+          break
+        }
+        fieldValues[col.displayName ?? col.name] = display
+      }
+
+      if (excluded) {
+        excludedSamples.push(rowName)
+        continue
+      }
+
+      const keyParts: string[] =
+        cls.disposition === 'group'
+          ? schema.groupBy.map(idx => {
+              const col = colByIdx.get(idx)!
+              return fieldValues[col.displayName ?? col.name]
+            })
+          : [cls.label]
+
+      // Prepend the class's short distinguishing label (see `classPrefix`
+      // above) so group names from different classes don't collide when they
+      // share a factor value (e.g. two tissue classes both emitting "5min").
+      //
+      // Only fires for disposition === 'group' classes with actual factor
+      // keyParts: overlay/exclude classes already use cls.label AS their
+      // single key part, so prefixing again would produce "IQC / IQC". The
+      // Unknown class also opts out — its label ("Unknown") adds no signal.
+      const hasMissingGroupPart =
+        input.missingGroupName &&
+        cls.disposition === 'group' &&
+        keyParts.some(part => part.trim().length === 0)
+      const prefix = cls.kind !== 'unknown' && keyParts.length > 0 ? classPrefix.get(cls) : undefined
+      const groupKey = hasMissingGroupPart
+        ? input.missingGroupName!
+        : prefix
+          ? `${prefix} / ${keyParts.join(' / ')}`
+          : keyParts.length > 0
+            ? keyParts.join(' / ')
+            : cls.label
+
+      const bucket = groupMap.get(groupKey)
+      if (bucket) {
+        bucket.samples.push(rowName)
+      } else {
+        groupMap.set(groupKey, { name: groupKey, samples: [rowName] })
+      }
+
+      metadata.push({ sampleName: rowName, fields: fieldValues, group: groupKey })
+
+      // Grow the nested tree: class root → one node per groupBy column → leaf.
+      if (buildsTree) {
+        if (!classNode) {
+          classNode = {
+            id: classNodeId,
+            label: cls.label,
+            badge: 0,
+            children: [],
+            metadata: { color: DEFAULT_COLORS[treeColorIdx++ % DEFAULT_COLORS.length] },
+          }
+          treeIndex.set(classNodeId, classNode)
+          groupTree.push(classNode)
+        }
+        classNode.badge = (classNode.badge as number) + 1
+        let cursor = classNode
+        let pathId = classNodeId
+        // Reuse the already-computed groupBy values (`keyParts`) so the tree
+        // levels can never drift from the flat group key.
+        for (const val of keyParts) {
+          pathId += PATH_SEP + val
+          let node = treeIndex.get(pathId)
+          if (!node) {
+            node = { id: pathId, label: val, badge: 0, children: [] }
+            cursor.children!.push(node)
+            treeIndex.set(pathId, node)
+          }
+          node.badge = (node.badge as number) + 1
+          cursor = node
+        }
+        // Injection value goes through the column's op pipeline (alias/exclude)
+        // via `fieldValues`, matching what every other surface shows.
+        const injection = runCol ? fieldValues[runCol.displayName ?? runCol.name] : undefined
+        const leaf: TreeNode = { id: pathId + PATH_SEP + rowName, label: rowName, type: 'sample' }
+        if (injection) {
+          leaf.badge = injection
+          leaf.metadata = { injection }
+        }
+        cursor.children!.push(leaf)
+      }
+    }
+
+    for (const { name, samples } of groupMap.values()) {
+      const color =
+        cls.disposition === 'overlay'
+          ? QC_OVERLAY_COLOR
+          : DEFAULT_COLORS[colorIdx++ % DEFAULT_COLORS.length]
+      const g: SampleGroup = { name, color, samples }
+      if (cls.disposition === 'overlay') qcGroups.push(g)
+      else experimentalGroups.push(g)
+    }
+  }
+
+  return {
+    groups: [...experimentalGroups, ...qcGroups],
+    experimentalGroups,
+    qcGroups,
+    metadata,
+    excludedSamples,
+    schemas: Object.values(input.schemas),
+    groupTree,
+  }
+}