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

package/src/templates/samplePrepBuilder.ts

@@ -0,0 +1,51 @@
+import { idFromName } from './builderIdUtils'
+import { normalizeSamplePrepStep } from './sampleNormalizers'
+import { createTemplateEnvelope } from './templateEnvelopes'
+import { validateSamplePrepData } from './templateValidators'
+import type {
+  CreateSamplePrepTemplateOptions,
+  SamplePrepStep,
+  SamplePrepTemplate,
+  SamplePrepTemplateData,
+} from './types'
+
+export function createSamplePrepTemplate(
+  options: CreateSamplePrepTemplateOptions
+): SamplePrepTemplate {
+  const prepType = options.prepType ?? 'extraction'
+  const volumeUnit = options.volumeUnit ?? 'uL'
+  const steps: SamplePrepStep[] = []
+  let order = 1
+
+  for (const [index, sample] of options.samples.entries()) {
+    if (typeof sample !== 'string') {
+      const step = normalizeSamplePrepStep(sample, prepType, volumeUnit, order, index)
+      steps.push(step)
+      order = Math.max(order, step.order + 1)
+      continue
+    }
+    const sourceSampleId = idFromName(sample, `sample-${index + 1}`)
+    steps.push({
+      id: `${sourceSampleId}-prep`,
+      order,
+      type: prepType,
+      name: `Prepare ${sample}`,
+      sourceSampleId,
+      destinationSampleId: `${sourceSampleId}-prepared`,
+      inputVolume: options.inputVolume,
+      outputVolume: options.outputVolume,
+      volumeUnit,
+      status: 'planned',
+      metadata: {},
+    })
+    order += 1
+  }
+
+  const data: SamplePrepTemplateData = {
+    protocolName: options.protocolName ?? 'Sample preparation',
+    steps,
+    metadata: options.metadata ?? {},
+  }
+  validateSamplePrepData(data)
+  return createTemplateEnvelope('sample-prep', data, options.metadata ?? {})
+}

package/src/templates/sampleSheetAdapters.ts

@@ -0,0 +1,75 @@
+import type {
+  DataFrameColumn,
+  SelectOption,
+} from '../types'
+import { getTemplateData } from './templateEnvelopes'
+import { validateSampleSheetData } from './templateValidators'
+import type {
+  SampleColumnsAdapterResult,
+  SampleDataFrameAdapterResult,
+  SampleOptionsAdapterResult,
+  SampleRowsAdapterResult,
+  SampleSheetTemplate,
+  SampleSheetTemplateData,
+} from './types'
+
+export function toSampleRows(
+  template: SampleSheetTemplate | SampleSheetTemplateData
+): SampleRowsAdapterResult {
+  const data = getTemplateData(template, 'sample-sheet')
+  validateSampleSheetData(data)
+  return data.samples.map(sample => ({
+    sampleId: sample.sampleId,
+    name: sample.name,
+    group: sample.group,
+    batch: sample.batch,
+    replicate: sample.replicate,
+    plateId: sample.plateId,
+    wellId: sample.wellId,
+    ...(sample.metadata ?? {}),
+  }))
+}
+
+export function toSampleColumns(
+  template: SampleSheetTemplate | SampleSheetTemplateData
+): SampleColumnsAdapterResult {
+  const data = getTemplateData(template, 'sample-sheet')
+  validateSampleSheetData(data)
+  return data.columns.map((column): DataFrameColumn<Record<string, unknown>> => ({
+    key: sampleColumnKey(column.id),
+    label: column.label,
+    sortable: true,
+    align: column.type === 'number' || column.type === 'integer' ? 'right' : 'left',
+  }))
+}
+
+export function toSampleDataFrame(
+  template: SampleSheetTemplate | SampleSheetTemplateData
+): SampleDataFrameAdapterResult {
+  return {
+    data: toSampleRows(template),
+    columns: toSampleColumns(template),
+    rowKey: 'sampleId',
+  }
+}
+
+export function toSampleOptions(
+  template: SampleSheetTemplate | SampleSheetTemplateData
+): SampleOptionsAdapterResult {
+  const data = getTemplateData(template, 'sample-sheet')
+  validateSampleSheetData(data)
+  return data.samples.map((sample): SelectOption<string> => ({
+    value: sample.sampleId,
+    label: sample.name ?? sample.sampleId,
+    description: [sample.group, sample.batch].filter(Boolean).join(' / ') || undefined,
+  }))
+}
+
+function sampleColumnKey(columnId: string): string {
+  const aliases: Record<string, string> = {
+    sample_id: 'sampleId',
+    plate_id: 'plateId',
+    well_id: 'wellId',
+  }
+  return aliases[columnId] ?? columnId
+}

