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

package/src/templates/presets.ts

@@ -74,6 +74,29 @@ export const bioTemplatePresets = [
     frontend_adapters: ['toTemplateDataFrame', 'toInstrumentRunDataFrame', 'toInstrumentRunSteps', 'toInstrumentRunScheduleEvents', 'toAssayMatrixDataFrame', 'toAssayMatrixSampleOptions'],
     components: ['DataFrame', 'ExperimentTimeline', 'ScheduleCalendar', 'ChartContainer', 'SampleSelector'],
   },
+  {
+    name: 'targeted-metabolomics',
+    label: 'Targeted metabolomics',
+    category: 'bio-template-preset',
+    purpose: 'Sample metadata, extraction prep, internal standards, LC/GC-MS sequence, calibration curve, and metabolite readout matrix for quantitative metabolomics.',
+    templates: ['sample-sheet', 'sample-prep', 'reagent-list', 'instrument-run', 'calibration-curve', 'assay-matrix'],
+    aliases: [
+      'targeted metabolomics',
+      'quantitative metabolomics',
+      'lc-ms metabolomics',
+      'gc-ms metabolomics',
+      'targeted lcms',
+      'metabolite quantitation',
+      'mass spec quantitation',
+      'internal standards',
+      'peak area ratio',
+    ],
+    python_import: 'from mint_sdk.templates import create_targeted_metabolomics_collection, save_template_collection',
+    python_example: 'create_targeted_metabolomics_collection(samples=["S001", "S002"], metabolites=["Glucose", "Lactate"], internal_standards=["13C Glucose"], instrument="LC-MS")',
+    frontend_import: "import { createTargetedMetabolomicsCollection, toInstrumentRunDataFrame, toCalibrationCurveDataFrame, toAssayMatrixDataFrame, toTemplateDataFrame } from '@morscherlab/mint-sdk/templates'",
+    frontend_adapters: ['toTemplateDataFrame', 'toSamplePrepDataFrame', 'toReagentDataFrame', 'toInstrumentRunDataFrame', 'toInstrumentRunSteps', 'toInstrumentRunScheduleEvents', 'toCalibrationCurveDataFrame', 'toAssayMatrixDataFrame', 'toAssayMatrixSampleOptions'],
+    components: ['DataFrame', 'ReagentList', 'ExperimentTimeline', 'ScheduleCalendar', 'FitPanel', 'ChartContainer', 'SampleSelector'],
+  },
   {
     name: 'elisa-assay',
     label: 'ELISA assay',

package/src/templates/protocolAdapters.ts

@@ -0,0 +1,69 @@
+import { getTemplateData } from './templateEnvelopes'
+import { validateProtocolStepsData } from './templateValidators'
+import type {
+  ProtocolColumnsAdapterResult,
+  ProtocolDataFrameAdapterResult,
+  ProtocolRowsAdapterResult,
+  ProtocolStepsAdapterResult,
+  ProtocolStepsTemplate,
+  ProtocolStepsTemplateData,
+} from './types'
+
+export function toProtocolSteps(
+  template: ProtocolStepsTemplate | ProtocolStepsTemplateData
+): ProtocolStepsAdapterResult {
+  const data = getTemplateData(template, 'protocol-steps')
+  validateProtocolStepsData(data)
+  return [...data.steps]
+    .sort((a, b) => a.order - b.order)
+    .map(step => ({
+      id: step.id,
+      type: step.type,
+      name: step.name,
+      description: step.description,
+      duration: step.duration,
+      status: step.status,
+      parameters: step.parameters,
+      order: step.order,
+    }))
+}
+
+export function toProtocolRows(
+  template: ProtocolStepsTemplate | ProtocolStepsTemplateData
+): ProtocolRowsAdapterResult {
+  const data = getTemplateData(template, 'protocol-steps')
+  validateProtocolStepsData(data)
+  return [...data.steps]
+    .sort((a, b) => a.order - b.order)
+    .map(step => ({
+      id: step.id,
+      order: step.order,
+      type: step.type,
+      name: step.name,
+      description: step.description,
+      duration: step.duration,
+      status: step.status,
+      ...(step.metadata ?? {}),
+    }))
+}
+
+export function toProtocolColumns(): ProtocolColumnsAdapterResult {
+  return [
+    { key: 'order', label: 'Order', sortable: true, align: 'right' },
+    { key: 'name', label: 'Name', sortable: true },
+    { key: 'type', label: 'Type', sortable: true },
+    { key: 'duration', label: 'Duration', sortable: true, align: 'right' },
+    { key: 'status', label: 'Status', sortable: true },
+    { key: 'description', label: 'Description', sortable: true },
+  ]
+}
+
+export function toProtocolDataFrame(
+  template: ProtocolStepsTemplate | ProtocolStepsTemplateData
+): ProtocolDataFrameAdapterResult {
+  return {
+    data: toProtocolRows(template),
+    columns: toProtocolColumns(),
+    rowKey: 'id',
+  }
+}

package/src/templates/protocolNormalizers.ts

@@ -0,0 +1,37 @@
+import type {
+  ProtocolStepRecord,
+  TimeCourseCondition,
+  TimePoint,
+} from './types'
+import { idFromName } from './builderIdUtils'
+
+export function normalizeTimePoint(timepoint: TimePoint): TimePoint {
+  return {
+    ...timepoint,
+    metadata: timepoint.metadata ?? {},
+  }
+}
+
+export function normalizeCondition(condition: TimeCourseCondition): TimeCourseCondition {
+  return {
+    ...condition,
+    metadata: condition.metadata ?? {},
+  }
+}
+
+export function normalizeProtocolStep(
+  step: Partial<ProtocolStepRecord> & { name: string },
+  index: number
+): ProtocolStepRecord {
+  return {
+    id: step.id ?? idFromName(step.name, `step-${index + 1}`),
+    type: step.type ?? 'custom',
+    name: step.name,
+    description: step.description,
+    duration: step.duration,
+    status: step.status ?? 'pending',
+    parameters: step.parameters ?? {},
+    order: step.order ?? index,
+    metadata: step.metadata ?? {},
+  }
+}

package/src/templates/protocolStepsBuilder.ts

@@ -0,0 +1,36 @@
+import { idFromName } from './builderIdUtils'
+import { normalizeProtocolStep } from './protocolNormalizers'
+import { createTemplateEnvelope } from './templateEnvelopes'
+import { validateProtocolStepsData } from './templateValidators'
+import type {
+  CreateProtocolStepsTemplateOptions,
+  ProtocolStepRecord,
+  ProtocolStepsTemplate,
+  ProtocolStepsTemplateData,
+} from './types'
+
+export function createProtocolStepsTemplate(
+  options: CreateProtocolStepsTemplateOptions
+): ProtocolStepsTemplate {
+  const steps = options.steps.map((step, index): ProtocolStepRecord => {
+    if (typeof step === 'string') {
+      return {
+        id: idFromName(step, `step-${index + 1}`),
+        type: 'custom',
+        name: step,
+        status: 'pending',
+        parameters: {},
+        order: index,
+        metadata: {},
+      }
+    }
+    return normalizeProtocolStep(step, index)
+  }).sort((a, b) => a.order - b.order)
+
+  const data: ProtocolStepsTemplateData = {
+    steps,
+    metadata: options.metadata ?? {},
+  }
+  validateProtocolStepsData(data)
+  return createTemplateEnvelope('protocol-steps', data, options.metadata ?? {})
+}

package/src/templates/qpcrAdapters.ts

@@ -0,0 +1,104 @@
+import type { Well } from '../types'
+import { getTemplateData } from './templateEnvelopes'
+import { validateQpcrPlateData } from './templateValidators'
+import type {
+  QpcrColumnsAdapterResult,
+  QpcrDataFrameAdapterResult,
+  QpcrPlateTemplate,
+  QpcrPlateTemplateData,
+  QpcrRowsAdapterResult,
+  QpcrWellMapAdapterResult,
+} from './types'
+
+export function toQpcrRows(
+  template: QpcrPlateTemplate | QpcrPlateTemplateData
+): QpcrRowsAdapterResult {
+  const data = getTemplateData(template, 'qpcr-plate')
+  validateQpcrPlateData(data)
+  const samples = new Map(data.samples.map(sample => [sample.sampleId, sample]))
+  const targets = new Map(data.targets.map(target => [target.id, target]))
+
+  return data.reactions.map(reaction => {
+    const sample = reaction.sampleId ? samples.get(reaction.sampleId) : undefined
+    const target = targets.get(reaction.targetId)
+    return {
+      id: reaction.id,
+      wellId: reaction.wellId,
+      sampleId: reaction.sampleId,
+      sample: sample?.name ?? reaction.sampleId ?? reaction.controlKind,
+      group: sample?.group,
+      targetId: reaction.targetId,
+      target: target?.name ?? reaction.targetId,
+      replicate: reaction.replicate,
+      controlKind: reaction.controlKind,
+      cq: reaction.cq ?? null,
+      quantity: reaction.quantity ?? null,
+      flags: reaction.flags.join(', '),
+      instrument: data.instrument,
+      chemistry: data.chemistry,
+      ...(reaction.metadata ?? {}),
+    }
+  })
+}
+
+export function toQpcrColumns(): QpcrColumnsAdapterResult {
+  return [
+    { key: 'wellId', label: 'Well', sortable: true },
+    { key: 'sample', label: 'Sample', sortable: true },
+    { key: 'group', label: 'Group', sortable: true },
+    { key: 'target', label: 'Target', sortable: true },
+    { key: 'replicate', label: 'Replicate', sortable: true, align: 'right' },
+    { key: 'controlKind', label: 'Control', sortable: true },
+    { key: 'cq', label: 'Cq', sortable: true, align: 'right' },
+    { key: 'quantity', label: 'Quantity', sortable: true, align: 'right' },
+    { key: 'flags', label: 'Flags' },
+  ]
+}
+
+export function toQpcrDataFrame(
+  template: QpcrPlateTemplate | QpcrPlateTemplateData
+): QpcrDataFrameAdapterResult {
+  return {
+    data: toQpcrRows(template),
+    columns: toQpcrColumns(),
+    rowKey: 'id',
+  }
+}
+
+export function toQpcrWellPlateWells(
+  template: QpcrPlateTemplate | QpcrPlateTemplateData
+): QpcrWellMapAdapterResult {
+  const data = getTemplateData(template, 'qpcr-plate')
+  validateQpcrPlateData(data)
+  return Object.fromEntries(data.reactions.map(reaction => {
+    const [row, col] = wellPositionFromId(reaction.wellId)
+    return [
+      reaction.wellId,
+      {
+        id: reaction.wellId,
+        row,
+        col,
+        state: 'filled' as const,
+        sampleType: reaction.sampleId ?? reaction.controlKind,
+        value: reaction.cq ?? undefined,
+        metadata: {
+          reactionId: reaction.id,
+          sampleId: reaction.sampleId,
+          targetId: reaction.targetId,
+          replicate: reaction.replicate,
+          controlKind: reaction.controlKind,
+        },
+      } satisfies Well,
+    ]
+  }))
+}
+
+function wellPositionFromId(wellId: string): [number, number] {
+  const match = /^([A-Z]+)([1-9][0-9]*)$/.exec(wellId.toUpperCase())
+  if (!match) {
+    throw new Error(`Invalid well id '${wellId}'.`)
+  }
+  const row = [...match[1]].reduce((value, char) => value * 26 + char.charCodeAt(0) - 64, 0) - 1
+  const col = Number(match[2]) - 1
+  return [row, col]
+}

package/src/templates/qpcrExpressionCollectionBuilder.ts

@@ -0,0 +1,33 @@
+import { createQpcrPlateTemplate } from './qpcrPlateBuilder'
+import { createSampleSheetTemplate } from './sampleSheetBuilder'
+import { presetSampleRecords } from './sampleNormalizers'
+import { createTemplateCollection } from './templateEnvelopes'
+import type {
+  CreateQpcrExpressionCollectionOptions,
+  TemplateCollectionEnvelope,
+} from './types'
+
+export function createQpcrExpressionCollection(
+  options: CreateQpcrExpressionCollectionOptions = {}
+): TemplateCollectionEnvelope {
+  const sampleRecords = presetSampleRecords(options.samples ?? ['Control', 'Treatment'])
+  const sampleSheet = createSampleSheetTemplate({ samples: sampleRecords })
+  const qpcr = createQpcrPlateTemplate({
+    samples: sampleRecords.map(sample => ({
+      sampleId: sample.sampleId,
+      name: sample.name,
+      group: sample.group,
+      metadata: sample.metadata ?? {},
+    })),
+    targets: options.targets ?? ['ACTB', 'GAPDH'],
+    chemistry: options.chemistry,
+    format: options.format,
+    includeNoTemplateControls: options.includeNoTemplateControls,
+    replicates: options.replicates ?? 3,
+    instrument: options.instrument,
+  })
+  return createTemplateCollection(
+    [sampleSheet, qpcr],
+    { preset: 'qpcr-expression', ...(options.metadata ?? {}) }
+  )
+}

package/src/templates/qpcrPlateBuilder.ts

@@ -0,0 +1,96 @@
+import { idFromName } from './builderIdUtils'
+import { wellIdsForFormat } from './plateGeometry'
+import {
+  normalizeQpcrSample,
+  normalizeQpcrTarget,
+} from './runNormalizers'
+import { createTemplateEnvelope } from './templateEnvelopes'
+import { validateQpcrPlateData } from './templateValidators'
+import type {
+  CreateQpcrPlateTemplateOptions,
+  QpcrPlateTemplate,
+  QpcrPlateTemplateData,
+  QpcrReaction,
+  QpcrSample,
+  QpcrTarget,
+} from './types'
+
+export function createQpcrPlateTemplate(
+  options: CreateQpcrPlateTemplateOptions
+): QpcrPlateTemplate {
+  const format = options.format ?? 96
+  const replicates = options.replicates ?? 3
+  if (replicates < 1) {
+    throw new Error('qPCR replicates must be at least 1.')
+  }
+
+  const samples = options.samples.map((sample, index): QpcrSample => {
+    if (typeof sample !== 'string') return normalizeQpcrSample(sample)
+    return {
+      sampleId: idFromName(sample, `sample-${index + 1}`),
+      name: sample,
+      metadata: {},
+    }
+  })
+  const targets = options.targets.map((target, index): QpcrTarget => {
+    if (typeof target !== 'string') return normalizeQpcrTarget(target)
+    return {
+      id: idFromName(target, `target-${index + 1}`),
+      name: target,
+      metadata: {},
+    }
+  })
+  const wells = wellIdsForFormat(format)
+  let wellIndex = 0
+  const reactions: QpcrReaction[] = []
+
+  for (const sample of samples) {
+    for (const target of targets) {
+      for (let replicate = 1; replicate <= replicates; replicate += 1) {
+        const wellId = wells[wellIndex]
+        if (!wellId) throw new Error(`qPCR plate format ${format} does not have enough wells.`)
+        reactions.push({
+          id: `${sample.sampleId}-${target.id}-r${replicate}`,
+          wellId,
+          sampleId: sample.sampleId,
+          targetId: target.id,
+          replicate,
+          controlKind: 'sample',
+          flags: [],
+          metadata: {},
+        })
+        wellIndex += 1
+      }
+    }
+  }
+
+  if (options.includeNoTemplateControls !== false) {
+    for (const target of targets) {
+      const wellId = wells[wellIndex]
+      if (!wellId) throw new Error(`qPCR plate format ${format} does not have enough wells.`)
+      reactions.push({
+        id: `ntc-${target.id}`,
+        wellId,
+        targetId: target.id,
+        replicate: 1,
+        controlKind: 'no-template',
+        flags: [],
+        metadata: {},
+      })
+      wellIndex += 1
+    }
+  }
+
+  const data: QpcrPlateTemplateData = {
+    plateId: 'qpcr-plate-1',
+    format,
+    samples,
+    targets,
+    reactions,
+    instrument: options.instrument,
+    chemistry: options.chemistry ?? 'sybr',
+    metadata: options.metadata ?? {},
+  }
+  validateQpcrPlateData(data)
+  return createTemplateEnvelope('qpcr-plate', data, options.metadata ?? {})
+}

package/src/templates/reagentAdapters.ts

@@ -0,0 +1,77 @@
+import { getTemplateData } from './templateEnvelopes'
+import { validateReagentListData } from './templateValidators'
+import type {
+  ReagentColumnsAdapterResult,
+  ReagentDataFrameAdapterResult,
+  ReagentListItemsAdapterResult,
+  ReagentListTemplate,
+  ReagentListTemplateData,
+  ReagentRowsAdapterResult,
+} from './types'
+
+export function toReagentListItems(
+  template: ReagentListTemplate | ReagentListTemplateData
+): ReagentListItemsAdapterResult {
+  const data = getTemplateData(template, 'reagent-list')
+  validateReagentListData(data)
+  return data.reagents.map(reagent => ({
+    id: reagent.id,
+    name: reagent.name,
+    catalogNumber: reagent.catalogNumber,
+    lotNumber: reagent.lotNumber,
+    expiryDate: reagent.expiryDate,
+    storageCondition: reagent.storageCondition,
+    location: reagent.location,
+    stockLevel: reagent.stockLevel,
+    stockUnit: reagent.stockUnit,
+    supplier: reagent.supplier,
+    url: reagent.url,
+  }))
+}
+
+export function toReagentRows(
+  template: ReagentListTemplate | ReagentListTemplateData
+): ReagentRowsAdapterResult {
+  const data = getTemplateData(template, 'reagent-list')
+  validateReagentListData(data)
+  return data.reagents.map(reagent => ({
+    id: reagent.id,
+    name: reagent.name,
+    kind: reagent.kind,
+    catalogNumber: reagent.catalogNumber,
+    lotNumber: reagent.lotNumber,
+    expiryDate: reagent.expiryDate,
+    storageCondition: reagent.storageCondition,
+    location: reagent.location,
+    stockLevel: reagent.stockLevel,
+    stockUnit: reagent.stockUnit,
+    supplier: reagent.supplier,
+    concentration: reagent.concentration,
+    ...(reagent.metadata ?? {}),
+  }))
+}
+
+export function toReagentColumns(): ReagentColumnsAdapterResult {
+  return [
+    { key: 'name', label: 'Name', sortable: true },
+    { key: 'kind', label: 'Kind', sortable: true },
+    { key: 'catalogNumber', label: 'Catalog', sortable: true },
+    { key: 'lotNumber', label: 'Lot', sortable: true },
+    { key: 'expiryDate', label: 'Expiry', sortable: true },
+    { key: 'storageCondition', label: 'Storage', sortable: true },
+    { key: 'location', label: 'Location', sortable: true },
+    { key: 'stockLevel', label: 'Stock', sortable: true, align: 'right' },
+    { key: 'stockUnit', label: 'Unit', sortable: true },
+    { key: 'supplier', label: 'Supplier', sortable: true },
+  ]
+}
+
+export function toReagentDataFrame(
+  template: ReagentListTemplate | ReagentListTemplateData
+): ReagentDataFrameAdapterResult {
+  return {
+    data: toReagentRows(template),
+    columns: toReagentColumns(),
+    rowKey: 'id',
+  }
+}

package/src/templates/reagentListBuilder.ts

@@ -0,0 +1,30 @@
+import { normalizeReagent } from './assayNormalizers'
+import { idFromName } from './builderIdUtils'
+import { createTemplateEnvelope } from './templateEnvelopes'
+import { validateReagentListData } from './templateValidators'
+import type {
+  CreateReagentListTemplateOptions,
+  ReagentListTemplate,
+  ReagentListTemplateData,
+  ReagentRecord,
+} from './types'
+
+export function createReagentListTemplate(
+  options: CreateReagentListTemplateOptions
+): ReagentListTemplate {
+  const reagents = options.reagents.map((reagent, index): ReagentRecord => {
+    if (typeof reagent !== 'string') return normalizeReagent(reagent)
+    return {
+      id: idFromName(reagent, `reagent-${index + 1}`),
+      name: reagent,
+      kind: 'reagent',
+      metadata: {},
+    }
+  })
+  const data: ReagentListTemplateData = {
+    reagents,
+    metadata: options.metadata ?? {},
+  }
+  validateReagentListData(data)
+  return createTemplateEnvelope('reagent-list', data, options.metadata ?? {})
+}

package/src/templates/runNormalizers.ts

@@ -0,0 +1,63 @@
+import type {
+  InstrumentMethod,
+  InstrumentRunItem,
+  QpcrSample,
+  QpcrTarget,
+} from './types'
+import { idFromName } from './builderIdUtils'
+
+export function normalizeInstrumentMethod(
+  method: Partial<InstrumentMethod> & { name?: string },
+  fallbackInstrument?: string
+): InstrumentMethod {
+  const name = method.name || method.id || 'Default method'
+  return {
+    id: method.id || idFromName(name, 'method-1'),
+    name,
+    instrument: method.instrument ?? fallbackInstrument,
+    acquisitionMode: method.acquisitionMode,
+    metadata: method.metadata ?? {},
+  }
+}
+
+export function normalizeInstrumentRunItem(
+  item: Partial<InstrumentRunItem> & { name?: string; sampleId?: string },
+  defaultMethodId: string,
+  fallbackOrder: number,
+  index: number
+): InstrumentRunItem {
+  const kind = item.kind ?? 'sample'
+  const sampleId = item.sampleId || (kind === 'sample'
+    ? idFromName(item.name ?? `Sample ${index + 1}`, `sample-${index + 1}`)
+    : undefined)
+  const label = item.name ?? sampleId ?? kind
+  return {
+    id: item.id || idFromName(label, `${kind}-${index + 1}`),
+    order: item.order ?? fallbackOrder,
+    kind,
+    sampleId,
+    name: item.name,
+    methodId: item.methodId || defaultMethodId,
+    vial: item.vial,
+    plateId: item.plateId,
+    wellId: item.wellId,
+    injectionVolume: item.injectionVolume,
+    expectedDurationMin: item.expectedDurationMin,
+    status: item.status ?? 'planned',
+    metadata: item.metadata ?? {},
+  }
+}
+
+export function normalizeQpcrSample(sample: QpcrSample): QpcrSample {
+  return {
+    ...sample,
+    metadata: sample.metadata ?? {},
+  }
+}
+
+export function normalizeQpcrTarget(target: QpcrTarget): QpcrTarget {
+  return {
+    ...target,
+    metadata: target.metadata ?? {},
+  }
+}

package/src/templates/sampleNormalizers.ts

@@ -0,0 +1,58 @@
+import type {
+  SamplePrepStep,
+  SamplePrepStepInput,
+  SampleRecord,
+} from './types'
+import {
+  idFromName,
+  sampleIdFromName,
+} from './builderIdUtils'
+
+export function normalizeSampleRecord(sample: SampleRecord): SampleRecord {
+  return {
+    ...sample,
+    metadata: sample.metadata ?? {},
+  }
+}
+
+export function presetSampleRecords(samples: Array<string | SampleRecord>): SampleRecord[] {
+  return samples.map((sample, index) => {
+    if (typeof sample !== 'string') return normalizeSampleRecord(sample)
+    return {
+      sampleId: sampleIdFromName(sample, index),
+      name: sample,
+      metadata: {},
+    }
+  })
+}
+
+export function normalizeSamplePrepStep(
+  step: SamplePrepStepInput,
+  prepType: SamplePrepStep['type'],
+  volumeUnit: string,
+  order: number,
+  index: number
+): SamplePrepStep {
+  const type = step.type ?? prepType
+  const sourceSampleId = step.sourceSampleId
+  const name = step.name || `Prepare ${sourceSampleId ?? index + 1}`
+  return {
+    id: step.id || idFromName(name, `${type}-${index + 1}`),
+    order: step.order ?? order,
+    type,
+    name,
+    sourceSampleId,
+    sourcePlateId: step.sourcePlateId,
+    sourceWellId: step.sourceWellId,
+    destinationSampleId: step.destinationSampleId,
+    destinationPlateId: step.destinationPlateId,
+    destinationWellId: step.destinationWellId,
+    reagentId: step.reagentId,
+    inputVolume: step.inputVolume,
+    outputVolume: step.outputVolume,
+    volumeUnit: step.volumeUnit || volumeUnit,
+    durationMin: step.durationMin,
+    status: step.status ?? 'planned',
+    metadata: step.metadata ?? {},
+  }
+}