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

package/src/templates/defaultBioTemplateBuilder.ts

@@ -0,0 +1,124 @@
+import { getBioTemplateInfo } from './catalog'
+import { createAssayMatrixTemplate } from './assayMatrixBuilder'
+import { createCalibrationCurveTemplate } from './calibrationCurveBuilder'
+import { createDoseResponseTemplate } from './doseResponseBuilder'
+import { createFlowCytometryPanelTemplate } from './flowCytometryPanelBuilder'
+import { createInstrumentRunTemplate } from './instrumentRunBuilder'
+import { createPlateMapTemplate } from './plateMapBuilder'
+import { createProtocolStepsTemplate } from './protocolStepsBuilder'
+import { createQpcrPlateTemplate } from './qpcrPlateBuilder'
+import { createReagentListTemplate } from './reagentListBuilder'
+import { createSamplePrepTemplate } from './samplePrepBuilder'
+import { createSampleSheetTemplate } from './sampleSheetBuilder'
+import { createTimeCourseTemplate } from './timeCourseBuilder'
+import type {
+  BioTemplateEnvelope,
+  TemplateId,
+} from './types'
+
+export function createDefaultBioTemplate(templateId: TemplateId | string): BioTemplateEnvelope<unknown> {
+  const template = getBioTemplateInfo(templateId)
+  if (!template) {
+    throw new Error(`Unknown bio template '${templateId}'.`)
+  }
+
+  switch (template.template_id) {
+    case 'plate-map':
+      return createPlateMapTemplate({
+        name: 'Plate 1',
+        samples: ['Control', 'Treatment'],
+      })
+    case 'sample-sheet':
+      return createSampleSheetTemplate({
+        samples: [
+          { sampleId: 'S001', name: 'Control 1', group: 'Control' },
+          { sampleId: 'S002', name: 'Treatment 1', group: 'Treatment' },
+        ],
+      })
+    case 'sample-prep':
+      return createSamplePrepTemplate({
+        samples: ['S001', 'S002'],
+        prepType: 'extraction',
+        outputVolume: 50,
+      })
+    case 'dose-response':
+      return createDoseResponseTemplate({
+        compounds: {
+          'Compound A': [10, 1, 0.1],
+        },
+        unit: 'uM',
+        replicates: 3,
+      })
+    case 'calibration-curve':
+      return createCalibrationCurveTemplate({
+        concentrations: [0.1, 1, 10, 100],
+        analyte: 'Analyte',
+        unit: 'uM',
+      })
+    case 'time-course':
+      return createTimeCourseTemplate({
+        timepoints: [0, 6, 24],
+        unit: 'hour',
+        conditions: ['Control', 'Treatment'],
+        replicates: 3,
+      })
+    case 'protocol-steps':
+      return createProtocolStepsTemplate({
+        steps: [
+          {
+            id: 'seed-cells',
+            type: 'addition',
+            name: 'Seed cells',
+            description: 'Add cells to wells or culture vessels.',
+            duration: 15,
+          },
+          {
+            id: 'incubate-overnight',
+            type: 'incubation',
+            name: 'Incubate overnight',
+            duration: 960,
+            parameters: { temperature: '37 C', co2: '5%' },
+          },
+          {
+            id: 'measure-readout',
+            type: 'measurement',
+            name: 'Measure readout',
+            duration: 45,
+          },
+        ],
+      })
+    case 'assay-matrix':
+      return createAssayMatrixTemplate({
+        samples: ['S001', 'S002'],
+        features: ['Lactate', 'Glucose'],
+        values: {
+          s001: { lactate: 1.2, glucose: 5.4 },
+          s002: { lactate: 2.1, glucose: 4.8 },
+        },
+      })
+    case 'reagent-list':
+      return createReagentListTemplate({
+        reagents: ['DMSO', 'Compound A', 'Anti-HA antibody'],
+      })
+    case 'flow-cytometry-panel':
+      return createFlowCytometryPanelTemplate({
+        markers: ['CD3', 'CD4', 'CD8'],
+        instrument: 'BD LSRFortessa',
+      })
+    case 'instrument-run':
+      return createInstrumentRunTemplate({
+        items: ['S001', 'S002'],
+        instrument: 'LC-MS',
+        method: 'Default method',
+      })
+    case 'qpcr-plate':
+      return createQpcrPlateTemplate({
+        samples: ['Control', 'Treatment'],
+        targets: ['ACTB', 'GAPDH'],
+        replicates: 3,
+        instrument: 'QuantStudio',
+      })
+    default:
+      throw new Error(`Unknown bio template '${templateId}'.`)
+  }
+}