package/src/templates/sampleSheetBuilder.ts

@@ -0,0 +1,23 @@
+import { normalizeSampleRecord } from './sampleNormalizers'
+import { createTemplateEnvelope } from './templateEnvelopes'
+import { validateSampleSheetData } from './templateValidators'
+import type {
+  CreateSampleSheetTemplateOptions,
+  SampleSheetTemplate,
+  SampleSheetTemplateData,
+} from './types'
+
+export function createSampleSheetTemplate(
+  options: CreateSampleSheetTemplateOptions
+): SampleSheetTemplate {
+  const data: SampleSheetTemplateData = {
+    samples: options.samples.map(normalizeSampleRecord),
+    columns: options.columns ?? [
+      { id: 'sampleId', label: 'Sample ID', type: 'string', required: true, groupable: false },
+      { id: 'name', label: 'Name', type: 'string', required: false, groupable: false },
+    ],
+    groups: options.groups ?? [],
+  }
+  validateSampleSheetData(data)
+  return createTemplateEnvelope('sample-sheet', data, options.metadata ?? {})
+}

package/src/templates/targetedMetabolomicsCollectionBuilder.ts

@@ -0,0 +1,79 @@
+import { createAssayMatrixTemplate } from './assayMatrixBuilder'
+import { createCalibrationCurveTemplate } from './calibrationCurveBuilder'
+import { createInstrumentRunTemplate } from './instrumentRunBuilder'
+import { createReagentListTemplate } from './reagentListBuilder'
+import { createSamplePrepTemplate } from './samplePrepBuilder'
+import { createSampleSheetTemplate } from './sampleSheetBuilder'
+import { presetSampleRecords } from './sampleNormalizers'
+import {
+  firstFeatureName,
+  normalizeInternalStandardReagents,
+  normalizeMetaboliteFeatures,
+  targetedMetabolomicsRunItems,
+} from './targetedMetabolomicsHelpers'
+import { createTemplateCollection } from './templateEnvelopes'
+import type {
+  CreateTargetedMetabolomicsCollectionOptions,
+  TemplateCollectionEnvelope,
+} from './types'
+
+export function createTargetedMetabolomicsCollection(
+  options: CreateTargetedMetabolomicsCollectionOptions = {}
+): TemplateCollectionEnvelope {
+  const sampleRecords = presetSampleRecords(options.samples ?? ['S001', 'S002'])
+  const responseUnit = options.responseUnit ?? 'peak area ratio'
+  const concentrationUnit = options.concentrationUnit ?? 'uM'
+  const metaboliteFeatures = normalizeMetaboliteFeatures(
+    options.metabolites ?? ['Glucose', 'Lactate', 'Pyruvate'],
+    responseUnit,
+  )
+  const sampleSheet = createSampleSheetTemplate({ samples: sampleRecords })
+  const samplePrep = createSamplePrepTemplate({
+    samples: sampleRecords.map(sample => sample.sampleId),
+    prepType: options.prepType ?? 'extraction',
+    protocolName: 'Metabolomics sample preparation',
+    outputVolume: options.outputVolume ?? 50,
+    metadata: { assay: 'targeted-metabolomics' },
+  })
+  const reagents = createReagentListTemplate({
+    reagents: normalizeInternalStandardReagents(
+      options.internalStandards ?? ['Stable isotope internal standard mix'],
+    ),
+    metadata: { assay: 'targeted-metabolomics' },
+  })
+  const calibrationCurve = createCalibrationCurveTemplate({
+    concentrations: options.standardConcentrations ?? [0.1, 1, 10, 100],
+    analyte: options.calibrationAnalyte ?? firstFeatureName(metaboliteFeatures, 'Metabolite panel'),
+    unit: concentrationUnit,
+    responseUnit,
+    model: 'linear-weighted-1-x',
+    includeQc: options.includeQc,
+    metadata: { assay: 'targeted-metabolomics' },
+  })
+  const instrumentRun = createInstrumentRunTemplate({
+    items: targetedMetabolomicsRunItems(
+      sampleRecords,
+      calibrationCurve.data.points,
+      options.includeQc !== false,
+    ),
+    method: options.method ?? 'Targeted metabolomics',
+    instrument: options.instrument ?? 'LC-MS',
+    includeBlanks: false,
+    includeQc: false,
+    metadata: { assay: 'targeted-metabolomics' },
+  })
+  const assayMatrix = createAssayMatrixTemplate({
+    samples: sampleRecords.map(sample => ({
+      sampleId: sample.sampleId,
+      name: sample.name,
+      group: sample.group,
+      metadata: sample.metadata ?? {},
+    })),
+    features: metaboliteFeatures,
+    metadata: { assay: 'targeted-metabolomics', responseUnit },
+  })
+  return createTemplateCollection(
+    [sampleSheet, samplePrep, reagents, instrumentRun, calibrationCurve, assayMatrix],
+    { preset: 'targeted-metabolomics', ...(options.metadata ?? {}) }
+  )
+}

