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

package/src/templates/assayLookups.ts

@@ -0,0 +1,33 @@
+import type {
+  AssayFeature,
+  AssaySample,
+} from './types'
+import { idFromName } from './builderIdUtils'
+
+export function createAssaySampleLookup(samples: AssaySample[]): Map<string, string> {
+  const lookup = new Map<string, string>()
+  for (const sample of samples) {
+    addLookupAlias(lookup, sample.sampleId, sample.sampleId)
+    if (sample.name) {
+      addLookupAlias(lookup, sample.name, sample.sampleId)
+      addLookupAlias(lookup, idFromName(sample.name, sample.sampleId), sample.sampleId)
+    }
+  }
+  return lookup
+}
+
+export function createAssayFeatureLookup(features: AssayFeature[]): Map<string, string> {
+  const lookup = new Map<string, string>()
+  for (const feature of features) {
+    addLookupAlias(lookup, feature.id, feature.id)
+    addLookupAlias(lookup, feature.name, feature.id)
+    addLookupAlias(lookup, idFromName(feature.name, feature.id), feature.id)
+  }
+  return lookup
+}
+
+function addLookupAlias(lookup: Map<string, string>, alias: string, value: string): void {
+  if (!lookup.has(alias)) {
+    lookup.set(alias, value)
+  }
+}

package/src/templates/assayMatrixAdapters.ts

@@ -0,0 +1,78 @@
+import type { SelectOption } from '../types'
+import { getTemplateData } from './templateEnvelopes'
+import { validateAssayMatrixData } from './templateValidators'
+import type {
+  AssayMatrixColumnsAdapterResult,
+  AssayMatrixDataFrameAdapterResult,
+  AssayMatrixRowsAdapterResult,
+  AssayMatrixSampleOptionsAdapterResult,
+  AssayMatrixTemplate,
+  AssayMatrixTemplateData,
+} from './types'
+
+export function toAssayMatrixRows(
+  template: AssayMatrixTemplate | AssayMatrixTemplateData
+): AssayMatrixRowsAdapterResult {
+  const data = getTemplateData(template, 'assay-matrix')
+  validateAssayMatrixData(data)
+  const measurements = new Map(
+    data.measurements.map(measurement => [
+      `${measurement.sampleId}:${measurement.featureId}`,
+      measurement.value ?? null,
+    ])
+  )
+
+  return data.samples.map(sample => {
+    const row: Record<string, unknown> = {
+      sampleId: sample.sampleId,
+      name: sample.name,
+      group: sample.group,
+      ...(sample.metadata ?? {}),
+    }
+    for (const feature of data.features) {
+      row[feature.id] = measurements.get(`${sample.sampleId}:${feature.id}`) ?? null
+    }
+    return row
+  })
+}
+
+export function toAssayMatrixColumns(
+  template: AssayMatrixTemplate | AssayMatrixTemplateData
+): AssayMatrixColumnsAdapterResult {
+  const data = getTemplateData(template, 'assay-matrix')
+  validateAssayMatrixData(data)
+  return [
+    { key: 'sampleId', label: 'Sample ID', sortable: true },
+    { key: 'name', label: 'Name', sortable: true },
+    { key: 'group', label: 'Group', sortable: true },
+    ...data.features.map(feature => ({
+      key: feature.id,
+      label: feature.unit ? `${feature.name} (${feature.unit})` : feature.name,
+      sortable: true,
+      align: 'right' as const,
+    })),
+  ]
+}
+
+export function toAssayMatrixDataFrame(
+  template: AssayMatrixTemplate | AssayMatrixTemplateData
+): AssayMatrixDataFrameAdapterResult {
+  return {
+    data: toAssayMatrixRows(template),
+    columns: toAssayMatrixColumns(template),
+    rowKey: 'sampleId',
+  }
+}
+
+/** Convert an assay-matrix template into SampleSelector options derived from assay samples. */
+export function toAssayMatrixSampleOptions(
+  template: AssayMatrixTemplate | AssayMatrixTemplateData
+): AssayMatrixSampleOptionsAdapterResult {
+  const data = getTemplateData(template, 'assay-matrix')
+  validateAssayMatrixData(data)
+  return data.samples.map((sample): SelectOption<string> => ({
+    value: sample.sampleId,
+    label: sample.name ?? sample.sampleId,
+    description: sample.group,
+  }))
+}

package/src/templates/assayMatrixBuilder.ts

