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

package/src/__tests__/composables/autoGroup/classKey.test.ts

@@ -0,0 +1,25 @@
+import { describe, it, expect } from 'vitest'
+import { classKey } from '../../../composables/autoGroup/classKey'
+
+describe('classKey', () => {
+  it('should key by kind alone when there is no subKind', () => {
+    expect(classKey({ kind: 'unknown' })).toBe('unknown')
+  })
+
+  it('should key by kind:subKind when a subKind is present', () => {
+    expect(classKey({ kind: 'biological', subKind: 'Plasma' })).toBe('biological:Plasma')
+  })
+
+  it('should append the token length so length-split classes get distinct keys', () => {
+    expect(classKey({ kind: 'biological', subKind: 'Plasma', tokenLength: 7 })).toBe(
+      'biological:Plasma#7',
+    )
+    expect(classKey({ kind: 'biological', subKind: 'Plasma', tokenLength: 8 })).toBe(
+      'biological:Plasma#8',
+    )
+  })
+
+  it('should append the token length even without a subKind', () => {
+    expect(classKey({ kind: 'unknown', tokenLength: 3 })).toBe('unknown#3')
+  })
+})

package/src/__tests__/composables/autoGroup/classify.test.ts

@@ -0,0 +1,107 @@
+import { describe, it, expect } from 'vitest'
+import { detectClass } from '../../../composables/autoGroup/classify'
+
+describe('detectClass', () => {
+  it('detects IQC and EQC by exact vocab match', () => {
+    const result = detectClass(
+      [
+        ['exp281', 'SAM_SAH', 'Tissues', 'IQC', '003'],
+        ['exp281', 'SAM_SAH', 'Tissues', 'IQC', '056'],
+        ['exp280', 'Experiment', 'EQC', '002'],
+      ],
+      {},
+    )
+    const iqc = result.find(c => c.kind === 'iqc')
+    const eqc = result.find(c => c.kind === 'eqc')
+    expect(iqc?.members).toEqual([0, 1])
+    expect(eqc?.members).toEqual([2])
+  })
+
+  it('detects Biological with subKind from matrix vocab', () => {
+    const result = detectClass(
+      [
+        ['exp281', 'SAM_SAH', 'Tissues', 'Kidney', 'M10', '085'],
+        ['exp281', 'SAM_SAH', 'Tissues', 'Liver', 'M10', '047'],
+        ['exp280', 'Experiment', 'Plasma', 'M10', '031'],
+      ],
+      {},
+    )
+    const tissues = result.find(c => c.kind === 'biological' && c.subKind === 'Tissues')
+    const plasma = result.find(c => c.kind === 'biological' && c.subKind === 'Plasma')
+    expect(tissues?.members).toEqual([0, 1])
+    expect(plasma?.members).toEqual([2])
+  })
+
+  it('classifies SAHStandard, SAMstandard, ExtractionS, STD1 as Standard (not Biological)', () => {
+    const result = detectClass(
+      [
+        ['exp281', 'SAM_SAH', 'SAHStandard', '5nM', '002'],
+        ['exp281', 'SAM_SAH', 'SAMstandard', '5nM', '001'],
+        ['exp281', 'SAM_SAH', 'Tissues', 'ExtractionS', '00B'],
+        ['exp', 'STD1', 'inject'],
+      ],
+      {},
+    )
+    const std = result.find(c => c.kind === 'standard')
+    expect(std?.members.sort()).toEqual([0, 1, 2, 3])
+  })
+
+  it('classifies SpikeIn and Stock', () => {
+    const result = detectClass(
+      [
+        ['exp280', 'SK', 'ESwithSpikeIn', '02'],
+        ['exp280', 'SK', 'ESwithSpikeIn', '1to100', 'Stock', '05'],
+      ],
+      {},
+    )
+    // SpikeIn matches first, so both go to spike-in (first match wins).
+    const spike = result.find(c => c.kind === 'spike-in')
+    expect(spike?.members.sort()).toEqual([0, 1])
+  })
+
+  it('classifies samples with no recognized vocab as Unknown', () => {
+    const result = detectClass([['foo', 'bar', 'baz']], {})
+    expect(result[0].kind).toBe('unknown')
+    expect(result[0].members).toEqual([0])
+  })
+
+  it('records classTagPositions for the position(s) that matched vocab', () => {
+    const result = detectClass(
+      [['exp281', 'SAM_SAH', 'Tissues', 'Kidney', 'M10', '085']],
+      {},
+    )
+    const tissues = result.find(c => c.kind === 'biological')
+    // Tissues at position 2 (class tag) and Kidney at position 3 (matrix tag).
+    expect(tissues?.classTagPositions).toContain(2)
+    expect(tissues?.classTagPositions).toContain(3)
+  })
+
+  it('honors sample_type hint short-circuit', () => {
+    const result = detectClass(
+      [['weird', 'name', 'with', 'no', 'vocab']],
+      { sampleTypeHints: ['qc'] },
+    )
+    expect(result[0].kind).toBe('iqc')
+  })
+
+  it('does not classify bare A1/M10/QC1/STD1 as Biological', () => {
+    // Names that only contain a `[A-Z]+\d+` token without matrix vocab must fall to Unknown,
+    // not Biological — prevents misclassifying calibration/QC labels.
+    const result = detectClass([['exp', 'foo', 'A1']], {})
+    expect(result[0].kind).toBe('unknown')
+  })
+
+  it('Biological requires an accompanying matrix vocab token', () => {
+    const result = detectClass([['exp', 'Plasma', 'M10']], {})
+    expect(result[0].kind).toBe('biological')
+    expect(result[0].subKind).toBe('Plasma')
+  })
+
+  it('first-match-wins between SpikeIn and Stock when both tokens appear', () => {
+    const result = detectClass(
+      [['exp', 'SK', 'ESwithSpikeIn', '1to100', 'Stock', '05']],
+      {},
+    )
+    expect(result[0].kind).toBe('spike-in')
+  })
+})