package/src/templates/targetedMetabolomicsHelpers.ts

@@ -0,0 +1,102 @@
+import type {
+  AssayFeature,
+  CalibrationPoint,
+  InstrumentRunItemInput,
+  ReagentTemplateInput,
+  SampleRecord,
+} from './types'
+import {
+  normalizeAssayFeature,
+  normalizeReagent,
+} from './assayNormalizers'
+import { idFromName } from './builderIdUtils'
+
+export function normalizeMetaboliteFeatures(
+  metabolites: Array<string | AssayFeature>,
+  responseUnit: string,
+): AssayFeature[] {
+  return metabolites.map((metabolite, index) => {
+    if (typeof metabolite === 'string') {
+      return {
+        id: idFromName(metabolite, `metabolite-${index + 1}`),
+        name: metabolite,
+        type: 'metabolite',
+        unit: responseUnit,
+        metadata: { quantitation: 'targeted' },
+      }
+    }
+
+    const feature = normalizeAssayFeature(metabolite)
+    return {
+      ...feature,
+      type: feature.type ?? 'metabolite',
+      unit: feature.unit ?? responseUnit,
+      metadata: {
+        quantitation: 'targeted',
+        ...feature.metadata,
+      },
+    }
+  })
+}
+
+export function normalizeInternalStandardReagents(
+  internalStandards: Array<string | ReagentTemplateInput>,
+): ReagentTemplateInput[] {
+  return internalStandards.map((standard, index) => {
+    if (typeof standard === 'string') {
+      return {
+        id: idFromName(standard, `internal-standard-${index + 1}`),
+        name: standard,
+        kind: 'compound',
+        metadata: { role: 'internal-standard' },
+      }
+    }
+
+    const reagent = normalizeReagent(standard)
+    return {
+      ...reagent,
+      kind: standard.kind ?? 'compound',
+      metadata: {
+        role: 'internal-standard',
+        ...reagent.metadata,
+      },
+    }
+  })
+}
+
+export function targetedMetabolomicsRunItems(
+  samples: SampleRecord[],
+  calibrationPoints: CalibrationPoint[],
+  includeQc: boolean,
+): InstrumentRunItemInput[] {
+  const calibrationItems = calibrationPoints
+    .filter(point => point.role !== 'qc' || includeQc)
+    .filter(point => point.role === 'blank' || point.role === 'standard' || point.role === 'qc')
+    .map((point): InstrumentRunItemInput => ({
+      id: `${point.id}-run`,
+      kind: calibrationRunItemKind(point.role),
+      name: point.level,
+      metadata: {
+        concentration: point.concentration,
+        unit: point.unit,
+        role: point.role,
+      },
+    }))
+
+  const sampleItems = samples.map((sample): InstrumentRunItemInput => ({
+    sampleId: sample.sampleId,
+    name: sample.name ?? sample.sampleId,
+    kind: 'sample',
+  }))
+
+  return [...calibrationItems, ...sampleItems]
+}
+
+export function firstFeatureName(features: AssayFeature[], fallback: string): string {
+  return features.find(feature => feature.name)?.name ?? fallback
+}
+
+function calibrationRunItemKind(role: CalibrationPoint['role']): 'blank' | 'standard' | 'qc' {
+  if (role === 'blank' || role === 'standard' || role === 'qc') return role
+  return 'standard'
+}