@@ -0,0 +1,59 @@
+import {
+  createAssayFeatureLookup,
+  createAssaySampleLookup,
+} from './assayLookups'
+import {
+  normalizeAssayFeature,
+  normalizeAssaySample,
+} from './assayNormalizers'
+import { idFromName } from './builderIdUtils'
+import { createTemplateEnvelope } from './templateEnvelopes'
+import { validateAssayMatrixData } from './templateValidators'
+import type {
+  AssayFeature,
+  AssayMatrixTemplate,
+  AssayMatrixTemplateData,
+  AssaySample,
+  CreateAssayMatrixTemplateOptions,
+} from './types'
+
+export function createAssayMatrixTemplate(
+  options: CreateAssayMatrixTemplateOptions
+): AssayMatrixTemplate {
+  const samples = options.samples.map((sample, index): AssaySample => {
+    if (typeof sample !== 'string') return normalizeAssaySample(sample)
+    return {
+      sampleId: idFromName(sample, `sample-${index + 1}`),
+      name: sample,
+      metadata: {},
+    }
+  })
+  const features = options.features.map((feature, index): AssayFeature => {
+    if (typeof feature !== 'string') return normalizeAssayFeature(feature)
+    return {
+      id: idFromName(feature, `feature-${index + 1}`),
+      name: feature,
+      type: 'readout',
+      metadata: {},
+    }
+  })
+  const sampleLookup = createAssaySampleLookup(samples)
+  const featureLookup = createAssayFeatureLookup(features)
+  const measurements = Object.entries(options.values ?? {}).flatMap(([sampleId, featureValues]) =>
+    Object.entries(featureValues).map(([featureId, value]) => ({
+      sampleId: sampleLookup.get(sampleId) ?? sampleId,
+      featureId: featureLookup.get(featureId) ?? featureId,
+      value,
+      metadata: {},
+    }))
+  )
+
+  const data: AssayMatrixTemplateData = {
+    samples,
+    features,
+    measurements,
+    metadata: options.metadata ?? {},
+  }
+  validateAssayMatrixData(data)
+  return createTemplateEnvelope('assay-matrix', data, options.metadata ?? {})
+}

package/src/templates/assayNormalizers.ts

@@ -0,0 +1,34 @@
+import type {
+  AssayFeature,
+  AssaySample,
+  ReagentRecord,
+  ReagentTemplateInput,
+} from './types'
+
+export function normalizeAssaySample(sample: AssaySample): AssaySample {
+  return {
+    ...sample,
+    metadata: sample.metadata ?? {},
+  }
+}
+
+export function normalizeAssayFeature(feature: AssayFeature): AssayFeature {
+  return {
+    ...feature,
+    metadata: feature.metadata ?? {},
+  }
+}
+
+export function normalizeReagent(reagent: ReagentTemplateInput): ReagentRecord {
+  return {
+    ...reagent,
+    expiryDate: normalizeDateString(reagent.expiryDate),
+    kind: reagent.kind ?? 'reagent',
+    metadata: reagent.metadata ?? {},
+  }
+}
+
+function normalizeDateString(value: Date | string | null | undefined): string | undefined {
+  if (value === undefined || value === null) return undefined
+  return value instanceof Date ? value.toISOString() : value
+}

package/src/templates/builderDefaults.ts

@@ -0,0 +1,11 @@
+export const DEFAULT_SAMPLE_COLORS = [
+  '#3B82F6',
+  '#10B981',
+  '#EF4444',
+  '#F59E0B',
+  '#8B5CF6',
+  '#F97316',
+  '#06B6D4',
+  '#14B8A6',
+  '#6B7280',
+]

package/src/templates/builderIdUtils.ts

@@ -0,0 +1,20 @@
+export function sampleIdFromName(name: string, index: number): string {
+  return idFromName(name, `sample-${index + 1}`)
+}
+
+export function compoundIdFromName(name: string, index: number): string {
+  return idFromName(name, `compound-${index + 1}`)
+}
+
+export function idFromName(name: string, fallback: string): string {
+  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')
+  return slug || fallback
+}
+
+export function timepointId(value: number, unit: string, index: number): string {
+  const raw = Number.isInteger(value)
+    ? String(value)
+    : String(value).replace(/0+$/, '').replace(/\.$/, '')
+  const token = raw.replace('.', 'p')
+  return token ? `t${token}-${unit}` : `timepoint-${index + 1}`
+}

package/src/templates/builderPresetControls.ts