package/src/templates/doseResponseAdapters.ts

@@ -0,0 +1,45 @@
+import type {
+  PlateCondition,
+  PlateMapEditorState,
+} from '../types'
+import { toPlateMapEditorState } from './plateMapAdapters'
+import { getTemplateData } from './templateEnvelopes'
+import { validateDoseResponseData } from './templateValidators'
+import type {
+  DoseConditionsAdapterResult,
+  DoseResponseTemplate,
+  DoseResponseTemplateData,
+} from './types'
+
+const CONDITION_COLORS = [
+  '#3B82F6',
+  '#10B981',
+  '#EF4444',
+  '#F59E0B',
+  '#8B5CF6',
+  '#F97316',
+  '#06B6D4',
+  '#14B8A6',
+  '#6B7280',
+]
+
+export function toDoseConditions(
+  template: DoseResponseTemplate | DoseResponseTemplateData
+): DoseConditionsAdapterResult {
+  const data = getTemplateData(template, 'dose-response')
+  validateDoseResponseData(data)
+  return data.compounds.map((compound, index): PlateCondition => ({
+    label: compound.name,
+    color: String(compound.metadata?.color ?? CONDITION_COLORS[index % CONDITION_COLORS.length]),
+    concentrations: compound.concentrations,
+    unit: data.unit,
+  }))
+}
+
+export function toDoseLayoutState(
+  template: DoseResponseTemplate | DoseResponseTemplateData
+): PlateMapEditorState | undefined {
+  const data = getTemplateData(template, 'dose-response')
+  validateDoseResponseData(data)
+  return data.layout ? toPlateMapEditorState(data.layout) : undefined
+}

package/src/templates/doseResponseBuilder.ts

@@ -0,0 +1,44 @@
+import { compoundIdFromName } from './builderIdUtils'
+import {
+  normalizeCompound,
+  normalizeControl,
+} from './calibrationNormalizers'
+import {
+  createTemplateEnvelope,
+  getTemplateData,
+} from './templateEnvelopes'
+import { validateDoseResponseData } from './templateValidators'
+import type {
+  CreateDoseResponseTemplateOptions,
+  DoseResponseTemplate,
+  DoseResponseTemplateData,
+  PlateMapTemplateData,
+} from './types'
+
+export function createDoseResponseTemplate(
+  options: CreateDoseResponseTemplateOptions
+): DoseResponseTemplate {
+  const compounds = Array.isArray(options.compounds)
+    ? options.compounds.map(normalizeCompound)
+    : Object.entries(options.compounds).map(([name, concentrations], index) => normalizeCompound({
+      id: compoundIdFromName(name, index),
+      name,
+      concentrations,
+      metadata: {},
+    }))
+
+  const layout = options.layout
+    ? getTemplateData<PlateMapTemplateData>(options.layout)
+    : undefined
+
+  const data: DoseResponseTemplateData = {
+    compounds,
+    unit: options.unit,
+    replicates: options.replicates ?? 1,
+    controls: (options.controls ?? []).map(normalizeControl),
+    layout,
+    metadata: options.metadata ?? {},
+  }
+  validateDoseResponseData(data)
+  return createTemplateEnvelope('dose-response', data, options.metadata ?? {})
+}

package/src/templates/elisaAssayCollectionBuilder.ts

