@morscherlab/mint-sdk 1.3.0 → 1.3.1

package/src/composables/autoGroup/classify.ts

@@ -56,6 +56,22 @@ export interface DetectClassOptions {
   vocab?: Partial<ClassVocab>
   /** Per-sample explicit `sample_type` hint (e.g. from experiment design data). */
   sampleTypeHints?: (string | undefined)[]
+  /** Number of leading tokens that all samples share (`TokenizedBatch.sharedPrefix`). */
+  sharedPrefix?: number
+}
+
+/** A token that names a QC-type class (blank, QC, standard, spike-in, stock). */
+export function isClassMarker(token: string, vocab: ClassVocab = classVocab): boolean {
+  return (
+    vocab.blankPattern.test(token) || vocab.iqcPattern.test(token) || vocab.eqcPattern.test(token)
+    || vocab.standardPattern.test(token) || vocab.standardAllow.has(token)
+    || vocab.spikeInPattern.test(token) || vocab.stockPattern.test(token)
+  )
+}
+
+/** Kinds that form experimental groups; all other kinds are QC-type overlay classes. */
+export function isExperimentalKind(kind: SampleClassKind): boolean {
+  return kind === 'biological' || kind === 'unknown'
 }
 
 const DEFAULT_DISPOSITION: Record<SampleClassKind, ClassDisposition> = {
@@ -72,26 +88,29 @@ const DEFAULT_DISPOSITION: Record<SampleClassKind, ClassDisposition> = {
 function classifyTokens(
   tokens: string[],
   vocab: ClassVocab,
+  qcFrom: number,
 ): { 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++) {
+  // QC kinds are read from `qcFrom`: a token that all names share (the
+  // experiment title) cannot mark one sample as QC.
+  for (let i = qcFrom; i < tokens.length; i++) {
     if (vocab.blankPattern.test(tokens[i])) return { kind: 'blank', tagPositions: [i] }
   }
-  for (let i = 0; i < tokens.length; i++) {
+  for (let i = qcFrom; i < tokens.length; i++) {
     if (vocab.iqcPattern.test(tokens[i])) return { kind: 'iqc', tagPositions: [i] }
   }
-  for (let i = 0; i < tokens.length; i++) {
+  for (let i = qcFrom; i < tokens.length; i++) {
     if (vocab.eqcPattern.test(tokens[i])) return { kind: 'eqc', tagPositions: [i] }
   }
-  for (let i = 0; i < tokens.length; i++) {
+  for (let i = qcFrom; 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++) {
+  for (let i = qcFrom; i < tokens.length; i++) {
     if (vocab.spikeInPattern.test(tokens[i])) return { kind: 'spike-in', tagPositions: [i] }
   }
-  for (let i = 0; i < tokens.length; i++) {
+  for (let i = qcFrom; i < tokens.length; i++) {
     if (vocab.stockPattern.test(tokens[i])) return { kind: 'stock', tagPositions: [i] }
   }
   for (let i = 0; i < tokens.length; i++) {
@@ -168,7 +187,7 @@ export function detectClass(
       kind = 'blank'
       tagPositions = []
     } else {
-      const r = classifyTokens(tokenizedSamples[i], vocab)
+      const r = classifyTokens(tokenizedSamples[i], vocab, options.sharedPrefix ?? 0)
       kind = r.kind
       subKind = r.subKind
       tagPositions = r.tagPositions

package/src/composables/autoGroup/columns.ts

@@ -5,15 +5,40 @@ import type {
   NumericParse,
   SampleClassKind,
 } from '../../types/auto-group'
+import vocabData from './vocab.json'
 
-const NUMERIC_VALUE_UNIT = /^(\d+(?:dot\d+)?)([A-Za-z%/μ]+)$/
+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.
+// Explicit replicate-token vocabulary: rep1 / Rep2 / replicate1 / R1 / T1.
 // 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
+const REPLICATE_TOKEN_PATTERN = new RegExp(vocabData.replicateToken, 'i')
+/**
+ * A replicate counter is a dense run of small numbers or letters: `1, 2, 3`,
+ * `01, 02, 03` or `A, B, C`. A quarter of the run can be missing (a failed
+ * sample). `1, 5, 10` is a dose and `1, 2, 6, 7` an animal number: too sparse.
+ */
+function isCounterRun(values: string[]): boolean {
+  if (!values.every(value => /^(\d{1,2}|[A-Za-z])$/.test(value))) return false
+  // One batch can count some replicates 1, 2, 3 and others a, b, c.
+  const ranks = [...new Set(values.map(value => (/\d/.test(value) ? Number(value) : value.toUpperCase().charCodeAt(0) - 64)))]
+  const allowedGaps = Math.max(1, Math.floor(ranks.length / 4))
+  return Math.min(...ranks) >= 1 && Math.max(...ranks) <= ranks.length + allowedGaps
+}
+
+// A stem with a counter attached: C1, C2, H1.
+const STEM_COUNTER_PATTERN = /^([A-Za-z]+)(\d{1,2})$/
+// Share of a column that must agree before the column is split or read as
+// one-value-for-each-sample. The rest allows for odd names and re-injections.
+const COLUMN_AGREEMENT = 0.9
+const ID_MIN_CLASS_SIZE = 4
+
+/** Roles the Field Recipe offers as grouping fields. `replicate` and `id` are off by default. */
+export const GROUPING_FIELD_ROLES: ReadonlySet<ColumnRole | undefined> = new Set<ColumnRole>([
+  'factor', 'numeric', 'replicate', 'id',
+])
 
 // Real-world LC-MS batches often have 30+ distinct conditions (subject IDs,
 // calibration levels, treatment combinations) in a single class. The earlier
@@ -48,16 +73,27 @@ export interface InferRoleInput {
   position: number
   totalPositions: number
   classSize: number
+  /** The column ends a name or a split token, where replicate counters sit. Defaults to the last position. */
+  tail?: boolean
 }
 
 export function inferRole(input: InferRoleInput): ColumnRole {
   const { values, position, totalPositions, classSize } = input
+  const tail = input.tail ?? position === totalPositions - 1
   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.
+  // replicate: explicit names (rep1, R1, T1), or a small counter that repeats
+  // at the end of a name (1, 2, 3, 1, 2, 3). Empty cells come from names that
+  // a column split did not match.
+  const present = values.filter(Boolean)
+  if (present.every(v => REPLICATE_TOKEN_PATTERN.test(v))) return 'replicate'
+  if (tail && cardinality * 2 <= values.length && isCounterRun(present)) return 'replicate'
+
+  // run-order: trailing position, injection-like values and high cardinality.
+  // Numbers repeat when one batch holds two experiments, so half is enough.
   if (position === totalPositions - 1) {
     const allRunLike = values.every(v => RUN_ORDER_PATTERN.test(v))
     if (allRunLike && cardinality >= classSize * 0.5) return 'run-order'
@@ -67,31 +103,90 @@ export function inferRole(input: InferRoleInput): ColumnRole {
   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.
+    // group on the timepoint, not bin it.
     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'
+  // id: one value for (almost) each sample, (almost) all with a digit — an
+  // animal or sample number (212, M10, C01). Grouping by it gives groups of
+  // one, so it is off by default. Unique words (Ctrl, DrugA, DrugB) are
+  // conditions of a design with no replicates and stay a factor.
+  if (
+    values.length >= ID_MIN_CLASS_SIZE
+    && cardinality >= values.length * COLUMN_AGREEMENT
+    && values.filter(v => /\d/.test(v)).length >= values.length * COLUMN_AGREEMENT
+  ) return 'id'
 
   if (cardinality <= DEFAULT_FACTOR_CARDINALITY_MAX) return 'factor'
 
   return 'ignore'
 }
 
+/**
+ * How a column splits when most of its values agree: on `-` into equal parts
+ * (`2-1` → `2`, `1`), or into stem + counter (`C1` → `C`, `1`) when two or more
+ * stems repeat with different counters. `D1`/`D3` (one stem) and `B13`/`S13`
+ * (one counter for each stem) stay whole.
+ */
+function columnSplitter(values: string[]): ((value: string) => string[]) | undefined {
+  const agree = (test: (value: string) => boolean): boolean =>
+    values.filter(test).length >= values.length * COLUMN_AGREEMENT
+
+  const partCounts = new Map<number, number>()
+  for (const value of values) {
+    const parts = value.split('-').length
+    partCounts.set(parts, (partCounts.get(parts) ?? 0) + 1)
+  }
+  const parts = [...partCounts].sort((a, b) => b[1] - a[1])[0]?.[0] ?? 1
+  if (parts > 1 && agree(value => value.split('-').length === parts)) {
+    return value => {
+      const pieces = value.split('-')
+      return pieces.length === parts ? pieces : [value, ...Array<string>(parts - 1).fill('')]
+    }
+  }
+
+  const countersByStem = new Map<string, Set<string>>()
+  for (const value of values) {
+    const match = STEM_COUNTER_PATTERN.exec(value)
+    if (match) countersByStem.set(match[1], (countersByStem.get(match[1]) ?? new Set()).add(match[2]))
+  }
+  const repeated = [...countersByStem.values()].filter(counters => counters.size > 1).length
+  if (countersByStem.size > 1 && repeated * 2 >= countersByStem.size && agree(value => STEM_COUNTER_PATTERN.test(value))) {
+    return value => STEM_COUNTER_PATTERN.exec(value)?.slice(1) ?? [value, '']
+  }
+  return undefined
+}
+
+export interface ColumnSplit {
+  rows: string[][]
+  /** `origin[newIndex]` = index of the source column before the split. */
+  origin: number[]
+  /** New indices that end a split token. */
+  tail: number[]
+}
+
+/** Split the columns of one class (rows of equal length) that hold two fields in one token. */
+export function splitColumns(rows: string[][]): ColumnSplit {
+  const width = rows[0]?.length ?? 0
+  const splitters = Array.from({ length: width }, (_, col) => columnSplitter(rows.map(row => row[col] ?? '')))
+  const origin: number[] = []
+  const tail: number[] = []
+  splitters.forEach((splitter, col) => {
+    const parts = splitter ? splitter(rows[0][col]).length : 1
+    for (let part = 0; part < parts; part++) origin.push(col)
+    if (parts > 1) tail.push(origin.length - 1)
+  })
+  return {
+    rows: rows.map(row => row.flatMap((token, col) => splitters[col]?.(token) ?? [token])),
+    origin,
+    tail,
+  }
+}
+
 /**
  * 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".
+ * Returns null when nothing matches, so callers can fall back to "Field N".
  *
  * Heuristics are content-derived and deterministic. They cover the common
  * LC-MS / proteomics naming conventions; users can override anything via
@@ -149,12 +244,13 @@ function inferColumnName(
   // 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'
+  // Operator / Username: a constant column of 2-3 uppercase letters is almost
+  // always operator initials (LCK, JD, AB). A column with two or more values
+  // (WT / KO) is a factor and gets no name here.
+  if (uniqueValues.length === 1 && /^[A-Z]{2,3}$/.test(uniqueValues[0])) return 'Username'
+
+  if (role === 'replicate') return 'Replicate'
+  if (role === 'id') return 'Sample ID'
 
   return null
 }
@@ -164,14 +260,20 @@ export function buildClassSchema(
   classKind: SampleClassKind,
   subKind: string | undefined,
   classTagPositions: number[],
+  /** Positions that end a split token (from `splitColumns`). */
+  tailPositions: number[] = [],
 ): ClassSchema {
   const totalPositions = tokenizedMembers[0]?.length ?? 0
   const classSize = tokenizedMembers.length
 
   const columns: ColumnInfo[] = []
   const tagSet = new Set(classTagPositions)
+  // Replicate counters sit at the end of a name: the last position, or the one
+  // before the injection number.
+  const tailSet = new Set([...tailPositions, totalPositions - 1])
 
-  for (let pos = 0; pos < totalPositions; pos++) {
+  // Right to left, so the injection column is known before its neighbour.
+  for (let pos = totalPositions - 1; pos >= 0; pos--) {
     const values = tokenizedMembers.map(t => t[pos] ?? '')
     const uniqueValues = [...new Set(values)]
 
@@ -182,8 +284,12 @@ export function buildClassSchema(
       // used as factor columns for grouping.
       role = 'class-tag'
     } else {
-      role = inferRole({ values, position: pos, totalPositions, classSize })
+      role = inferRole({ values, position: pos, totalPositions, classSize, tail: tailSet.has(pos) })
     }
+    // Injection numbers with no zero padding (7, 18, 20) read as an id column
+    // at the last position; a counter can sit before either form.
+    const lastPosition = pos === totalPositions - 1
+    if (role === 'run-order' || (lastPosition && role === 'id')) tailSet.add(pos - 1)
 
     const numeric =
       role === 'numeric'
@@ -197,9 +303,9 @@ export function buildClassSchema(
         : undefined
 
     const inferredName = inferColumnName(values, uniqueValues, role)
-    columns.push({
+    columns.unshift({
       index: pos,
-      name: inferredName ?? `Token ${pos + 1}`,
+      name: inferredName ?? `Field ${pos + 1}`,
       sourceIndices: [pos],
       uniqueValues,
       cardinality: uniqueValues.length,
@@ -210,17 +316,19 @@ export function buildClassSchema(
     })
   }
 
-  // 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
-    }
+  // The name is the field's identity across classes, so it must be unique in
+  // a schema: a second `Date` or `Replicate` becomes `Date 2`. Grouping fields
+  // take their names first, so a card keeps `Matrix` and the constant class
+  // tag beside it becomes `Matrix 2`.
+  const nameCounts = new Map<string, number>()
+  const isField = (c: ColumnInfo): boolean => GROUPING_FIELD_ROLES.has(c.role)
+  for (const c of [...columns.filter(isField), ...columns.filter(c => !isField(c))]) {
+    const count = (nameCounts.get(c.name) ?? 0) + 1
+    nameCounts.set(c.name, count)
+    if (count > 1) c.name = `${c.name} ${count}`
   }
 
-  const groupBy = columns.filter(c => c.role === 'factor').map(c => c.index)
+  const groupBy = columns.filter(c => c.role === 'factor' || c.role === 'numeric').map(c => c.index)
 
   return { classKind, subKind, columns, groupBy }
 }

package/src/composables/autoGroup/compose.ts

@@ -154,22 +154,20 @@ export function composeGroups(input: ComposeInput): AutoGroupResult {
       // 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.
+      // Only fires for disposition === 'group' classes (`classPrefix` holds no
+      // other class): overlay/exclude classes already use cls.label AS their
+      // single key part, so prefixing again would produce "IQC / IQC". A class
+      // with one condition has no factor keyParts and is named by the prefix
+      // alone ("Brain" next to "Liver / Ctrl"). The Unknown class 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 prefix = cls.kind !== 'unknown' ? classPrefix.get(cls) : undefined
       const groupKey = hasMissingGroupPart
         ? input.missingGroupName!
-        : prefix
-          ? `${prefix} / ${keyParts.join(' / ')}`
-          : keyParts.length > 0
-            ? keyParts.join(' / ')
-            : cls.label
+        : [...(prefix ? [prefix] : []), ...keyParts].join(' / ') || cls.label
 
       const bucket = groupMap.get(groupKey)
       if (bucket) {

package/src/composables/autoGroup/fingerprint.ts

@@ -34,7 +34,7 @@ export function restoreFingerprint(
       c =>
         c.classKind === snap.kind &&
         c.subKind === snap.subKind &&
-        (snap.tokenLength == null || c.tokenLength === snap.tokenLength),
+        (snap.tokenLength == null || c.tokenLength == null || c.tokenLength === snap.tokenLength),
     )
     const target =
       candidates.find(c => c.columns.length === snap.columns.length) ?? candidates[0]

package/src/composables/autoGroup/index.ts

@@ -1,12 +1,12 @@
 // Internal engine for `useAutoGroup` / `AutoGroupModal`. Deprecated: scheduled
 // for removal in MINT 1.4 together with `useAutoGroup`; no SDK replacement.
 
-export { splitMulti, pickPrimaryDelimiter } from './tokenize'
-export type { Delimiter } from './tokenize'
-export { detectClass, classVocab } from './classify'
+export { splitMulti, pickPrimaryDelimiter, tokenizeBatch } from './tokenize'
+export type { Delimiter, ExperimentHeader, TokenizedBatch } from './tokenize'
+export { detectClass, classVocab, isExperimentalKind } from './classify'
 export type { ClassVocab, DetectClassOptions } from './classify'
-export { inferRole, parseNumeric, buildClassSchema } from './columns'
-export type { InferRoleInput } from './columns'
+export { inferRole, parseNumeric, buildClassSchema, splitColumns, GROUPING_FIELD_ROLES } from './columns'
+export type { InferRoleInput, ColumnSplit } from './columns'
 export { findMerges } from './cooccurrence'
 export { composeGroups } from './compose'
 export type { ComposeInput } from './compose'
@@ -15,11 +15,4 @@ 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'

package/src/composables/autoGroup/tokenLength.ts

@@ -1,4 +1,5 @@
 import type { SampleClass } from '../../types/auto-group'
+import { isExperimentalKind } from './classify'
 
 /**
  * Token-length pre-grouping.
@@ -22,6 +23,13 @@ export function splitByTokenLength(
   const out: SampleClass[] = []
 
   for (const cls of classes) {
+    // QC-kind classes (QC, blank, standard) are one group named by the class
+    // label and never group by column, so they need no rectangular matrix.
+    if (!isExperimentalKind(cls.kind)) {
+      out.push(cls)
+      continue
+    }
+
     // Bucket members by token count, preserving first-seen order of lengths.
     const byLength = new Map<number, number[]>()
     const lengthOrder: number[] = []

package/src/composables/autoGroup/tokenize.ts

@@ -1,4 +1,6 @@
-const DELIMITER_CANDIDATES = ['_', '-', '.'] as const
+import { isClassMarker } from './classify'
+
+const DELIMITER_CANDIDATES = ['_', '-', ' ', '.'] as const
 export type Delimiter = (typeof DELIMITER_CANDIDATES)[number]
 
 /** Pick the delimiter whose split produces the most consistent field count across `lines`. */
@@ -39,3 +41,148 @@ export function pickPrimaryDelimiter(lines: string[]): Delimiter {
 export function splitMulti(name: string, delimiter: Delimiter): string[] {
   return name.split(delimiter)
 }
+
+/** The `exp<NNN>_<date>_<operator>` fields at the start of a sample name. */
+export interface ExperimentHeader {
+  code?: string
+  /** ISO date. Names carry it as YYMMDD, YYYYMMDD or DDMMYYYY. */
+  date?: string
+  operator?: string
+}
+
+export interface TokenizedBatch {
+  delimiter: Delimiter
+  /** One row of tokens for each input name, in input order. */
+  rows: string[][]
+  /** Header fields with one value in the batch. They are not in `rows`. */
+  experiment: ExperimentHeader
+  /**
+   * Number of leading tokens that all rows share (normally the experiment
+   * title). They cannot tell a QC sample from a study sample.
+   */
+  sharedPrefix: number
+}
+
+const HEADER_FIELDS = ['code', 'date', 'operator'] as const
+// Share of the names with a header that must carry the same operator before it
+// leaves the rows. The rest allows for stray names such as `exp157_test_blank_1`.
+const OPERATOR_AGREEMENT = 0.9
+// Outside this window a 6-digit token is read day-first: `091123` is 2023-11-09, not 2009.
+const FIRST_PLAUSIBLE_YEAR = 2015
+
+function isoDate(year: number, month: number, day: number): string | undefined {
+  const lastYear = new Date().getFullYear() + 1
+  if (year < FIRST_PLAUSIBLE_YEAR || year > lastYear) return undefined
+  // `Date` rolls an impossible day over to the next month; reject that.
+  const date = new Date(Date.UTC(year, month - 1, day))
+  if (date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day) return undefined
+  return date.toISOString().slice(0, 10)
+}
+
+/** Read a 6- or 8-digit date token; year-first is tried before day-first. */
+export function parseDateToken(token: string): string | undefined {
+  const n = (from: number, to: number): number => Number(token.slice(from, to))
+  if (/^\d{8}$/.test(token)) return isoDate(n(0, 4), n(4, 6), n(6, 8)) ?? isoDate(n(4, 8), n(2, 4), n(0, 2))
+  if (/^\d{6}$/.test(token)) return isoDate(2000 + n(0, 2), n(2, 4), n(4, 6)) ?? isoDate(2000 + n(4, 6), n(2, 4), n(0, 2))
+  return undefined
+}
+
+type HeaderField = (typeof HEADER_FIELDS)[number]
+
+/**
+ * Read the experiment code, date and operator from the left of a name, in any
+ * order. `position` holds the token index of each field. A name with no code
+ * and no date has no header, so `WT_Ctrl_1` keeps `WT` as a sample token.
+ */
+function readHeader(tokens: string[]): { fields: ExperimentHeader; position: Partial<Record<HeaderField, number>> } {
+  const fields: ExperimentHeader = {}
+  const position: Partial<Record<HeaderField, number>> = {}
+  let i = 0
+  if (tokens.length > 1 && /^exp\d+$/i.test(tokens[0])) {
+    fields.code = tokens[0].toLowerCase()
+    position.code = i++
+  }
+  for (; i < tokens.length - 1; i++) {
+    const date = fields.date ? undefined : parseDateToken(tokens[i])
+    if (date) {
+      fields.date = date
+      position.date = i
+    } else if (!fields.operator && /^[A-Z]{2,3}$/.test(tokens[i]) && !isClassMarker(tokens[i])) {
+      fields.operator = tokens[i]
+      position.operator = i
+    } else {
+      break
+    }
+  }
+  if (!fields.code && !fields.date) return { fields: {}, position: {} }
+  return { fields, position }
+}
+
+const MS_FILE_EXTENSION = /\.(raw|mzml|mzxml|mzdata|wiff2?|d|mgf|csv|tsv|txt)$/i
+
+/** Drop a mass-spec file extension from each name, and any other extension that all names share. */
+function stripExtensions(names: string[]): string[] {
+  const bare = names.map(name => name.replace(MS_FILE_EXTENSION, ''))
+  const ext = /\.[A-Za-z][A-Za-z0-9]{0,4}$/.exec(bare[0] ?? '')?.[0]
+  return ext && bare.every(name => name.endsWith(ext)) ? bare.map(name => name.slice(0, -ext.length)) : bare
+}
+
+/**
+ * Sample names → token rows.
+ *
+ *   1. Trim; drop a file extension that all names share.
+ *   2. Split on runs of the primary delimiter.
+ *   3. Drop a trailing 14-digit acquisition stamp.
+ *   4. Read the experiment header. A field moves to `experiment` when the batch
+ *      has one value for it. Any other field stays in the rows as written, so
+ *      `QC` or `WT` after the date in some names is not taken for operator
+ *      initials.
+ *   5. Count the tokens that all names share after the header (the experiment
+ *      title), so a title word such as `std` cannot classify the batch as QC.
+ */
+export function tokenizeBatch(names: string[]): TokenizedBatch {
+  const cleaned = stripExtensions(names.map(name => name.trim()))
+  const delimiter = pickPrimaryDelimiter(cleaned)
+  const parsed = cleaned.map(name => {
+    const split = name.split(delimiter).filter(Boolean)
+    if (split.length > 1 && /^\d{14}$/.test(split[split.length - 1])) split.pop()
+    const tokens = split.length > 0 ? split : [name]
+    return { tokens, ...readHeader(tokens) }
+  })
+
+  const experiment: ExperimentHeader = {}
+  for (const field of ['code', 'date'] as const) {
+    const values = new Set(parsed.map(({ fields }) => fields[field]).filter(Boolean))
+    if (values.size === 1) experiment[field] = [...values][0]
+  }
+  // `exp<NNN>` and a date are clear by their form. Operator initials are not:
+  // `QC`, `WT` or `KO` look the same. The operator is the caps token that
+  // (almost) all complete headers carry; any other caps token stays in its row.
+  const dated = parsed.filter(({ fields }) => fields.date)
+  const complete = dated.length > 0 ? dated : parsed.filter(({ fields }) => fields.code)
+  const operatorCounts = new Map<string, number>()
+  for (const { fields } of complete) {
+    if (fields.operator) operatorCounts.set(fields.operator, (operatorCounts.get(fields.operator) ?? 0) + 1)
+  }
+  const [operator, count] = [...operatorCounts].sort((a, b) => b[1] - a[1])[0] ?? []
+  if (operator && count >= complete.length * OPERATOR_AGREEMENT) experiment.operator = operator
+
+  const rows = parsed.map(({ tokens, fields, position }) => {
+    const moved = new Set(
+      HEADER_FIELDS.filter(field => experiment[field] && fields[field] === experiment[field]).map(field => position[field]),
+    )
+    return tokens.filter((_, index) => !moved.has(index))
+  })
+
+  // A title exists only after a header; without one a shared first token can
+  // be the QC marker of a QC-only paste.
+  let sharedPrefix = 0
+  if (rows.length > 1 && Object.keys(experiment).length > 0) {
+    while (rows.every(row => row.length > sharedPrefix + 1 && row[sharedPrefix] === rows[0][sharedPrefix])) sharedPrefix++
+    // When only numbers follow, the shared tokens are the sample description
+    // (a QC-only batch: `QC_1`, `QC_2`), not a title.
+    if (rows.every(row => row.slice(sharedPrefix).every(token => /^\d+[A-Za-z]?$/.test(token)))) sharedPrefix = 0
+  }
+
+  return { delimiter, experiment, rows, sharedPrefix }
+}

package/src/composables/autoGroup/vocab.json

@@ -7,14 +7,14 @@
     "matrixVocab": "Lowercase token → canonical display name. Tokens are normalised to lowercase before lookup, so adding 'tissues' handles 'Tissues' / 'TISSUES' / 'tissues' uniformly. Multiple aliases map to one canonical (e.g. cell + cells → Cells).",
     "ionizationModes": "Lowercase polarity tokens (pos / positive / neg / negative). Suffixed to the subKind so POS and NEG acquisitions get independent schemas.",
     "tissueParentTokens": "Tokens that flag the immediately-following token as the organ subKind (so `tissues / kidney` becomes Biological/Tissues, tagging both positions).",
-    "replicateStripPatterns": "Regex sources stripped from each sample name during the replicate pre-grouping pass. Samples whose stripped (base) names match are treated as replicates of one another and grouped together before tokenisation. Default set covers _T<n>, _B<n>, and _Rep<n> markers. The trailing injection / run-order number is intentionally NOT stripped here — it survives tokenisation and is surfaced as a 'run-order' column (named 'Injection #'), then excluded from the default group key so replicates still collapse."
+    "replicateToken": "Regex source for a token that names a replicate: rep1, Rep2, replicate3, R1, T1 (technical replicate). A column whose values all match is a replicate column: it stays a visible field and is left out of the default group key. B<n> is not in the pattern: on the lab share B13 / S13 are label tokens."
   },
 
   "patterns": {
     "blank":    "^(blank|blk|solv?blank|matrix.?blank)$",
-    "iqc":      "^iqc$",
+    "iqc":      "^(iqc|qc|pqc|pooled.?qc)$",
     "eqc":      "^eqc$",
-    "standard": "^(standard|std\\d*|cal(?:ibrator)?\\d*|.+standard)$",
+    "standard": "^(standards?|stds?\\d*|istd|cal(?:ibrator)?\\d*|.+standard)$",
     "spikeIn":  "spike.?in",
     "stock":    "^stock$"
   },
@@ -22,9 +22,7 @@
   "standardAllow": [
     "ExtractionS",
     "IS",
-    "internal.standard",
-    "PQC",
-    "pooledQC"
+    "internal.standard"
   ],
 
   "matrixVocab": {
@@ -58,9 +56,5 @@
 
   "tissueParentTokens": ["tissue", "tissues"],
 
-  "replicateStripPatterns": [
-    "[_-]T\\d+(?=[_-]|$)",
-    "[_-]B\\d+(?=[_-]|$)",
-    "[_-](?:rep(?:licate)?)\\d+(?=[_-]|$)"
-  ]
+  "replicateToken": "^(?:rep(?:licate)?|r|t)\\d+$"
 }