@@ -0,0 +1,165 @@
+import {
+  readBoolean,
+  readInteger,
+  readNumber,
+  readNumberList,
+  readOptionalString,
+  readString,
+  readStringList,
+} from './builderReadUtils'
+import { readPlateFormat } from './plateGeometry'
+import { getBioTemplatePresetInfo } from './presets'
+import type {
+  CreateElisaAssayCollectionOptions,
+  CreateFlowCytometryAssayCollectionOptions,
+  CreateLcmsBatchCollectionOptions,
+  CreateQpcrExpressionCollectionOptions,
+  CreateQpcrPlateTemplateOptions,
+  CreateSamplePrepTemplateOptions,
+  CreateTargetedMetabolomicsCollectionOptions,
+  CreateWellPlateScreenCollectionOptions,
+  CreateWesternBlotAssayCollectionOptions,
+  TemplatePresetId,
+} from './types'
+
+export type BioTemplateControlValues = Record<string, unknown>
+
+export function bioTemplatePresetControlValuesToOptions(
+  name: 'wellplate-screen',
+  values: BioTemplateControlValues
+): CreateWellPlateScreenCollectionOptions
+export function bioTemplatePresetControlValuesToOptions(
+  name: 'qpcr-expression',
+  values: BioTemplateControlValues
+): CreateQpcrExpressionCollectionOptions
+export function bioTemplatePresetControlValuesToOptions(
+  name: 'lcms-batch',
+  values: BioTemplateControlValues
+): CreateLcmsBatchCollectionOptions
+export function bioTemplatePresetControlValuesToOptions(
+  name: 'targeted-metabolomics',
+  values: BioTemplateControlValues
+): CreateTargetedMetabolomicsCollectionOptions
+export function bioTemplatePresetControlValuesToOptions(
+  name: 'elisa-assay',
+  values: BioTemplateControlValues
+): CreateElisaAssayCollectionOptions
+export function bioTemplatePresetControlValuesToOptions(
+  name: 'flow-cytometry-assay',
+  values: BioTemplateControlValues
+): CreateFlowCytometryAssayCollectionOptions
+export function bioTemplatePresetControlValuesToOptions(
+  name: 'western-blot-assay',
+  values: BioTemplateControlValues
+): CreateWesternBlotAssayCollectionOptions
+export function bioTemplatePresetControlValuesToOptions(
+  name: TemplatePresetId | string,
+  values: BioTemplateControlValues
+):
+  | CreateWellPlateScreenCollectionOptions
+  | CreateQpcrExpressionCollectionOptions
+  | CreateLcmsBatchCollectionOptions
+  | CreateTargetedMetabolomicsCollectionOptions
+  | CreateElisaAssayCollectionOptions
+  | CreateFlowCytometryAssayCollectionOptions
+  | CreateWesternBlotAssayCollectionOptions
+export function bioTemplatePresetControlValuesToOptions(
+  name: TemplatePresetId | string,
+  values: BioTemplateControlValues
+):
+  | CreateWellPlateScreenCollectionOptions
+  | CreateQpcrExpressionCollectionOptions
+  | CreateLcmsBatchCollectionOptions
+  | CreateTargetedMetabolomicsCollectionOptions
+  | CreateElisaAssayCollectionOptions
+  | CreateFlowCytometryAssayCollectionOptions
+  | CreateWesternBlotAssayCollectionOptions {
+  const preset = getBioTemplatePresetInfo(name)
+  if (!preset) {
+    throw new Error(`Unknown template preset '${name}'.`)
+  }
+
+  if (preset.name === 'wellplate-screen') {
+    return {
+      samples: readStringList(values.sampleNames, ['Control', 'Treatment']),
+      plateName: readString(values.plateName, 'Screen plate'),
+      plateFormat: readPlateFormat(values.plateFormat, 96),
+      unit: readString(values.unit, 'uM'),
+      replicates: readInteger(values.replicates, 3),
+    }
+  }
+
+  if (preset.name === 'qpcr-expression') {
+    return {
+      samples: readStringList(values.sampleNames, ['Control', 'Treatment']),
+      targets: readStringList(values.targets, ['ACTB', 'GAPDH']),
+      chemistry: readString(values.chemistry, 'sybr') as CreateQpcrPlateTemplateOptions['chemistry'],
+      format: readPlateFormat(values.plateFormat, 96),
+      includeNoTemplateControls: readBoolean(values.includeNoTemplateControls, true),
+      replicates: readInteger(values.replicates, 3),
+      instrument: readOptionalString(values.instrument),
+    }
+  }
+
+  if (preset.name === 'lcms-batch') {
+    return {
+      samples: readStringList(values.sampleNames, ['S001', 'S002']),
+      features: readStringList(values.featureNames, ['Glucose', 'Lactate']),
+      instrument: readString(values.instrument, 'LC-MS'),
+      method: readString(values.method, 'Default method'),
+      includeQc: readBoolean(values.includeQc, true),
+    }
+  }
+
+  if (preset.name === 'targeted-metabolomics') {
+    return {
+      samples: readStringList(values.sampleNames, ['S001', 'S002']),
+      metabolites: readStringList(values.metaboliteNames, ['Glucose', 'Lactate', 'Pyruvate']),
+      internalStandards: readStringList(
+        values.internalStandards,
+        ['Stable isotope internal standard mix'],
+      ),
+      standardConcentrations: readNumberList(values.standardConcentrations, [0.1, 1, 10, 100]),
+      concentrationUnit: readString(values.concentrationUnit, 'uM'),
+      responseUnit: readString(values.responseUnit, 'peak area ratio'),
+      calibrationAnalyte: readOptionalString(values.calibrationAnalyte),
+      instrument: readString(values.instrument, 'LC-MS'),
+      method: readString(values.method, 'Targeted metabolomics'),
+      prepType: readString(values.prepType, 'extraction') as CreateSamplePrepTemplateOptions['prepType'],
+      outputVolume: readNumber(values.outputVolume, 50),
+      includeQc: readBoolean(values.includeQc, true),
+    }
+  }
+
+  if (preset.name === 'elisa-assay') {
+    return {
+      samples: readStringList(values.sampleNames, ['Control', 'Treatment']),
+      analyte: readString(values.analyte, 'Analyte'),
+      standardConcentrations: readNumberList(values.standardConcentrations, [1000, 100, 10, 1]),
+      unit: readString(values.unit, 'pg/mL'),
+      responseUnit: readString(values.responseUnit, 'OD450'),
+      plateName: readString(values.plateName, 'ELISA plate'),
+      plateFormat: readPlateFormat(values.plateFormat, 96),
+    }
+  }
+
+  if (preset.name === 'flow-cytometry-assay') {
+    return {
+      samples: readStringList(values.sampleNames, ['Control', 'Treatment']),
+      markers: readStringList(values.markers, ['CD3', 'CD4', 'CD8']),
+      features: readStringList(values.featureNames, ['CD3+ cells', 'CD4+ cells', 'CD8+ cells']),
+      instrument: readString(values.instrument, 'Flow cytometer'),
+      includeDefaultControls: readBoolean(values.includeDefaultControls, true),
+    }
+  }
+
+  if (preset.name === 'western-blot-assay') {
+    return {
+      samples: readStringList(values.sampleNames, ['Control', 'Treatment']),
+      targets: readStringList(values.targets, ['Target protein']),
+      loadingControl: readString(values.loadingControl, 'ACTB'),
+    }
+  }
+
+  throw new Error(`Unknown template preset '${name}'.`)
+}