package/src/__tests__/composables/autoGroup/columns.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect } from 'vitest'
+import { inferRole, parseNumeric, buildClassSchema } from '../../../composables/autoGroup/columns'
+
+describe('parseNumeric', () => {
+  it('parses value+unit tokens', () => {
+    expect(parseNumeric('5nM')).toEqual({ value: 5, unit: 'nM', raw: '5nM' })
+    expect(parseNumeric('400ulES')).toEqual({ value: 400, unit: 'ulES', raw: '400ulES' })
+    expect(parseNumeric('1ul')).toEqual({ value: 1, unit: 'ul', raw: '1ul' })
+  })
+
+  it('decodes the dot-encoded decimal point', () => {
+    expect(parseNumeric('0dot5ul')).toEqual({ value: 0.5, unit: 'ul', raw: '0dot5ul' })
+  })
+
+  it('parses ratios via the dedicated branch', () => {
+    expect(parseNumeric('1to100')).toEqual({ value: 0.01, unit: 'ratio', raw: '1to100' })
+    expect(parseNumeric('1to10')).toEqual({ value: 0.1, unit: 'ratio', raw: '1to10' })
+  })
+
+  it('rejects bare IDs, dates, and pure numbers', () => {
+    expect(parseNumeric('M10')).toBeNull()
+    expect(parseNumeric('exp281')).toBeNull()
+    expect(parseNumeric('260415')).toBeNull()
+    expect(parseNumeric('123')).toBeNull()
+  })
+})
+
+describe('inferRole', () => {
+  const make = (values: string[]) => ({
+    values,
+    position: 0,
+    totalPositions: 1,
+    classSize: values.length,
+  })
+
+  it('returns constant when every value is the same', () => {
+    expect(inferRole(make(['exp281', 'exp281', 'exp281']))).toBe('constant')
+  })
+
+  it('returns run-order when trailing position has high-card numeric values', () => {
+    expect(inferRole({
+      values: ['001', '002', '003', '004', '005'],
+      position: 4,
+      totalPositions: 5,
+      classSize: 5,
+    })).toBe('run-order')
+  })
+
+  it('returns numeric when many distinct value+unit values are present', () => {
+    // 6+ distinct numeric levels read as numeric (binning candidates).
+    expect(inferRole(make(['1nM', '5nM', '10nM', '20nM', '50nM', '100nM']))).toBe('numeric')
+  })
+
+  it('returns factor for low-cardinality numerics (<=5 unique levels)', () => {
+    // 5min / 10min and similar small dose ladders read as factors by default;
+    // users opt into binning via the column popover for the cases that want it.
+    expect(inferRole(make(['5min', '10min']))).toBe('factor')
+    expect(inferRole(make(['5nM', '10nM', '20nM']))).toBe('factor')
+  })
+
+  it('returns replicate ONLY for explicit replicate-named tokens (rep1, Rep2, replicate3, R1)', () => {
+    // The replicate pre-grouping pass collapses real replicates by name
+    // before tokenisation, so the cardinality-based ID_PATTERN heuristic
+    // (M1, M2, …) was removed — those reach inferRole now only when they
+    // represent distinct conditions, and should be treated as factors.
+    expect(inferRole({
+      values: ['M1', 'M2', 'M3', 'M4', 'M5'],
+      position: 1,
+      totalPositions: 3,
+      classSize: 5,
+    })).toBe('factor')
+    expect(inferRole({
+      values: ['rep1', 'rep2', 'rep3'],
+      position: 1,
+      totalPositions: 3,
+      classSize: 3,
+    })).toBe('replicate')
+    expect(inferRole({
+      values: ['Replicate1', 'Replicate2'],
+      position: 1,
+      totalPositions: 3,
+      classSize: 2,
+    })).toBe('replicate')
+  })
+
+  it('returns factor for low-cardinality categoricals', () => {
+    expect(inferRole(make(['Kidney', 'Liver', 'Tumor', 'Kidney', 'Liver']))).toBe('factor')
+  })
+
+  it('returns ignore for very-high-cardinality opaque values', () => {
+    // Real-world LC-MS batches routinely have 30–50 distinct conditions, so the
+    // factor cap was raised to 50 (was 20). 80 unique values still reads as
+    // ignore — likely a sample-ID column rather than a meaningful factor.
+    const values = Array.from({ length: 80 }, (_, i) => `opaque-${i}`)
+    expect(inferRole({ values, position: 0, totalPositions: 1, classSize: 80 })).toBe('ignore')
+  })
+})
+
+describe('buildClassSchema', () => {
+  it('builds one ColumnInfo per position, constant class-tag positions get class-tag role', () => {
+    const schema = buildClassSchema(
+      [
+        ['exp281', 'SAM_SAH', 'Tissues', 'Kidney', 'M10', '085'],
+        ['exp281', 'SAM_SAH', 'Tissues', 'Liver', 'M10', '047'],
+      ],
+      'biological',
+      'Tissues',
+      [2, 3], // positions flagged as class-related tags
+    )
+    expect(schema.classKind).toBe('biological')
+    expect(schema.subKind).toBe('Tissues')
+    // Position 2 ('Tissues') is constant → class-tag.
+    // Position 3 ('Kidney'/'Liver') is multi-valued → falls through to factor inference.
+    const tagCols = schema.columns.filter(c => c.role === 'class-tag')
+    expect(tagCols.length).toBe(1)
+    expect(tagCols[0].index).toBe(2)
+    const factorCols = schema.columns.filter(c => c.role === 'factor')
+    expect(factorCols.some(c => c.index === 3)).toBe(true)
+  })
+
+  it('default groupBy is every Factor column', () => {
+    const schema = buildClassSchema(
+      [
+        ['exp', 'Kidney', '1'],
+        ['exp', 'Liver', '2'],
+        ['exp', 'Tumor', '3'],
+      ],
+      'biological',
+      'Tissues',
+      [],
+    )
+    const factorIndices = schema.columns.filter(c => c.role === 'factor').map(c => c.index)
+    expect(schema.groupBy).toEqual(factorIndices)
+  })
+})

