@morscherlab/mint-sdk 1.0.27 → 1.0.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morscherlab/mint-sdk",
-  "version": "1.0.27",
+  "version": "1.0.29",
   "description": "MINT Platform SDK — Vue 3 components, composables, and types for plugin development. MINT = Mass-spec INtegrated Toolkit.",
   "type": "module",
   "main": "./dist/index.js",

package/src/__tests__/composables/useAutoGroup.test.ts

@@ -215,6 +215,74 @@ describe('extractSamplesFromDesignData', () => {
   })
 })
 
+describe('useAutoGroup CSV structured hierarchy', () => {
+  it('uses CSV metadata columns as hierarchy without biological or QC class groups', () => {
+    const auto = useAutoGroup()
+    auto.inputMode.value = 'csv'
+    auto.csvData.value = parseCSV([
+      'Sample,Tissue,Treatment,sample_type',
+      'S1,Kidney,Drug,sample',
+      'S2,Liver,Drug,sample',
+      'QC_pool,,QC,qc',
+    ].join('\n'))
+    auto.parseInput()
+
+    expect(auto.classes.value).toHaveLength(1)
+    expect(auto.classes.value[0].kind).toBe('unknown')
+    expect(auto.qcGroups.value).toEqual([])
+    expect(auto.groups.value.map(g => g.name).sort()).toEqual([
+      'Kidney / Drug',
+      'Liver / Drug',
+      'Outlier',
+    ])
+    expect(auto.groups.value.find(g => g.name === 'Outlier')?.samples).toEqual(['QC_pool'])
+    expect(auto.groups.value.some(g => g.name.includes('Biological'))).toBe(false)
+    expect(auto.groups.value.some(g => g.name === 'QC')).toBe(false)
+  })
+
+  it('defaults every CSV metadata column into the group key', () => {
+    const auto = useAutoGroup()
+    auto.inputMode.value = 'csv'
+    auto.csvData.value = parseCSV([
+      'Sample,Batch,Tissue,Treatment,Timepoint',
+      'S1,B1,Kidney,Drug,5min',
+      'S2,B1,Kidney,Drug,10min',
+    ].join('\n'))
+    auto.parseInput()
+
+    expect(auto.activeSchema.value?.columns.map(c => c.name)).toEqual([
+      'Batch',
+      'Tissue',
+      'Treatment',
+      'Timepoint',
+    ])
+    expect(auto.activeSchema.value?.groupBy).toEqual([0, 1, 2, 3])
+    expect(auto.groups.value.map(g => g.name).sort()).toEqual([
+      'B1 / Kidney / Drug / 10min',
+      'B1 / Kidney / Drug / 5min',
+    ])
+  })
+
+  it('limits experiment design-data grouping to provided sample names', () => {
+    const auto = useAutoGroup()
+    const loaded = auto.loadExperimentData({
+      samples: [
+        { sample_name: 'S1', sample_type: 'sample', conditions: { Tissue: 'Kidney', Treatment: 'Control' } },
+        { sample_name: 'S2', sample_type: 'sample', conditions: { Tissue: 'Liver', Treatment: 'Drug' } },
+        { sample_name: 'S3', sample_type: 'sample', conditions: { Tissue: 'Brain', Treatment: 'Drug' } },
+      ],
+    }, { samples: ['S2', 'MissingFromDesign'] })
+
+    expect(loaded).toBe(true)
+    expect(auto.samples.value).toEqual(['S2', 'MissingFromDesign'])
+    expect(auto.groups.value.map(g => g.name).sort()).toEqual([
+      'Liver / Drug',
+      'Outlier',
+    ])
+    expect(auto.groups.value.find(g => g.name === 'Outlier')?.samples).toEqual(['MissingFromDesign'])
+  })
+})
+
 describe('useAutoGroup auto-disable degenerate columns', () => {
   it('collapses unique-per-row injection numbers via replicate pre-grouping', () => {
     // The replicate pre-grouping pass strips the trailing 3-digit run-order

package/src/__tests__/composables/useAutoGroupInputSources.test.ts

@@ -71,6 +71,26 @@ describe('useAutoGroupInputSources', () => {
     expect(sources.experimentLoading.value).toBe(false)
   })
 
+  it('filters loaded experiment metadata to the provided sample subset', async () => {
+    const { autoGroup, sources } = makeSources({
+      samples: ['S2', 'MissingFromDesign'],
+      designData: {
+        samples: [
+          { sample_name: 'S1', sample_type: 'sample', conditions: { Tissue: 'Kidney', Treatment: 'Control' } },
+          { sample_name: 'S2', sample_type: 'sample', conditions: { Tissue: 'Liver', Treatment: 'Drug' } },
+        ],
+      },
+    })
+
+    await sources.initializeInputSources()
+
+    expect(autoGroup.samples.value).toEqual(['S2', 'MissingFromDesign'])
+    expect(autoGroup.groups.value.map(g => g.name).sort()).toEqual([
+      'Liver / Drug',
+      'Outlier',
+    ])
+  })
+
   it('parses uploaded CSV files and can clear them back to paste mode', async () => {
     const { autoGroup, sources } = makeSources()
     const file = {

package/src/components/AutoGroupModal.vue

@@ -529,7 +529,7 @@ async function fetchExperimentData() {
       return
     }
 
-    const success = autoGroup.loadExperimentData(pluginData)
+    const success = autoGroup.loadExperimentData(pluginData, { samples: props.samples })
     if (!success) {
       experimentError.value = 'No sample metadata found in this experiment'
       return

package/src/composables/autoGroup/compose.ts

@@ -15,6 +15,8 @@ export interface ComposeInput {
   sampleNames: string[]
   schemas: Record<string, ClassSchema>
   classes: SampleClass[]
+  prefixClassLabels?: boolean
+  missingGroupName?: string
 }
 
 /** Apply the operation pipeline to a single raw token value:
@@ -116,13 +118,22 @@ export function composeGroups(input: ComposeInput): AutoGroupResult {
       // 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 useClassPrefix =
-        cls.disposition === 'group' && cls.kind !== 'unknown' && keyParts.length > 0
-      const groupKey = useClassPrefix
-        ? `${cls.label} / ${keyParts.join(' / ')}`
-        : keyParts.length > 0
-          ? keyParts.join(' / ')
-          : cls.label
+        input.prefixClassLabels !== false &&
+        cls.disposition === 'group' &&
+        cls.kind !== 'unknown' &&
+        keyParts.length > 0
+      const groupKey = hasMissingGroupPart
+        ? input.missingGroupName!
+        : useClassPrefix
+          ? `${cls.label} / ${keyParts.join(' / ')}`
+          : keyParts.length > 0
+            ? keyParts.join(' / ')
+            : cls.label
 
       const bucket = groupMap.get(groupKey)
       if (bucket) {

package/src/composables/useAutoGroup.ts

@@ -35,6 +35,14 @@ import { unwrapExperimentDesignData } from './experimentDesignData'
 
 export { DEFAULT_COLORS } from './autoGroup'
 
+const STRUCTURED_MISSING_GROUP = 'Outlier'
+
+type ParsedExperimentCsvData = ParsedCsvData & { sampleTypeHints: (string | undefined)[] }
+
+interface LoadExperimentDataOptions {
+  samples?: readonly string[]
+}
+
 let deprecationWarned = false
 let outlierDeprecationWarned = false
 function warnDeprecated(api: string) {
@@ -104,30 +112,26 @@ export function useAutoGroup() {
     }
     const tokens = csv.rows.map(r => nonSampleCols.map(col => r[col] ?? ''))
     tokenized.value = tokens
-    // Class detection: use explicit sample_type hint from csv.rows[i].sample_type
-    const hints = csv.rows.map(r => {
-      const t = String(r['sample_type'] ?? '').toLowerCase()
-      if (t === 'qc') return 'qc'
-      if (t === 'blank') return 'blank'
-      return undefined
-    })
-    const detected = detectClass(tokens, { sampleTypeHints: hints })
-    classes.value = detected
-    // Build schema per class with CSV header names
-    const newSchemas: Record<string, ClassSchema> = {}
-    for (const cls of detected) {
-      const memberTokens = cls.members.map(i => tokens[i])
-      const schema = buildClassSchema(memberTokens, cls.kind, cls.subKind, cls.classTagPositions)
-      // Override default Token N names with actual CSV header names
-      schema.columns = schema.columns.map((c, i) => ({
-        ...c,
-        name: nonSampleCols[i] ?? c.name,
-        originalName: nonSampleCols[i],
-      }))
-      newSchemas[classKey(cls)] = schema
+    const structuredClass: SampleClass = {
+      kind: 'unknown',
+      label: 'Unknown',
+      members: csv.rows.map((_, i) => i),
+      classTagPositions: [],
+      disposition: 'group',
     }
-    schemas.value = newSchemas
-    if (detected.length > 0) activeClassKey.value = classKey(detected[0])
+    classes.value = [structuredClass]
+
+    const schema = buildClassSchema(tokens, 'unknown', undefined, [])
+    schema.columns = schema.columns.map((c, i) => ({
+      ...c,
+      name: nonSampleCols[i] ?? c.name,
+      originalName: nonSampleCols[i],
+    }))
+    // CSV headers are already the user-authored hierarchy. Default to every
+    // metadata column so N CSV columns produce N visible grouping levels.
+    schema.groupBy = schema.columns.map(c => c.index)
+    schemas.value = { unknown: schema }
+    activeClassKey.value = 'unknown'
   }
 
   function parseInputFromPaste() {
@@ -193,6 +197,10 @@ export function useAutoGroup() {
       sampleNames: pre ? pre.baseNames : samples.value,
       schemas: schemas.value,
       classes: classes.value,
+      prefixClassLabels: !(csvData.value && (inputMode.value === 'csv' || inputMode.value === 'experiment')),
+      missingGroupName: csvData.value && (inputMode.value === 'csv' || inputMode.value === 'experiment')
+        ? STRUCTURED_MISSING_GROUP
+        : undefined,
     })
     if (!pre) return composed
     // Expand each group's `samples` from base names back to the original
@@ -416,8 +424,11 @@ export function useAutoGroup() {
     if (activeClassKey.value) setColumnName(activeClassKey.value, index, name)
   }
 
-  function loadExperimentData(rawData: Record<string, unknown>): boolean {
-    const parsed = extractSamplesFromDesignData(rawData)
+  function loadExperimentData(
+    rawData: Record<string, unknown>,
+    options: LoadExperimentDataOptions = {},
+  ): boolean {
+    const parsed = extractSamplesFromDesignData(rawData, options)
     if (!parsed) return false
     inputMode.value = 'experiment'
     csvData.value = parsed
@@ -460,7 +471,8 @@ export function useAutoGroup() {
 
 export function extractSamplesFromDesignData(
   rawData: Record<string, unknown>,
-): (ParsedCsvData & { sampleTypeHints: (string | undefined)[] }) | null {
+  options: LoadExperimentDataOptions = {},
+): ParsedExperimentCsvData | null {
   const designData = unwrapExperimentDesignData(rawData)
   if (!designData) return null
   const samples = designData.samples
@@ -492,5 +504,51 @@ export function extractSamplesFromDesignData(
     for (const key of allConditionKeys) row[key] = conditions[key] ?? ''
     return row
   })
-  return { columns, rows, sampleColumn: 'sample_name', delimiter: ',', sampleTypeHints }
+  return constrainParsedSamplesToInput(
+    { columns, rows, sampleColumn: 'sample_name', delimiter: ',', sampleTypeHints },
+    options.samples,
+  )
+}
+
+function constrainParsedSamplesToInput(
+  parsed: ParsedExperimentCsvData,
+  samples: readonly string[] | undefined,
+): ParsedExperimentCsvData {
+  const requested = samples
+    ?.map(sample => sample.trim())
+    .filter(sample => sample.length > 0)
+  if (!requested || requested.length === 0) return parsed
+
+  const rowBySample = new Map<string, { row: Record<string, string>; hint: string | undefined }>()
+  parsed.rows.forEach((row, index) => {
+    const sample = row[parsed.sampleColumn]
+    if (sample && !rowBySample.has(sample)) {
+      rowBySample.set(sample, { row, hint: parsed.sampleTypeHints[index] })
+    }
+  })
+
+  const metadataColumns = parsed.columns.filter(
+    column => column !== parsed.sampleColumn && column !== 'sample_type',
+  )
+  const rows: Record<string, string>[] = []
+  const sampleTypeHints: (string | undefined)[] = []
+
+  for (const sample of requested) {
+    const match = rowBySample.get(sample)
+    if (match) {
+      rows.push(match.row)
+      sampleTypeHints.push(match.hint)
+      continue
+    }
+
+    const outlierRow: Record<string, string> = {
+      [parsed.sampleColumn]: sample,
+      sample_type: 'sample',
+    }
+    for (const column of metadataColumns) outlierRow[column] = ''
+    rows.push(outlierRow)
+    sampleTypeHints.push(undefined)
+  }
+
+  return { ...parsed, rows, sampleTypeHints }
 }

package/src/composables/useAutoGroupInputSources.ts

@@ -64,7 +64,7 @@ export function useAutoGroupInputSources(options: UseAutoGroupInputSourcesOption
         return
       }
 
-      const success = options.autoGroup.loadExperimentData(pluginData)
+      const success = options.autoGroup.loadExperimentData(pluginData, { samples: options.samples.value })
       if (!success) {
         experimentError.value = 'No sample metadata found in this experiment'
         return