package/src/templates/templateControlSchemas.ts

@@ -0,0 +1,320 @@
+import {
+  CONCENTRATION_UNITS,
+  ICONS,
+  PLATE_FORMAT_OPTIONS,
+} from './controlSchemaConstants'
+import type {
+  BioTemplateControlSchema,
+} from './controlSchemaTypes'
+import type {
+  TemplateId,
+} from './types'
+
+export const templateControlSchemas = {
+  'plate-map': {
+    plateName: {
+      label: 'Plate name',
+      default: 'Plate 1',
+      section: 'layout',
+      sectionLabel: 'Layout',
+      sectionSubtitle: 'Plate geometry',
+      view: 'design',
+      sidebar: { icon: ICONS.plate, iconColor: '#6366f1', iconBg: '#e0e7ff' },
+    },
+    plateFormat: {
+      label: 'Format',
+      default: 96,
+      options: PLATE_FORMAT_OPTIONS,
+      section: 'layout',
+      view: 'design',
+    },
+    sampleNames: {
+      type: 'tags',
+      label: 'Samples',
+      default: ['Control', 'Treatment'],
+      section: 'samples',
+      sectionLabel: 'Samples',
+      sectionSubtitle: 'Groups and legend',
+      view: 'design',
+      sidebar: { icon: ICONS.samples, iconColor: '#10b981', iconBg: '#d1fae5' },
+    },
+  },
+  'sample-sheet': {
+    sampleCount: {
+      type: 'number',
+      label: 'Sample count',
+      default: 2,
+      min: 1,
+      max: 10000,
+      section: 'samples',
+      sectionLabel: 'Samples',
+      sectionSubtitle: 'Metadata table',
+      view: 'design',
+      sidebar: { icon: ICONS.samples, iconColor: '#10b981', iconBg: '#d1fae5' },
+    },
+    includeGroups: {
+      label: 'Include groups',
+      default: true,
+      section: 'samples',
+      view: 'design',
+    },
+    includeBatch: {
+      label: 'Include batch',
+      default: false,
+      section: 'columns',
+      sectionLabel: 'Columns',
+      view: 'design',
+      sidebar: { icon: ICONS.table, iconColor: '#0ea5e9', iconBg: '#e0f2fe' },
+    },
+  },
+  'sample-prep': {
+    prepType: {
+      label: 'Prep type',
+      default: 'extraction',
+      options: ['extraction', 'dilution', 'normalization', 'transfer', 'quench', 'custom'],
+      section: 'protocol',
+      sectionLabel: 'Protocol',
+      sectionSubtitle: 'Prep workflow',
+      view: 'design',
+      sidebar: { icon: ICONS.run, iconColor: '#f97316', iconBg: '#ffedd5' },
+    },
+    volumeUnit: {
+      label: 'Volume unit',
+      default: 'uL',
+      options: ['uL', 'mL'],
+      section: 'protocol',
+      view: 'design',
+    },
+    outputVolume: {
+      type: 'number',
+      label: 'Output volume',
+      default: 50,
+      min: 0,
+      section: 'protocol',
+      view: 'design',
+    },
+  },
+  'dose-response': {
+    unit: {
+      label: 'Dose unit',
+      default: 'uM',
+      options: CONCENTRATION_UNITS,
+      section: 'dose',
+      sectionLabel: 'Dose Design',
+      sectionSubtitle: 'Concentration series',
+      view: 'design',
+      sidebar: { icon: ICONS.dose, iconColor: '#8b5cf6', iconBg: '#ede9fe' },
+    },
+    replicates: {
+      type: 'number',
+      label: 'Replicates',
+      default: 3,
+      min: 1,
+      max: 24,
+      section: 'dose',
+      view: 'design',
+    },
+    includePlateLayout: {
+      label: 'Create plate layout',
+      default: true,
+      section: 'layout',
+      sectionLabel: 'Layout',
+      sectionSubtitle: 'Well assignment',
+      view: 'design',
+      sidebar: { icon: ICONS.plate, iconColor: '#6366f1', iconBg: '#e0e7ff', defaultOpen: false },
+    },
+  },
+  'calibration-curve': {
+    analyte: {
+      label: 'Analyte',
+      default: 'Analyte',
+      section: 'standards',
+      sectionLabel: 'Standards',
+      sectionSubtitle: 'Curve setup',
+      view: 'analysis',
+      sidebar: { icon: ICONS.dose, iconColor: '#8b5cf6', iconBg: '#ede9fe' },
+    },
+    model: {
+      label: 'Model',
+      default: 'linear',
+      options: ['linear', 'linear-weighted-1-x', 'linear-weighted-1-x2', 'quadratic', 'four-parameter-logistic'],
+      section: 'fit',
+      sectionLabel: 'Fit',
+      view: 'analysis',
+      sidebar: { icon: ICONS.settings, iconColor: '#6366f1', iconBg: '#e0e7ff' },
+    },
+    minRSquared: {
+      type: 'number',
+      label: 'Minimum R squared',
+      default: 0.99,
+      min: 0,
+      max: 1,
+      props: { step: 0.001 },
+      section: 'fit',
+      view: 'analysis',
+    },
+  },
+  'time-course': {
+    timeUnit: {
+      label: 'Time unit',
+      default: 'hour',
+      options: ['second', 'minute', 'hour', 'day', 'week'],
+      section: 'schedule',
+      sectionLabel: 'Schedule',
+      sectionSubtitle: 'Sampling timeline',
+      view: 'design',
+      sidebar: { icon: ICONS.run, iconColor: '#0ea5e9', iconBg: '#e0f2fe' },
+    },
+    replicates: {
+      type: 'number',
+      label: 'Replicates',
+      default: 3,
+      min: 1,
+      max: 24,
+      section: 'samples',
+      sectionLabel: 'Samples',
+      view: 'design',
+      sidebar: { icon: ICONS.samples, iconColor: '#10b981', iconBg: '#d1fae5' },
+    },
+  },
+  'protocol-steps': {
+    defaultDuration: {
+      type: 'number',
+      label: 'Default duration',
+      default: 30,
+      min: 0,
+      section: 'protocol',
+      sectionLabel: 'Protocol',
+      sectionSubtitle: 'Step defaults',
+      view: 'design',
+      sidebar: { icon: ICONS.run, iconColor: '#f97316', iconBg: '#ffedd5' },
+      props: { suffix: 'min' },
+    },
+    editable: {
+      label: 'Editable timeline',
+      default: true,
+      section: 'protocol',
+      view: 'design',
+    },
+  },
+  'assay-matrix': {
+    featureType: {
+      label: 'Feature type',
+      default: 'metabolite',
+      options: ['metabolite', 'protein', 'gene', 'cell', 'compound', 'readout', 'other'],
+      section: 'features',
+      sectionLabel: 'Features',
+      sectionSubtitle: 'Measurement matrix',
+      view: 'analysis',
+      sidebar: { icon: ICONS.table, iconColor: '#0ea5e9', iconBg: '#e0f2fe' },
+    },
+    normalizeValues: {
+      label: 'Normalize values',
+      default: false,
+      section: 'analysis',
+      sectionLabel: 'Analysis',
+      view: 'analysis',
+      sidebar: { icon: ICONS.settings, iconColor: '#6366f1', iconBg: '#e0e7ff', defaultOpen: false },
+    },
+  },
+  'reagent-list': {
+    reagentKind: {
+      label: 'Reagent kind',
+      default: 'reagent',
+      options: ['compound', 'antibody', 'primer', 'enzyme', 'buffer', 'media', 'kit', 'reagent', 'other'],
+      section: 'inventory',
+      sectionLabel: 'Inventory',
+      sectionSubtitle: 'Reagent metadata',
+      view: 'design',
+      sidebar: { icon: ICONS.table, iconColor: '#10b981', iconBg: '#d1fae5' },
+    },
+    trackStock: {
+      label: 'Track stock level',
+      default: true,
+      section: 'inventory',
+      view: 'design',
+    },
+  },
+  'flow-cytometry-panel': {
+    markers: {
+      type: 'tags',
+      label: 'Markers',
+      default: ['CD3', 'CD4', 'CD8'],
+      section: 'panel',
+      sectionLabel: 'Panel',
+      sectionSubtitle: 'Markers and controls',
+      view: 'design',
+      sidebar: { icon: ICONS.table, iconColor: '#0ea5e9', iconBg: '#e0f2fe' },
+    },
+    instrument: {
+      label: 'Instrument',
+      default: 'Flow cytometer',
+      section: 'panel',
+      sectionLabel: 'Panel',
+      sectionSubtitle: 'Markers and controls',
+      view: 'design',
+      sidebar: { icon: ICONS.settings, iconColor: '#6366f1', iconBg: '#e0e7ff' },
+    },
+    includeDefaultControls: {
+      label: 'Default controls',
+      default: true,
+      section: 'panel',
+      view: 'design',
+    },
+  },
+  'instrument-run': {
+    instrument: {
+      label: 'Instrument',
+      default: 'LC-MS',
+      options: ['LC-MS', 'GC-MS', 'Orbitrap', 'Triple quadrupole', 'Plate reader', 'Other'],
+      section: 'acquisition',
+      sectionLabel: 'Acquisition',
+      sectionSubtitle: 'Run queue',
+      view: 'run',
+      sidebar: { icon: ICONS.run, iconColor: '#ef4444', iconBg: '#fee2e2' },
+    },
+    method: {
+      label: 'Method',
+      default: 'Default method',
+      section: 'acquisition',
+      view: 'run',
+    },
+    includeQc: {
+      label: 'Include QC',
+      default: true,
+      section: 'quality',
+      sectionLabel: 'Quality Control',
+      view: 'run',
+      sidebar: { icon: ICONS.settings, iconColor: '#6366f1', iconBg: '#e0e7ff', defaultOpen: false },
+    },
+  },
+  'qpcr-plate': {
+    chemistry: {
+      label: 'Chemistry',
+      default: 'sybr',
+      options: ['sybr', 'taqman', 'probe', 'evagreen', 'other'],
+      section: 'assay',
+      sectionLabel: 'Assay',
+      sectionSubtitle: 'qPCR setup',
+      view: 'design',
+      sidebar: { icon: ICONS.plate, iconColor: '#6366f1', iconBg: '#e0e7ff' },
+    },
+    replicates: {
+      type: 'number',
+      label: 'Replicates',
+      default: 3,
+      min: 1,
+      max: 12,
+      section: 'assay',
+      view: 'design',
+    },
+    includeNoTemplateControls: {
+      label: 'No-template controls',
+      default: true,
+      section: 'controls',
+      sectionLabel: 'Controls',
+      view: 'design',
+      sidebar: { icon: ICONS.settings, iconColor: '#8b5cf6', iconBg: '#ede9fe', defaultOpen: false },
+    },
+  },
+} satisfies Record<TemplateId, BioTemplateControlSchema>