package/src/__tests__/composables/autoGroup/compose.test.ts

@@ -0,0 +1,226 @@
+import { describe, it, expect } from 'vitest'
+import { composeGroups } from '../../../composables/autoGroup/compose'
+import type { ClassSchema } from '../../../types/auto-group'
+
+const tissueSchema: ClassSchema = {
+  classKind: 'biological',
+  subKind: 'Tissues',
+  columns: [
+    { index: 0, name: 'Tissue', sourceIndices: [0], uniqueValues: ['Kidney', 'Liver'], cardinality: 2, role: 'factor' },
+    { index: 1, name: 'Animal', sourceIndices: [1], uniqueValues: ['M1', 'M2', 'M3'], cardinality: 3, role: 'replicate' },
+  ],
+  groupBy: [0],
+}
+
+const iqcSchema: ClassSchema = {
+  classKind: 'iqc',
+  columns: [
+    { index: 0, name: 'IQC', sourceIndices: [0], uniqueValues: ['IQC'], cardinality: 1, role: 'class-tag' },
+    { index: 1, name: 'Run', sourceIndices: [1], uniqueValues: ['001', '002'], cardinality: 2, role: 'run-order' },
+  ],
+  groupBy: [],
+}
+
+describe('composeGroups', () => {
+  it('builds groups by enabled factor columns, ignoring replicate and run-order roles', () => {
+    const result = composeGroups({
+      tokenizedSamples: [
+        ['Kidney', 'M1'],
+        ['Kidney', 'M2'],
+        ['Liver', 'M1'],
+      ],
+      sampleNames: ['s1', 's2', 's3'],
+      schemas: { 'biological:Tissues': tissueSchema },
+      classes: [
+        {
+          kind: 'biological',
+          subKind: 'Tissues',
+          label: 'Biological / Tissues',
+          members: [0, 1, 2],
+          classTagPositions: [],
+          disposition: 'group',
+        },
+      ],
+    })
+    // A single experimental class needs no disambiguating prefix: group names
+    // start directly at the first enabled factor layer.
+    expect(result.experimentalGroups!.map(g => g.name).sort()).toEqual([
+      'Kidney',
+      'Liver',
+    ])
+    expect(
+      result.experimentalGroups!.find(g => g.name === 'Kidney')!.samples,
+    ).toEqual(['s1', 's2'])
+  })
+
+  it('routes overlay classes to qcGroups (separate from experimental)', () => {
+    const result = composeGroups({
+      tokenizedSamples: [
+        ['Kidney', 'M1'],
+        ['IQC', '001'],
+        ['IQC', '002'],
+      ],
+      sampleNames: ['bio1', 'iqc1', 'iqc2'],
+      schemas: { 'biological:Tissues': tissueSchema, iqc: iqcSchema },
+      classes: [
+        {
+          kind: 'biological',
+          subKind: 'Tissues',
+          label: 'Biological / Tissues',
+          members: [0],
+          classTagPositions: [],
+          disposition: 'group',
+        },
+        {
+          kind: 'iqc',
+          label: 'IQC',
+          members: [1, 2],
+          classTagPositions: [0],
+          disposition: 'overlay',
+        },
+      ],
+    })
+    expect(result.qcGroups!.length).toBe(1)
+    expect(result.qcGroups![0].name).toBe('IQC')
+    expect(result.qcGroups![0].samples).toEqual(['iqc1', 'iqc2'])
+    expect(result.experimentalGroups!.length).toBe(1)
+  })
+
+  it('routes excluded-disposition classes to excludedSamples', () => {
+    const result = composeGroups({
+      tokenizedSamples: [
+        ['Kidney', 'M1'],
+        ['IQC', '001'],
+      ],
+      sampleNames: ['bio1', 'iqc1'],
+      schemas: { 'biological:Tissues': tissueSchema, iqc: iqcSchema },
+      classes: [
+        {
+          kind: 'biological',
+          subKind: 'Tissues',
+          label: 'Biological / Tissues',
+          members: [0],
+          classTagPositions: [],
+          disposition: 'group',
+        },
+        {
+          kind: 'iqc',
+          label: 'IQC',
+          members: [1],
+          classTagPositions: [0],
+          disposition: 'exclude',
+        },
+      ],
+    })
+    expect(result.excludedSamples).toEqual(['iqc1'])
+    expect(result.qcGroups!.length).toBe(0)
+  })
+
+  it('legacy groups field equals experimentalGroups concat qcGroups', () => {
+    const result = composeGroups({
+      tokenizedSamples: [
+        ['Kidney', 'M1'],
+        ['IQC', '001'],
+      ],
+      sampleNames: ['bio1', 'iqc1'],
+      schemas: { 'biological:Tissues': tissueSchema, iqc: iqcSchema },
+      classes: [
+        {
+          kind: 'biological',
+          subKind: 'Tissues',
+          label: 'Biological / Tissues',
+          members: [0],
+          classTagPositions: [],
+          disposition: 'group',
+        },
+        {
+          kind: 'iqc',
+          label: 'IQC',
+          members: [1],
+          classTagPositions: [0],
+          disposition: 'overlay',
+        },
+      ],
+    })
+    const concatNames = [
+      ...result.experimentalGroups!.map(g => g.name),
+      ...result.qcGroups!.map(g => g.name),
+    ]
+    expect(result.groups.map(g => g.name)).toEqual(concatNames)
+  })
+
+  it('applies alias before exclude before bin in the operation pipeline', () => {
+    const schema: ClassSchema = {
+      classKind: 'biological',
+      columns: [
+        {
+          index: 0,
+          name: 'Treatment',
+          sourceIndices: [0],
+          uniqueValues: ['Drug-A', 'drug-A', 'CTL', 'CTL'],
+          cardinality: 3,
+          role: 'factor',
+          ops: {
+            alias: { 'drug-A': 'Drug-A' },
+            exclude: ['CTL'],
+          },
+        },
+      ],
+      groupBy: [0],
+    }
+    const result = composeGroups({
+      tokenizedSamples: [['Drug-A'], ['drug-A'], ['CTL']],
+      sampleNames: ['s1', 's2', 's3'],
+      schemas: { biological: schema },
+      classes: [
+        {
+          kind: 'biological',
+          label: 'Biological',
+          members: [0, 1, 2],
+          classTagPositions: [],
+          disposition: 'group',
+        },
+      ],
+    })
+    expect(result.experimentalGroups!.length).toBe(1)
+    // Single experimental class → unprefixed post-alias factor value.
+    expect(result.experimentalGroups![0].name).toBe('Drug-A')
+    expect(result.experimentalGroups![0].samples).toEqual(['s1', 's2'])
+    expect(result.excludedSamples).toEqual(['s3'])
+  })
+
+  it('stores post-alias / post-bin display values in MetadataRow.fields', () => {
+    const schema: ClassSchema = {
+      classKind: 'biological',
+      columns: [
+        {
+          index: 0,
+          name: 'Tissue',
+          sourceIndices: [0],
+          uniqueValues: ['Kidney', 'Liver'],
+          cardinality: 2,
+          role: 'factor',
+          ops: { alias: { Kidney: 'kidney_panel' } },
+        },
+      ],
+      groupBy: [0],
+    }
+    const result = composeGroups({
+      tokenizedSamples: [['Kidney']],
+      sampleNames: ['s1'],
+      schemas: { biological: schema },
+      classes: [
+        {
+          kind: 'biological',
+          label: 'Biological',
+          members: [0],
+          classTagPositions: [],
+          disposition: 'group',
+        },
+      ],
+    })
+    expect(result.metadata[0].fields.Tissue).toBe('kidney_panel')
+    // Single experimental class → unprefixed post-alias value as the group label.
+    expect(result.metadata[0].group).toBe('kidney_panel')
+  })
+})

