@morscherlab/mint-sdk 1.0.0-rc.2 → 1.0.0-rc.5

package/src/components/internal/PlateMapEditorToolbarInternal.vue

@@ -0,0 +1,128 @@
+<script setup lang="ts">
+/** Toolbar for PlateMapEditor plate tabs and import/export history actions. */
+import type { PlateMap } from '../../types'
+
+interface Props {
+  plates: PlateMap[]
+  activePlateId?: string
+  plateWellCounts: Record<string, number>
+  canAddPlate: boolean
+  canUndo: boolean
+  canRedo: boolean
+  slotColorForPlate: (plateId: string, plateIndex: number) => string
+}
+
+const props = defineProps<Props>()
+
+const emit = defineEmits<{
+  'select-plate': [plateId: string]
+  'remove-plate': [plateId: string]
+  'add-plate': []
+  undo: []
+  redo: []
+  import: []
+  'export-json': []
+}>()
+</script>
+
+<template>
+  <div class="mint-plate-editor__toolbar">
+    <div class="mint-plate-editor__tabs">
+      <button
+        v-for="(plate, index) in plates"
+        :key="plate.id"
+        type="button"
+        :class="['mint-plate-editor__tab', { 'mint-plate-editor__tab--active': plate.id === activePlateId }]"
+        @click="emit('select-plate', plate.id)"
+      >
+        <span
+          class="mint-plate-editor__tab-slot"
+          :style="{ backgroundColor: slotColorForPlate(plate.id, index) }"
+        />
+        <span class="mint-plate-editor__tab-name">{{ plate.name }}</span>
+        <span
+          v-if="plateWellCounts[plate.id] > 0"
+          class="mint-plate-editor__tab-count"
+        >
+          {{ plateWellCounts[plate.id] }}
+        </span>
+        <button
+          v-if="props.plates.length > 1"
+          type="button"
+          class="mint-plate-editor__tab-remove"
+          :aria-label="`Remove ${plate.name}`"
+          @click.stop="emit('remove-plate', plate.id)"
+        >
+          <svg fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+            <path d="M18 6 6 18" /><path d="m6 6 12 12" />
+          </svg>
+        </button>
+      </button>
+
+      <button
+        v-if="canAddPlate"
+        type="button"
+        class="mint-plate-editor__add-plate"
+        aria-label="Add plate"
+        @click="emit('add-plate')"
+      >
+        <svg fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <path d="M5 12h14" /><path d="M12 5v14" />
+        </svg>
+        <span>Add</span>
+      </button>
+    </div>
+
+    <div class="mint-plate-editor__spacer" />
+
+    <div class="mint-plate-editor__actions">
+      <button
+        type="button"
+        :disabled="!canUndo"
+        class="mint-plate-editor__action-btn"
+        title="Undo (Ctrl+Z)"
+        @click="emit('undo')"
+      >
+        <svg fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <path d="M9 14 4 9l5-5" /><path d="M4 9h10.5a5.5 5.5 0 0 1 5.5 5.5a5.5 5.5 0 0 1-5.5 5.5H11" />
+        </svg>
+      </button>
+
+      <button
+        type="button"
+        :disabled="!canRedo"
+        class="mint-plate-editor__action-btn"
+        title="Redo (Ctrl+Shift+Z)"
+        @click="emit('redo')"
+      >
+        <svg fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <path d="m15 14 5-5-5-5" /><path d="M20 9H9.5A5.5 5.5 0 0 0 4 14.5A5.5 5.5 0 0 0 9.5 20H13" />
+        </svg>
+      </button>
+
+      <div class="mint-plate-editor__divider" />
+
+      <button
+        type="button"
+        class="mint-plate-editor__action-btn"
+        title="Import"
+        @click="emit('import')"
+      >
+        <svg fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <path d="M12 3v12" /><path d="m17 8-5-5-5 5" /><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" />
+        </svg>
+      </button>
+
+      <button
+        type="button"
+        class="mint-plate-editor__action-btn"
+        title="Export JSON"
+        @click="emit('export-json')"
+      >
+        <svg fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <path d="M12 15V3" /><path d="m7 10 5 5 5-5" /><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" />
+        </svg>
+      </button>
+    </div>
+  </div>
+</template>

package/src/composables/autoGroup/classKey.ts

@@ -0,0 +1,5 @@
+import type { SampleClass } from '../../types/auto-group'
+
+export function classKey(c: Pick<SampleClass, 'kind'> & { subKind?: string }): string {
+  return c.subKind ? `${c.kind}:${c.subKind}` : c.kind
+}

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 already has the right semantic role.
+  if (role === 'run-order') return 'Run Order'
+
+  // 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 }
+}