package/src/templates/builderReadUtils.ts

@@ -0,0 +1,57 @@
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+export function readStringList(value: unknown, fallback: string[]): string[] {
+  if (Array.isArray(value)) {
+    const items = value.map(item => String(item).trim()).filter(Boolean)
+    return items.length ? items : fallback
+  }
+  if (typeof value === 'string') {
+    const items = value.split(',').map(item => item.trim()).filter(Boolean)
+    return items.length ? items : fallback
+  }
+  return fallback
+}
+
+export function readNumberList(value: unknown, fallback: number[]): number[] {
+  const rawItems = Array.isArray(value)
+    ? value
+    : typeof value === 'string'
+      ? value.split(',')
+      : []
+  const items = rawItems
+    .map(item => Number(String(item).trim()))
+    .filter(item => Number.isFinite(item))
+  return items.length ? items : fallback
+}
+
+export function readString(value: unknown, fallback: string): string {
+  return typeof value === 'string' && value.trim() ? value.trim() : fallback
+}
+
+export function readOptionalString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined
+}
+
+export function readInteger(value: unknown, fallback: number): number {
+  const parsed = typeof value === 'number'
+    ? value
+    : typeof value === 'string'
+      ? Number(value)
+      : Number.NaN
+  return Number.isFinite(parsed) ? Math.max(1, Math.round(parsed)) : fallback
+}
+
+export function readNumber(value: unknown, fallback: number): number {
+  const parsed = typeof value === 'number'
+    ? value
+    : typeof value === 'string'
+      ? Number(value)
+      : Number.NaN
+  return Number.isFinite(parsed) ? parsed : fallback
+}
+
+export function readBoolean(value: unknown, fallback: boolean): boolean {
+  return typeof value === 'boolean' ? value : fallback
+}