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

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,
+  }
+}

package/src/composables/autoGroup/cooccurrence.ts

@@ -0,0 +1,46 @@
+import type { ClassSchema, MergeSuggestion } from '../../types/auto-group'
+
+const THRESHOLD = 0.95
+const MIN_CLASS_SIZE = 4
+
+function functionalDependency(rows: string[][], srcIdx: number, dstIdx: number): number {
+  const map = new Map<string, Set<string>>()
+  for (const row of rows) {
+    const a = row[srcIdx] ?? ''
+    const b = row[dstIdx] ?? ''
+    const set = map.get(a)
+    if (set) set.add(b)
+    else map.set(a, new Set([b]))
+  }
+  if (map.size === 0) return 0
+  let functional = 0
+  for (const set of map.values()) if (set.size === 1) functional++
+  return functional / map.size
+}
+
+export function findMerges(schema: ClassSchema, rows: string[][]): MergeSuggestion[] {
+  if (rows.length < MIN_CLASS_SIZE) return []
+
+  const out: MergeSuggestion[] = []
+  for (let i = 0; i < schema.columns.length - 1; i++) {
+    const a = schema.columns[i]
+    const b = schema.columns[i + 1]
+    if (a.role !== 'factor' && b.role !== 'factor') continue
+
+    const forward = functionalDependency(rows, a.index, b.index)
+    const backward = functionalDependency(rows, b.index, a.index)
+    if (forward < THRESHOLD || backward < THRESHOLD) continue
+
+    const merged = new Set(rows.map(r => `${r[a.index] ?? ''}_${r[b.index] ?? ''}`))
+    if (merged.size < 2) continue
+
+    out.push({
+      classKind: schema.classKind,
+      subKind: schema.subKind,
+      columnIndices: [a.index, b.index],
+      proposedName: `Column ${a.index + 1}–${b.index + 1}`,
+      confidence: Math.min(forward, backward),
+    })
+  }
+  return out
+}

package/src/composables/autoGroup/csv-shim.ts

@@ -0,0 +1,44 @@
+import type { ParsedCsvData } from '../../types/auto-group'
+
+function parseCSVLine(line: string, delimiter: string = ','): string[] {
+  const result: string[] = []
+  let current = ''
+  let inQuotes = false
+  for (let i = 0; i < line.length; i++) {
+    const char = line[i]
+    if (char === '"') {
+      if (inQuotes && line[i + 1] === '"') {
+        current += '"'
+        i++
+      } else {
+        inQuotes = !inQuotes
+      }
+    } else if (char === delimiter && !inQuotes) {
+      result.push(current.trim())
+      current = ''
+    } else {
+      current += char
+    }
+  }
+  result.push(current.trim())
+  return result
+}
+
+export function parseCSV(text: string): ParsedCsvData {
+  const lines = text.trim().split('\n')
+  if (lines.length < 2) throw new Error('CSV must have at least a header and one data row')
+  const firstLine = lines[0]
+  const csvDelimiter = firstLine.includes('\t') ? '\t' : ','
+  const headers = parseCSVLine(firstLine, csvDelimiter)
+  const rows: Record<string, string>[] = []
+  for (let i = 1; i < lines.length; i++) {
+    const values = parseCSVLine(lines[i], csvDelimiter)
+    if (values.length !== headers.length) continue
+    const row: Record<string, string> = {}
+    headers.forEach((h, idx) => { row[h] = values[idx] })
+    rows.push(row)
+  }
+  const sampleKeywords = ['sample', 'name', 'id', 'sample_name', 'samplename', 'file name', 'filename', 'file_name']
+  const sampleColumn = headers.find(h => sampleKeywords.includes(h.toLowerCase())) ?? headers[0]
+  return { columns: headers, rows, sampleColumn, delimiter: csvDelimiter }
+}

package/src/composables/autoGroup/fingerprint.ts

@@ -0,0 +1,63 @@
+import type { ClassSchema, SchemaFingerprint } from '../../types/auto-group'
+
+export function serializeFingerprint(schemas: ClassSchema[]): SchemaFingerprint {
+  return {
+    version: 1,
+    classes: schemas.map(s => ({
+      kind: s.classKind,
+      subKind: s.subKind,
+      tokenLength: s.tokenLength,
+      columns: s.columns.map(c => ({
+        name: c.displayName ?? c.name,
+        role: c.role ?? 'factor',
+        sourceIndices: c.sourceIndices,
+        binning: c.binning,
+        ops: c.ops,
+      })),
+      groupBy: s.groupBy,
+    })),
+  }
+}
+
+export function restoreFingerprint(
+  fp: SchemaFingerprint,
+  current: ClassSchema[],
+): ClassSchema[] {
+  return fp.classes.map(snap => {
+    // Match on token length too when the snapshot carries one, so length-split
+    // classes sharing a (kind, subKind) restore to the right schema. Snapshots
+    // saved before token-length splitting have no `tokenLength`; for those we
+    // match on (kind, subKind) and prefer the candidate with the same column
+    // count, so an old single-class fingerprint lands on the compatible split
+    // instead of throwing on the first (wrong-arity) hit.
+    const candidates = current.filter(
+      c =>
+        c.classKind === snap.kind &&
+        c.subKind === snap.subKind &&
+        (snap.tokenLength == null || c.tokenLength === snap.tokenLength),
+    )
+    const target =
+      candidates.find(c => c.columns.length === snap.columns.length) ?? candidates[0]
+    if (!target) {
+      throw new Error(
+        `Fingerprint class not present in current input: ${snap.kind}${snap.subKind ? '/' + snap.subKind : ''}`,
+      )
+    }
+    if (target.columns.length !== snap.columns.length) {
+      throw new Error(
+        `Saved schema expects ${snap.columns.length} columns, current data has ${target.columns.length} for class ${snap.kind}${snap.subKind ? '/' + snap.subKind : ''}. column count mismatch`,
+      )
+    }
+    return {
+      ...target,
+      groupBy: snap.groupBy,
+      columns: target.columns.map((col, i) => ({
+        ...col,
+        displayName: snap.columns[i].name,
+        role: snap.columns[i].role,
+        binning: snap.columns[i].binning,
+        ops: snap.columns[i].ops,
+      })),
+    }
+  })
+}

package/src/composables/autoGroup/index.ts

@@ -0,0 +1,22 @@
+export { splitMulti, pickPrimaryDelimiter } from './tokenize'
+export type { Delimiter } from './tokenize'
+export { detectClass, classVocab } from './classify'
+export type { ClassVocab, DetectClassOptions } from './classify'
+export { inferRole, parseNumeric, buildClassSchema } from './columns'
+export type { InferRoleInput } from './columns'
+export { findMerges } from './cooccurrence'
+export { composeGroups } from './compose'
+export type { ComposeInput } from './compose'
+export { serializeFingerprint, restoreFingerprint } from './fingerprint'
+export { composeTemplate } from './template'
+export type { TemplateOptions } from './template'
+export { DEFAULT_COLORS, QC_OVERLAY_COLOR } from './colors'
+export { classKey } from './classKey'
+export {
+  stripReplicateTokens,
+  preGroupReplicates,
+  expandGroupsWithReplicates,
+  expandTreeWithReplicates,
+} from './replicatePreGroup'
+export type { ReplicatePreGrouping } from './replicatePreGroup'
+export { splitByTokenLength } from './tokenLength'