@morscherlab/mint-sdk 1.0.0-alpha.2

package/src/composables/useAutoGroup.ts

@@ -0,0 +1,641 @@
+import { ref, computed } from 'vue'
+import type {
+  InputMode,
+  OutlierAction,
+  OutlierInfo,
+  ColumnInfo,
+  MetadataRow,
+  AutoGroupResult,
+  ParsedCsvData,
+} from '../types/auto-group'
+import type { SampleGroup } from '../types/components'
+
+export const DEFAULT_COLORS = [
+  '#3B82F6', '#10B981', '#F59E0B', '#EF4444', '#8B5CF6',
+  '#EC4899', '#06B6D4', '#84CC16', '#F97316', '#6366F1',
+]
+
+const DELIMITER_CANDIDATES = ['_', '-', '.'] as const
+
+// --- Pure functions (exported for testing) ---
+
+export function analyzeDelimiter(lines: string[]): {
+  delimiter: string
+  dominantFieldCount: number
+  minFieldCount: number
+  consistency: number
+} {
+  if (lines.length === 0) {
+    return { delimiter: '_', dominantFieldCount: 1, minFieldCount: 1, consistency: 0 }
+  }
+
+  let bestDelimiter = '_'
+  let bestConsistency = -1
+  let bestFieldCount = 1
+
+  for (const candidate of DELIMITER_CANDIDATES) {
+    const fieldCounts = lines.map(line => line.split(candidate).length)
+    const countFrequency = new Map<number, number>()
+
+    for (const count of fieldCounts) {
+      countFrequency.set(count, (countFrequency.get(count) ?? 0) + 1)
+    }
+
+    // Find mode (most frequent field count)
+    let modeCount = 1
+    let modeFrequency = 0
+    for (const [count, freq] of countFrequency) {
+      if (freq > modeFrequency || (freq === modeFrequency && count > modeCount)) {
+        modeCount = count
+        modeFrequency = freq
+      }
+    }
+
+    const rawConsistency = modeFrequency / lines.length
+    // A delimiter that produces field count 1 didn't actually split anything
+    const consistency = modeCount > 1 ? rawConsistency : 0
+
+    if (
+      consistency > bestConsistency ||
+      (consistency === bestConsistency &&
+        DELIMITER_CANDIDATES.indexOf(candidate) < DELIMITER_CANDIDATES.indexOf(bestDelimiter as typeof candidate))
+    ) {
+      bestDelimiter = candidate
+      bestConsistency = consistency
+      bestFieldCount = modeCount
+    }
+  }
+
+  const bestFieldCounts = lines.map(line => line.split(bestDelimiter).length)
+  const multiFieldCounts = bestFieldCounts.filter(c => c >= 2)
+  const minFieldCount = multiFieldCounts.length > 0 ? Math.min(...multiFieldCounts) : 1
+
+  return {
+    delimiter: bestDelimiter,
+    dominantFieldCount: bestFieldCount,
+    minFieldCount,
+    consistency: bestConsistency,
+  }
+}
+
+export function detectOutliers(
+  lines: string[],
+  delimiter: string,
+  minFieldCount: number,
+): OutlierInfo[] {
+  const outliers: OutlierInfo[] = []
+
+  for (let i = 0; i < lines.length; i++) {
+    const fieldCount = lines[i].split(delimiter).length
+    if (fieldCount < minFieldCount) {
+      outliers.push({
+        sample: lines[i],
+        index: i,
+        fieldCount,
+        action: 'include',
+      })
+    }
+  }
+
+  return outliers
+}
+
+const QC_KEYWORDS = new Set([
+  'eqc', 'iqc', 'qc', 'blank', 'std', 'standard', 'test',
+])
+
+export function classifyOutlierAction(
+  sample: string,
+  delimiter: string,
+): OutlierAction {
+  const segments = sample.split(delimiter)
+  return segments.some(seg => QC_KEYWORDS.has(seg.toLowerCase()))
+    ? 'qc'
+    : 'include'
+}
+
+// A column is useful for grouping when it has more than one distinct value
+// AND it does not produce a unique value per row (which would create N
+// singleton groups instead of meaningful aggregation).
+export function isUsefulField(field: ColumnInfo, rowCount: number): boolean {
+  return field.cardinality > 1 && !(rowCount > 1 && field.cardinality === rowCount)
+}
+
+export function extractColumns(
+  samples: string[],
+  delimiter: string,
+  minFieldCount: number,
+): ColumnInfo[] {
+  if (samples.length === 0) return []
+
+  const suffixCount = minFieldCount - 1
+  const rows = samples.map(s => {
+    const parts = s.split(delimiter)
+    const splitAt = parts.length - suffixCount
+    return [
+      parts.slice(0, splitAt).join(delimiter),
+      ...parts.slice(splitAt),
+    ]
+  })
+
+  const columnCount = minFieldCount
+  const columns: ColumnInfo[] = []
+  for (let col = 0; col < columnCount; col++) {
+    const values = rows.map(row => row[col])
+    const unique = [...new Set(values)]
+    columns.push({
+      index: col,
+      name: col === 0 ? 'Condition' : `Field ${col + 1}`,
+      uniqueValues: unique,
+      cardinality: unique.length,
+      type: col === 0 ? 'prefix' : 'suffix',
+    })
+  }
+
+  return columns
+}
+
+export 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 === '"') {
+      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')
+  }
+
+  // Auto-detect delimiter: tab takes precedence if present in header
+  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((header, idx) => {
+      row[header] = values[idx]
+    })
+    rows.push(row)
+  }
+
+  // Auto-detect sample column
+  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 }
+}
+
+export function computeGroups(
+  allSamples: string[],
+  columns: ColumnInfo[],
+  enabledFields: Set<number>,
+  outlierActions: Map<number, OutlierAction>,
+  delimiter: string,
+  minFieldCount: number,
+): { groups: SampleGroup[]; metadata: MetadataRow[]; excludedSamples: string[] } {
+  const excludedSamples: string[] = []
+  const qcSamples: string[] = []
+  const conformingSamples: string[] = []
+
+  for (let i = 0; i < allSamples.length; i++) {
+    const action = outlierActions.get(i)
+    if (action === 'exclude') {
+      excludedSamples.push(allSamples[i])
+    } else if (action === 'qc') {
+      qcSamples.push(allSamples[i])
+    } else {
+      conformingSamples.push(allSamples[i])
+    }
+  }
+
+  // Build group map
+  const groupMap = new Map<string, string[]>()
+  const metadata: MetadataRow[] = []
+  const enabledIndices = [...enabledFields].sort((a, b) => a - b)
+
+  const suffixCount = minFieldCount - 1
+
+  for (const sample of conformingSamples) {
+    const parts = sample.split(delimiter)
+    const splitAt = Math.max(1, parts.length - suffixCount)
+    const row = [
+      parts.slice(0, splitAt).join(delimiter),
+      ...parts.slice(splitAt),
+    ]
+
+    // Build group key from enabled columns
+    const keyParts: string[] = []
+    for (const idx of enabledIndices) {
+      if (idx < row.length && idx < columns.length) {
+        keyParts.push(row[idx])
+      }
+    }
+    const groupKey = keyParts.join(' / ')
+
+    if (!groupMap.has(groupKey)) {
+      groupMap.set(groupKey, [])
+    }
+    groupMap.get(groupKey)!.push(sample)
+
+    // Build metadata row with ALL columns
+    const fields: Record<string, string> = {}
+    for (const col of columns) {
+      if (col.index < row.length) {
+        fields[col.name] = row[col.index]
+      }
+    }
+    metadata.push({ sampleName: sample, fields, group: groupKey })
+  }
+
+  // Convert to SampleGroup[]
+  const groups: SampleGroup[] = []
+  let colorIdx = 0
+  for (const [name, samples] of groupMap) {
+    groups.push({
+      name,
+      color: DEFAULT_COLORS[colorIdx % DEFAULT_COLORS.length],
+      samples,
+    })
+    colorIdx++
+  }
+
+  // QC group
+  if (qcSamples.length > 0) {
+    groups.push({
+      name: 'QC',
+      color: '#6B7280',
+      samples: qcSamples,
+    })
+    for (const sample of qcSamples) {
+      metadata.push({ sampleName: sample, fields: {}, group: 'QC' })
+    }
+  }
+
+  return { groups, metadata, excludedSamples }
+}
+
+/**
+ * Extract sample metadata from raw design_data into ParsedCsvData format.
+ *
+ * Looks for a `samples` array in the design data. For each sample, merges
+ * the `conditions` dict (the metadata table) with the `sample_name` to
+ * produce a flat tabular row. QC and blank samples are filtered out by
+ * their explicit `sample_type` field.
+ *
+ * Returns null if no samples with conditions are found.
+ */
+export function extractSamplesFromDesignData(
+  rawData: Record<string, unknown>,
+): ParsedCsvData | null {
+  const samples = rawData.samples
+  if (!Array.isArray(samples) || samples.length === 0) return null
+
+  // Single pass: filter QC/blank and collect all condition keys
+  const allConditionKeys: string[] = []
+  const keySet = new Set<string>()
+  const filteredSamples: Record<string, unknown>[] = []
+
+  for (const sample of samples) {
+    const sampleType = String((sample as Record<string, unknown>).sample_type ?? 'sample').toLowerCase()
+    if (sampleType === 'qc' || sampleType === 'blank') continue
+
+    filteredSamples.push(sample as Record<string, unknown>)
+    const conditions = (sample as Record<string, unknown>).conditions as Record<string, string> | undefined
+    if (conditions && typeof conditions === 'object') {
+      for (const key of Object.keys(conditions)) {
+        if (!keySet.has(key)) {
+          keySet.add(key)
+          allConditionKeys.push(key)
+        }
+      }
+    }
+  }
+
+  if (filteredSamples.length === 0 || allConditionKeys.length === 0) return null
+
+  const columns = ['sample_name', ...allConditionKeys]
+  const rows: Record<string, string>[] = filteredSamples.map((sample) => {
+    const conditions = (sample.conditions as Record<string, string>) ?? {}
+    const row: Record<string, string> = {
+      sample_name: String(sample.sample_name ?? ''),
+    }
+    for (const key of allConditionKeys) {
+      row[key] = conditions[key] ?? ''
+    }
+    return row
+  })
+
+  return { columns, rows, sampleColumn: 'sample_name', delimiter: ',' }
+}
+
+export function computeGroupsFromCsv(
+  csvData: ParsedCsvData,
+  columns: ColumnInfo[],
+  enabledFields: Set<number>,
+): { groups: SampleGroup[]; metadata: MetadataRow[]; excludedSamples: string[] } {
+  const groupMap = new Map<string, string[]>()
+  const metadata: MetadataRow[] = []
+  const enabledCols = columns
+    .filter(c => enabledFields.has(c.index))
+    .sort((a, b) => a.index - b.index)
+
+  for (const row of csvData.rows) {
+    const sampleName = row[csvData.sampleColumn]
+
+    // Build group key from enabled CSV column values
+    // Use originalName for CSV row lookup (survives user renames), display name for group key
+    const keyParts = enabledCols.map(col => row[col.originalName ?? col.name])
+    const groupKey = keyParts.join(' / ')
+
+    if (!groupMap.has(groupKey)) {
+      groupMap.set(groupKey, [])
+    }
+    groupMap.get(groupKey)!.push(sampleName)
+
+    // Build metadata row with ALL columns — use display name as key, original for lookup
+    const fields: Record<string, string> = {}
+    for (const col of columns) {
+      fields[col.name] = row[col.originalName ?? col.name]
+    }
+    metadata.push({ sampleName, fields, group: groupKey })
+  }
+
+  // Convert to SampleGroup[]
+  const groups: SampleGroup[] = []
+  let colorIdx = 0
+  for (const [name, samples] of groupMap) {
+    groups.push({
+      name,
+      color: DEFAULT_COLORS[colorIdx % DEFAULT_COLORS.length],
+      samples,
+    })
+    colorIdx++
+  }
+
+  return { groups, metadata, excludedSamples: [] }
+}
+
+// --- Reactive composable ---
+
+/** Parses sample names or CSV data to propose group assignments with outlier detection and preview. */
+export function useAutoGroup() {
+  const inputMode = ref<InputMode>('paste')
+  const rawText = ref('')
+  const csvData = ref<ParsedCsvData | null>(null)
+  const delimiter = ref('_')
+  const dominantFieldCount = ref(1)
+  const minFieldCount = ref(1)
+  const outliers = ref<OutlierInfo[]>([])
+  const fields = ref<ColumnInfo[]>([])
+  const fieldNames = ref<Record<number, string>>({})
+  const enabledFields = ref(new Set<number>())
+
+  const isTabularMode = computed(() =>
+    (inputMode.value === 'csv' || inputMode.value === 'experiment') && csvData.value !== null,
+  )
+
+  const samples = computed(() => {
+    if (isTabularMode.value && csvData.value) {
+      return csvData.value.rows.map(r => r[csvData.value!.sampleColumn])
+    }
+    return rawText.value
+      .split('\n')
+      .map(l => l.trim())
+      .filter(l => l.length > 0)
+  })
+
+  const hasOutliers = computed(() => outliers.value.length > 0)
+
+  const conformingSamples = computed(() => {
+    const outlierIndices = new Set(outliers.value.map(o => o.index))
+    return samples.value.filter((_, i) => !outlierIndices.has(i))
+  })
+
+  const outlierActions = computed(() => {
+    const map = new Map<number, OutlierAction>()
+    for (const o of outliers.value) {
+      map.set(o.index, o.action)
+    }
+    return map
+  })
+
+  const effectiveColumns = computed(() => {
+    return fields.value.map(col => ({
+      ...col,
+      name: fieldNames.value[col.index] ?? col.name,
+    }))
+  })
+
+  const _computedResult = computed((): AutoGroupResult => {
+    if (effectiveColumns.value.length === 0 || enabledFields.value.size === 0) {
+      return { groups: [], metadata: [], excludedSamples: [] }
+    }
+
+    if (isTabularMode.value && csvData.value) {
+      return computeGroupsFromCsv(
+        csvData.value,
+        effectiveColumns.value,
+        enabledFields.value,
+      )
+    }
+
+    return computeGroups(
+      samples.value,
+      effectiveColumns.value,
+      enabledFields.value,
+      outlierActions.value,
+      delimiter.value,
+      minFieldCount.value,
+    )
+  })
+
+  const groups = computed(() => _computedResult.value.groups)
+  const metadata = computed(() => _computedResult.value.metadata)
+  const excludedSamples = computed(() => _computedResult.value.excludedSamples)
+
+  const allSingletons = computed(() =>
+    groups.value.length > 1 && groups.value.every(g => g.samples.length === 1),
+  )
+
+  const result = _computedResult
+
+  function parseInput() {
+    if (isTabularMode.value) {
+      parseCsvInput()
+    } else {
+      parsePasteInput()
+    }
+  }
+
+  function parsePasteInput() {
+    const lines = samples.value
+    if (lines.length === 0) return
+
+    const analysis = analyzeDelimiter(lines)
+    delimiter.value = analysis.delimiter
+    dominantFieldCount.value = analysis.dominantFieldCount
+
+    // Use dominantFieldCount as outlier threshold so QC/test samples with
+    // fewer fields than the majority are correctly flagged
+    outliers.value = detectOutliers(lines, analysis.delimiter, analysis.dominantFieldCount)
+
+    // Apply smart default actions: auto-classify QC/test samples
+    for (const outlier of outliers.value) {
+      outlier.action = classifyOutlierAction(outlier.sample, analysis.delimiter)
+    }
+
+    const conforming = lines.filter(
+      (_, i) => !outliers.value.some(o => o.index === i)
+    )
+
+    // Recompute minFieldCount from conforming samples only
+    const conformingFieldCounts = conforming.map(s => s.split(analysis.delimiter).length)
+    minFieldCount.value = conformingFieldCounts.length > 0
+      ? Math.min(...conformingFieldCounts)
+      : analysis.dominantFieldCount
+
+    fields.value = extractColumns(conforming, analysis.delimiter, minFieldCount.value)
+
+    fieldNames.value = {}
+    const rowCount = conforming.length
+    enabledFields.value = new Set(
+      fields.value.filter(f => isUsefulField(f, rowCount)).map(f => f.index),
+    )
+  }
+
+  function parseCsvInput() {
+    if (!csvData.value) return
+
+    const csv = csvData.value
+    const nonSampleCols = csv.columns.filter(c => c !== csv.sampleColumn)
+
+    fields.value = nonSampleCols.map((col, i) => {
+      const values = csv.rows.map(r => r[col])
+      const unique = [...new Set(values)]
+      return {
+        index: i,
+        name: col,
+        originalName: col,
+        uniqueValues: unique,
+        cardinality: unique.length,
+      }
+    })
+
+    // For CSV, no outliers
+    outliers.value = []
+    delimiter.value = csv.delimiter
+    dominantFieldCount.value = csv.columns.length
+
+    fieldNames.value = Object.fromEntries(fields.value.map(f => [f.index, f.name]))
+    const rowCount = csv.rows.length
+    enabledFields.value = new Set(
+      fields.value.filter(f => isUsefulField(f, rowCount)).map(f => f.index),
+    )
+  }
+
+  function setOutlierAction(index: number, action: OutlierAction) {
+    const outlier = outliers.value.find(o => o.index === index)
+    if (outlier) {
+      outlier.action = action
+      // Trigger reactivity
+      outliers.value = [...outliers.value]
+    }
+  }
+
+  function setAllOutlierActions(action: OutlierAction) {
+    for (const outlier of outliers.value) {
+      outlier.action = action
+    }
+    outliers.value = [...outliers.value]
+  }
+
+  function toggleField(index: number) {
+    const newSet = new Set(enabledFields.value)
+    if (newSet.has(index)) {
+      newSet.delete(index)
+    } else {
+      newSet.add(index)
+    }
+    enabledFields.value = newSet
+  }
+
+  function renameField(index: number, name: string) {
+    fieldNames.value = { ...fieldNames.value, [index]: name }
+  }
+
+  function loadExperimentData(rawData: Record<string, unknown>): boolean {
+    const parsed = extractSamplesFromDesignData(rawData)
+    if (!parsed) return false
+
+    inputMode.value = 'experiment'
+    csvData.value = parsed
+    parseCsvInput()
+    return true
+  }
+
+  function reset() {
+    rawText.value = ''
+    csvData.value = null
+    delimiter.value = '_'
+    dominantFieldCount.value = 1
+    minFieldCount.value = 1
+    outliers.value = []
+    fields.value = []
+    fieldNames.value = {}
+    enabledFields.value = new Set()
+  }
+
+  return {
+    // State
+    inputMode,
+    rawText,
+    csvData,
+    delimiter,
+    dominantFieldCount,
+    minFieldCount,
+    outliers,
+    fields,
+    fieldNames,
+    enabledFields,
+    // Computed
+    samples,
+    hasOutliers,
+    conformingSamples,
+    groups,
+    metadata,
+    excludedSamples,
+    allSingletons,
+    result,
+    effectiveColumns,
+    // Actions
+    parseInput,
+    loadExperimentData,
+    setOutlierAction,
+    setAllOutlierActions,
+    toggleField,
+    renameField,
+    reset,
+  }
+}