@@ -0,0 +1,62 @@
+import { createAssayMatrixTemplate } from './assayMatrixBuilder'
+import { DEFAULT_SAMPLE_COLORS } from './builderDefaults'
+import { idFromName } from './builderIdUtils'
+import { createCalibrationCurveTemplate } from './calibrationCurveBuilder'
+import { createPlateMapTemplate } from './plateMapBuilder'
+import { createSampleSheetTemplate } from './sampleSheetBuilder'
+import { presetSampleRecords } from './sampleNormalizers'
+import { createTemplateCollection } from './templateEnvelopes'
+import type {
+  CreateElisaAssayCollectionOptions,
+  TemplateCollectionEnvelope,
+} from './types'
+
+export function createElisaAssayCollection(
+  options: CreateElisaAssayCollectionOptions = {}
+): TemplateCollectionEnvelope {
+  const sampleRecords = presetSampleRecords(options.samples ?? ['Control', 'Treatment'])
+  const analyte = options.analyte ?? 'Analyte'
+  const responseUnit = options.responseUnit ?? 'OD450'
+  const plate = createPlateMapTemplate({
+    name: options.plateName ?? 'ELISA plate',
+    format: options.plateFormat ?? 96,
+    samples: [
+      { id: 'blank', name: 'Blank' },
+      { id: 'standard', name: 'Standards' },
+      { id: 'qc', name: 'QC' },
+      ...sampleRecords.map((sample, index) => ({
+        id: sample.sampleId,
+        name: sample.name ?? sample.sampleId,
+        color: DEFAULT_SAMPLE_COLORS[index % DEFAULT_SAMPLE_COLORS.length],
+      })),
+    ],
+  })
+  const sampleSheet = createSampleSheetTemplate({ samples: sampleRecords })
+  const calibrationCurve = createCalibrationCurveTemplate({
+    concentrations: options.standardConcentrations ?? [1000, 100, 10, 1],
+    analyte,
+    unit: options.unit ?? 'pg/mL',
+    responseUnit,
+    model: 'four-parameter-logistic',
+  })
+  const assayMatrix = createAssayMatrixTemplate({
+    samples: sampleRecords.map(sample => ({
+      sampleId: sample.sampleId,
+      name: sample.name,
+      group: sample.group,
+      metadata: sample.metadata ?? {},
+    })),
+    features: [{
+      id: idFromName(analyte, 'analyte'),
+      name: analyte,
+      type: 'protein',
+      unit: responseUnit,
+      metadata: {},
+    }],
+    metadata: { analyte, responseUnit },
+  })
+  return createTemplateCollection(
+    [plate, sampleSheet, calibrationCurve, assayMatrix],
+    { preset: 'elisa-assay', ...(options.metadata ?? {}) }
+  )
+}

package/src/templates/flowCytometryAssayCollectionBuilder.ts

@@ -0,0 +1,41 @@
+import { createAssayMatrixTemplate } from './assayMatrixBuilder'
+import { createFlowCytometryPanelTemplate } from './flowCytometryPanelBuilder'
+import { createSampleSheetTemplate } from './sampleSheetBuilder'
+import { presetSampleRecords } from './sampleNormalizers'
+import { createTemplateCollection } from './templateEnvelopes'
+import type {
+  CreateFlowCytometryAssayCollectionOptions,
+  TemplateCollectionEnvelope,
+} from './types'
+
+export function createFlowCytometryAssayCollection(
+  options: CreateFlowCytometryAssayCollectionOptions = {}
+): TemplateCollectionEnvelope {
+  const sampleRecords = presetSampleRecords(options.samples ?? ['Control', 'Treatment'])
+  const markers = options.markers ?? ['CD3', 'CD4', 'CD8']
+  const sampleSheet = createSampleSheetTemplate({ samples: sampleRecords })
+  const flowPanel = createFlowCytometryPanelTemplate({
+    markers,
+    instrument: options.instrument ?? 'Flow cytometer',
+    includeDefaultControls: options.includeDefaultControls,
+  })
+  const assayMatrix = createAssayMatrixTemplate({
+    samples: sampleRecords.map(sample => ({
+      sampleId: sample.sampleId,
+      name: sample.name,
+      group: sample.group,
+      metadata: sample.metadata ?? {},
+    })),
+    features: options.features ?? flowPanel.data.markers.map(marker => ({
+      id: marker.id,
+      name: `${marker.marker}+ cells`,
+      type: 'cell',
+      unit: '%',
+      metadata: { marker: marker.marker, fluorophore: marker.fluorophore },
+    })),
+  })
+  return createTemplateCollection(
+    [sampleSheet, flowPanel, assayMatrix],
+    { preset: 'flow-cytometry-assay', ...(options.metadata ?? {}) }
+  )
+}

package/src/templates/flowCytometryPanelBuilder.ts