package/src/__tests__/composables/autoGroup/cooccurrence.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, expect } from 'vitest'
+import { findMerges } from '../../../composables/autoGroup/cooccurrence'
+import type { ClassSchema } from '../../../types/auto-group'
+
+const schema = (overrides: Partial<ClassSchema> = {}): ClassSchema => ({
+  classKind: 'biological',
+  columns: [
+    { index: 0, name: 'A', sourceIndices: [0], uniqueValues: ['SAM'], cardinality: 1, role: 'factor' },
+    { index: 1, name: 'B', sourceIndices: [1], uniqueValues: ['SAH'], cardinality: 1, role: 'factor' },
+  ],
+  groupBy: [],
+  ...overrides,
+})
+
+describe('findMerges', () => {
+  it('suggests merging SAM + SAH when both columns are factors and mutually paired', () => {
+    const s = schema({
+      columns: [
+        { index: 0, name: 'A', sourceIndices: [0], uniqueValues: ['SAM', 'WT'], cardinality: 2, role: 'factor' },
+        { index: 1, name: 'B', sourceIndices: [1], uniqueValues: ['SAH', 'CTL'], cardinality: 2, role: 'factor' },
+      ],
+    })
+    const rows = [
+      ['SAM', 'SAH'],
+      ['SAM', 'SAH'],
+      ['SAM', 'SAH'],
+      ['SAM', 'SAH'],
+      ['WT', 'CTL'],
+      ['WT', 'CTL'],
+      ['WT', 'CTL'],
+      ['WT', 'CTL'],
+    ]
+    const out = findMerges(s, rows)
+    expect(out.length).toBe(1)
+    expect(out[0].columnIndices).toEqual([0, 1])
+    expect(out[0].confidence).toBeGreaterThanOrEqual(0.95)
+  })
+
+  it('rejects merge between two adjacent constants (no factor among them)', () => {
+    const s = schema({
+      columns: [
+        { index: 0, name: 'A', sourceIndices: [0], uniqueValues: ['exp281'], cardinality: 1, role: 'constant' },
+        { index: 1, name: 'B', sourceIndices: [1], uniqueValues: ['260415'], cardinality: 1, role: 'constant' },
+      ],
+    })
+    const rows = Array.from({ length: 10 }, () => ['exp281', '260415'])
+    expect(findMerges(s, rows)).toEqual([])
+  })
+
+  it('rejects asymmetric pairing (forward functional but not backward)', () => {
+    const s = schema({
+      columns: [
+        { index: 0, name: 'A', sourceIndices: [0], uniqueValues: ['a', 'b'], cardinality: 2, role: 'factor' },
+        { index: 1, name: 'B', sourceIndices: [1], uniqueValues: ['x'], cardinality: 1, role: 'constant' },
+      ],
+    })
+    const rows = [
+      ['a', 'x'],
+      ['a', 'x'],
+      ['b', 'x'],
+      ['b', 'x'],
+    ]
+    expect(findMerges(s, rows)).toEqual([])
+  })
+
+  it('rejects suggestions when class size < 4', () => {
+    const s = schema({
+      columns: [
+        { index: 0, name: 'A', sourceIndices: [0], uniqueValues: ['a', 'b'], cardinality: 2, role: 'factor' },
+        { index: 1, name: 'B', sourceIndices: [1], uniqueValues: ['x', 'y'], cardinality: 2, role: 'factor' },
+      ],
+    })
+    const rows = [
+      ['a', 'x'],
+      ['b', 'y'],
+      ['a', 'x'],
+    ]
+    expect(findMerges(s, rows)).toEqual([])
+  })
+
+  it('rejects merge that would collapse two adjacent factors into a single constant', () => {
+    const s = schema({
+      columns: [
+        { index: 0, name: 'A', sourceIndices: [0], uniqueValues: ['x'], cardinality: 1, role: 'factor' },
+        { index: 1, name: 'B', sourceIndices: [1], uniqueValues: ['y'], cardinality: 1, role: 'factor' },
+      ],
+    })
+    const rows = Array.from({ length: 6 }, () => ['x', 'y'])
+    expect(findMerges(s, rows)).toEqual([])
+  })
+})