@@ -0,0 +1,53 @@
+import { idFromName } from './builderIdUtils'
+import {
+  defaultFlowControls,
+  normalizeFlowControl,
+  normalizeFlowMarker,
+} from './flowNormalizers'
+import { createTemplateEnvelope } from './templateEnvelopes'
+import { validateFlowCytometryPanelData } from './templateValidators'
+import type {
+  CreateFlowCytometryPanelTemplateOptions,
+  FlowCytometryPanelTemplate,
+  FlowCytometryPanelTemplateData,
+  FlowPanelControl,
+  FlowPanelMarker,
+} from './types'
+
+export function createFlowCytometryPanelTemplate(
+  options: CreateFlowCytometryPanelTemplateOptions
+): FlowCytometryPanelTemplate {
+  const markers = options.markers.map((marker, index): FlowPanelMarker => {
+    if (typeof marker !== 'string') return normalizeFlowMarker(marker, index)
+    return {
+      id: idFromName(marker, `marker-${index + 1}`),
+      marker,
+      fluorophore: 'unassigned',
+      purpose: 'phenotype',
+      compensationRequired: true,
+      metadata: {},
+    }
+  })
+  const controls = options.controls === undefined
+    ? options.includeDefaultControls === false
+      ? []
+      : defaultFlowControls(markers)
+    : options.controls.map((control, index): FlowPanelControl => {
+        if (typeof control !== 'string') return normalizeFlowControl(control, index)
+        return {
+          id: idFromName(control, `control-${index + 1}`),
+          name: control,
+          kind: 'other',
+          required: true,
+          metadata: {},
+        }
+      })
+  const data: FlowCytometryPanelTemplateData = {
+    markers,
+    controls,
+    instrument: options.instrument,
+    metadata: options.metadata ?? {},
+  }
+  validateFlowCytometryPanelData(data)
+  return createTemplateEnvelope('flow-cytometry-panel', data, options.metadata ?? {})
+}

package/src/templates/flowNormalizers.ts

@@ -0,0 +1,58 @@
+import type {
+  FlowPanelControl,
+  FlowPanelMarker,
+} from './types'
+import { idFromName } from './builderIdUtils'
+
+export function normalizeFlowMarker(
+  marker: Partial<FlowPanelMarker> & { marker: string },
+  index: number
+): FlowPanelMarker {
+  return {
+    id: marker.id ?? idFromName(marker.marker, `marker-${index + 1}`),
+    marker: marker.marker,
+    fluorophore: marker.fluorophore ?? 'unassigned',
+    detector: marker.detector,
+    clone: marker.clone,
+    reagentId: marker.reagentId,
+    purpose: marker.purpose ?? 'phenotype',
+    compensationRequired: marker.compensationRequired ?? true,
+    metadata: marker.metadata ?? {},
+  }
+}
+
+export function normalizeFlowControl(
+  control: Partial<FlowPanelControl> & { name: string },
+  index: number
+): FlowPanelControl {
+  return {
+    id: control.id ?? idFromName(control.name, `control-${index + 1}`),
+    name: control.name,
+    kind: control.kind ?? 'other',
+    markerId: control.markerId,
+    required: control.required ?? true,
+    metadata: control.metadata ?? {},
+  }
+}
+
+export function defaultFlowControls(markers: FlowPanelMarker[]): FlowPanelControl[] {
+  return [
+    {
+      id: 'unstained',
+      name: 'Unstained',
+      kind: 'unstained',
+      required: true,
+      metadata: {},
+    },
+    ...markers
+      .filter(marker => marker.compensationRequired)
+      .map(marker => ({
+        id: `${marker.id}-single-stain`,
+        name: `${marker.marker} single stain`,
+        kind: 'single-stain' as const,
+        markerId: marker.id,
+        required: true,
+        metadata: {},
+      })),
+  ]
+}

package/src/templates/flowPanelAdapters.ts

@@ -0,0 +1,58 @@
+import { getTemplateData } from './templateEnvelopes'
+import { validateFlowCytometryPanelData } from './templateValidators'
+import type {
+  FlowCytometryPanelTemplate,
+  FlowCytometryPanelTemplateData,
+  FlowPanelColumnsAdapterResult,
+  FlowPanelDataFrameAdapterResult,
+  FlowPanelRowsAdapterResult,
+} from './types'
+
+export function toFlowPanelRows(
+  template: FlowCytometryPanelTemplate | FlowCytometryPanelTemplateData
+): FlowPanelRowsAdapterResult {
+  const data = getTemplateData(template, 'flow-cytometry-panel')
+  validateFlowCytometryPanelData(data)
+  return data.markers.map(marker => {
+    const markerControls = data.controls
+      .filter(control => control.markerId === marker.id)
+      .map(control => control.name)
+      .join(', ')
+    return {
+      id: marker.id,
+      marker: marker.marker,
+      fluorophore: marker.fluorophore,
+      detector: marker.detector,
+      clone: marker.clone,
+      reagentId: marker.reagentId,
+      purpose: marker.purpose,
+      compensationRequired: marker.compensationRequired,
+      controls: markerControls,
+      instrument: data.instrument,
+      ...(marker.metadata ?? {}),
+    }
+  })
+}
+
+export function toFlowPanelColumns(): FlowPanelColumnsAdapterResult {
+  return [
+    { key: 'marker', label: 'Marker', sortable: true },
+    { key: 'fluorophore', label: 'Fluorophore', sortable: true },
+    { key: 'detector', label: 'Detector', sortable: true },
+    { key: 'clone', label: 'Clone', sortable: true },
+    { key: 'purpose', label: 'Purpose', sortable: true },
+    { key: 'compensationRequired', label: 'Compensation', sortable: true },
+    { key: 'controls', label: 'Controls' },
+    { key: 'instrument', label: 'Instrument', sortable: true },
+  ]
+}
+
+export function toFlowPanelDataFrame(
+  template: FlowCytometryPanelTemplate | FlowCytometryPanelTemplateData
+): FlowPanelDataFrameAdapterResult {
+  return {
+    data: toFlowPanelRows(template),
+    columns: toFlowPanelColumns(),
+    rowKey: 'id',
+  }
+}

package/src/templates/instrumentRunAdapterHelpers.ts

@@ -0,0 +1,94 @@
+import type {
+  ProtocolStepStatus,
+  ProtocolStepType,
+  ScheduleEventStatus,
+} from '../types'
+import type {
+  InstrumentRunItem,
+  InstrumentRunItemKind,
+  InstrumentRunStatus,
+} from './types'
+
+export function instrumentRunStepType(kind: InstrumentRunItemKind): ProtocolStepType {
+  switch (kind) {
+    case 'wash':
+      return 'wash'
+    case 'blank':
+    case 'qc':
+    case 'standard':
+    case 'calibration':
+    case 'sample':
+      return 'measurement'
+    default:
+      return 'custom'
+  }
+}
+
+export function instrumentRunStepStatus(status: InstrumentRunStatus): ProtocolStepStatus {
+  switch (status) {
+    case 'running':
+      return 'in_progress'
+    case 'completed':
+      return 'completed'
+    case 'failed':
+      return 'failed'
+    case 'skipped':
+      return 'skipped'
+    case 'planned':
+    case 'queued':
+    default:
+      return 'pending'
+  }
+}
+
+export function instrumentRunScheduleStatus(status: InstrumentRunStatus): ScheduleEventStatus {
+  switch (status) {
+    case 'running':
+      return 'in-progress'
+    case 'completed':
+      return 'confirmed'
+    case 'failed':
+    case 'skipped':
+      return 'cancelled'
+    case 'planned':
+    case 'queued':
+    default:
+      return 'pending'
+  }
+}
+
+export function instrumentRunScheduleColor(kind: InstrumentRunItem['kind']): string {
+  switch (kind) {
+    case 'blank':
+      return '#64748b'
+    case 'qc':
+      return '#8b5cf6'
+    case 'standard':
+    case 'calibration':
+      return '#f59e0b'
+    case 'wash':
+      return '#06b6d4'
+    case 'sample':
+      return '#2563eb'
+    default:
+      return '#475569'
+  }
+}
+
+export function dateFromMetadata(
+  metadata: Record<string, unknown> | undefined,
+  keys: readonly string[]
+): Date | undefined {
+  if (!metadata) return undefined
+  for (const key of keys) {
+    const value = metadata[key]
+    if (!(typeof value === 'string' || value instanceof Date)) continue
+    const date = new Date(value)
+    if (!Number.isNaN(date.getTime())) return date
+  }
+  return undefined
+}
+
+export function addMinutes(date: Date, minutes: number): Date {
+  return new Date(date.getTime() + minutes * 60_000)
+}