@morscherlab/mint-sdk 1.2.0-beta.3 → 1.2.0-beta.4

package/src/templates/types.ts

@@ -0,0 +1,493 @@
+import type {
+  PlateMap,
+  ProtocolStep,
+  Reagent,
+  SampleType,
+  Well,
+} from '../types'
+import type { QpcrPlateTemplate } from './templateQpcrTypes'
+
+export type TemplateKind = 'experiment-design'
+export type TemplateId =
+  | 'plate-map'
+  | 'sample-sheet'
+  | 'sample-prep'
+  | 'dose-response'
+  | 'calibration-curve'
+  | 'time-course'
+  | 'protocol-steps'
+  | 'assay-matrix'
+  | 'reagent-list'
+  | 'flow-cytometry-panel'
+  | 'instrument-run'
+  | 'qpcr-plate'
+
+export type TemplatePresetId =
+  | 'wellplate-screen'
+  | 'qpcr-expression'
+  | 'lcms-batch'
+  | 'targeted-metabolomics'
+  | 'elisa-assay'
+  | 'flow-cytometry-assay'
+  | 'western-blot-assay'
+
+export type TemplatePackId =
+  | 'cell-culture-screen'
+  | 'omics-assay'
+  | 'longitudinal-study'
+  | 'molecular-assay'
+
+export interface BioTemplateEnvelope<TData = Record<string, unknown>> {
+  template_id: TemplateId | string
+  template_version: string
+  kind: TemplateKind | string
+  data: TData
+  metadata: Record<string, unknown>
+}
+
+export type TemplateCollection = Record<string, BioTemplateEnvelope<unknown>>
+
+export interface TemplateCollectionEnvelope {
+  templates: TemplateCollection
+  metadata?: Record<string, unknown>
+}
+
+export type TemplateWell = Well
+export type TemplatePlateMap = PlateMap
+export type TemplateSample = SampleType
+
+export interface PlateMapTemplateData {
+  plates: TemplatePlateMap[]
+  samples: TemplateSample[]
+  activePlateId?: string
+  selectedWells?: string[]
+  activeSampleId?: string
+}
+
+export type PlateMapTemplate = BioTemplateEnvelope<PlateMapTemplateData>
+
+export type SampleColumnType = 'string' | 'number' | 'integer' | 'boolean' | 'date' | 'category' | 'unknown'
+
+export interface SampleColumn {
+  id: string
+  label: string
+  type: SampleColumnType
+  required: boolean
+  groupable: boolean
+}
+
+export interface SampleRecord {
+  sampleId: string
+  name?: string
+  group?: string
+  batch?: string
+  replicate?: number | string
+  plateId?: string
+  wellId?: string
+  metadata?: Record<string, unknown>
+}
+
+export interface SampleGroupDefinition {
+  name: string
+  color: string
+  samples: string[]
+}
+
+export interface SampleSheetTemplateData {
+  samples: SampleRecord[]
+  columns: SampleColumn[]
+  groups: SampleGroupDefinition[]
+}
+
+export type SampleSheetTemplate = BioTemplateEnvelope<SampleSheetTemplateData>
+
+export type SamplePrepStepType =
+  | 'extraction'
+  | 'dilution'
+  | 'normalization'
+  | 'transfer'
+  | 'incubation'
+  | 'centrifugation'
+  | 'cleanup'
+  | 'digestion'
+  | 'labeling'
+  | 'other'
+export type SamplePrepStatus = 'planned' | 'in-progress' | 'completed' | 'failed' | 'skipped'
+
+export interface SamplePrepStep {
+  id: string
+  order: number
+  type: SamplePrepStepType
+  name: string
+  sourceSampleId?: string
+  sourcePlateId?: string
+  sourceWellId?: string
+  destinationSampleId?: string
+  destinationPlateId?: string
+  destinationWellId?: string
+  reagentId?: string
+  inputVolume?: number
+  outputVolume?: number
+  volumeUnit: string
+  durationMin?: number
+  status: SamplePrepStatus
+  metadata?: Record<string, unknown>
+}
+
+export interface SamplePrepTemplateData {
+  protocolName: string
+  steps: SamplePrepStep[]
+  metadata: Record<string, unknown>
+}
+
+export type SamplePrepTemplate = BioTemplateEnvelope<SamplePrepTemplateData>
+export type SamplePrepStepInput = Partial<SamplePrepStep> & { name?: string; sourceSampleId?: string }
+
+export interface CompoundDoseSeries {
+  id: string
+  name: string
+  concentrations: number[]
+  metadata?: Record<string, unknown>
+}
+
+export type ControlRole = 'vehicle' | 'positive' | 'negative' | 'blank' | 'baseline' | 'other'
+
+export interface ControlDefinition {
+  id: string
+  name: string
+  role: ControlRole
+  vehicle?: string
+  metadata?: Record<string, unknown>
+}
+
+export interface DoseResponseTemplateData {
+  compounds: CompoundDoseSeries[]
+  unit: string
+  replicates: number
+  controls: ControlDefinition[]
+  layout?: PlateMapTemplateData
+  metadata: Record<string, unknown>
+}
+
+export type DoseResponseTemplate = BioTemplateEnvelope<DoseResponseTemplateData>
+
+export type CalibrationModel =
+  | 'linear'
+  | 'linear-weighted-1-x'
+  | 'linear-weighted-1-x2'
+  | 'quadratic'
+  | 'four-parameter-logistic'
+export type CalibrationPointRole = 'blank' | 'standard' | 'qc' | 'unknown'
+export type CalibrationPointStatus = 'planned' | 'accepted' | 'rejected' | 'warning'
+
+export interface CalibrationAcceptance {
+  minRSquared: number
+  standardTolerancePercent: number
+  qcTolerancePercent: number
+  requireBlank: boolean
+  metadata?: Record<string, unknown>
+}
+
+export interface CalibrationPoint {
+  id: string
+  order: number
+  role: CalibrationPointRole
+  level: string
+  concentration: number
+  unit: string
+  expectedResponse?: number
+  response?: number
+  replicate: number
+  include: boolean
+  status: CalibrationPointStatus
+  metadata?: Record<string, unknown>
+}
+
+export interface CalibrationCurveTemplateData {
+  analyte: string
+  model: CalibrationModel
+  xUnit: string
+  responseUnit: string
+  points: CalibrationPoint[]
+  acceptance: CalibrationAcceptance
+  metadata: Record<string, unknown>
+}
+
+export type CalibrationCurveTemplate = BioTemplateEnvelope<CalibrationCurveTemplateData>
+export type CalibrationAcceptanceInput = Partial<CalibrationAcceptance>
+export type CalibrationPointInput = Partial<CalibrationPoint> & { concentration?: number; level?: string }
+
+export type TimeUnit = 'second' | 'minute' | 'hour' | 'day' | 'week'
+
+export interface TimePoint {
+  id: string
+  label: string
+  value: number
+  unit: TimeUnit
+  metadata?: Record<string, unknown>
+}
+
+export interface TimeCourseCondition {
+  id: string
+  name: string
+  color?: string
+  description?: string
+  metadata?: Record<string, unknown>
+}
+
+export interface TimeCourseSample {
+  sampleId: string
+  conditionId: string
+  timepointId: string
+  replicate: number
+  metadata?: Record<string, unknown>
+}
+
+export interface TimeCourseTemplateData {
+  timepoints: TimePoint[]
+  conditions: TimeCourseCondition[]
+  samples: TimeCourseSample[]
+  metadata: Record<string, unknown>
+}
+
+export type TimeCourseTemplate = BioTemplateEnvelope<TimeCourseTemplateData>
+
+export type AssayFeatureType = 'metabolite' | 'protein' | 'gene' | 'cell' | 'compound' | 'readout' | 'other'
+
+export interface AssaySample {
+  sampleId: string
+  name?: string
+  group?: string
+  metadata?: Record<string, unknown>
+}
+
+export interface AssayFeature {
+  id: string
+  name: string
+  type: AssayFeatureType
+  unit?: string
+  metadata?: Record<string, unknown>
+}
+
+export interface AssayMeasurement {
+  sampleId: string
+  featureId: string
+  value?: number | null
+  metadata?: Record<string, unknown>
+}
+
+export interface AssayMatrixTemplateData {
+  samples: AssaySample[]
+  features: AssayFeature[]
+  measurements: AssayMeasurement[]
+  metadata: Record<string, unknown>
+}
+
+export type AssayMatrixTemplate = BioTemplateEnvelope<AssayMatrixTemplateData>
+
+export type ProtocolStepRecord = ProtocolStep & {
+  metadata?: Record<string, unknown>
+}
+
+export interface ProtocolStepsTemplateData {
+  steps: ProtocolStepRecord[]
+  metadata: Record<string, unknown>
+}
+
+export type ProtocolStepsTemplate = BioTemplateEnvelope<ProtocolStepsTemplateData>
+
+export type ReagentKind =
+  | 'compound'
+  | 'antibody'
+  | 'primer'
+  | 'enzyme'
+  | 'buffer'
+  | 'media'
+  | 'kit'
+  | 'reagent'
+  | 'other'
+
+export type ReagentTemplateInput = Omit<Reagent, 'expiryDate'> & {
+  expiryDate?: Date | string | null
+  kind?: ReagentKind
+  concentration?: string
+  metadata?: Record<string, unknown>
+}
+
+export interface ReagentRecord extends Omit<Reagent, 'expiryDate'> {
+  expiryDate?: string
+  kind?: ReagentKind
+  concentration?: string
+  metadata?: Record<string, unknown>
+}
+
+export interface ReagentListTemplateData {
+  reagents: ReagentRecord[]
+  metadata: Record<string, unknown>
+}
+
+export type ReagentListTemplate = BioTemplateEnvelope<ReagentListTemplateData>
+
+export type FlowMarkerPurpose = 'phenotype' | 'viability' | 'activation' | 'sorting' | 'control' | 'other'
+export type FlowControlKind = 'unstained' | 'single-stain' | 'fmo' | 'isotype' | 'viability' | 'beads' | 'other'
+
+export interface FlowPanelMarker {
+  id: string
+  marker: string
+  fluorophore: string
+  detector?: string
+  clone?: string
+  reagentId?: string
+  purpose: FlowMarkerPurpose
+  compensationRequired: boolean
+  metadata?: Record<string, unknown>
+}
+
+export interface FlowPanelControl {
+  id: string
+  name: string
+  kind: FlowControlKind
+  markerId?: string
+  required: boolean
+  metadata?: Record<string, unknown>
+}
+
+export interface FlowCytometryPanelTemplateData {
+  markers: FlowPanelMarker[]
+  controls: FlowPanelControl[]
+  instrument?: string
+  metadata: Record<string, unknown>
+}
+
+export type FlowCytometryPanelTemplate = BioTemplateEnvelope<FlowCytometryPanelTemplateData>
+
+export type InstrumentRunItemKind = 'sample' | 'blank' | 'qc' | 'standard' | 'calibration' | 'wash' | 'other'
+export type InstrumentRunStatus = 'planned' | 'queued' | 'running' | 'completed' | 'failed' | 'skipped'
+
+export interface InstrumentMethod {
+  id: string
+  name: string
+  instrument?: string
+  acquisitionMode?: string
+  metadata?: Record<string, unknown>
+}
+
+export interface InstrumentRunItem {
+  id: string
+  order: number
+  kind: InstrumentRunItemKind
+  sampleId?: string
+  name?: string
+  methodId: string
+  vial?: string
+  plateId?: string
+  wellId?: string
+  injectionVolume?: number
+  expectedDurationMin?: number
+  status: InstrumentRunStatus
+  metadata?: Record<string, unknown>
+}
+
+export interface InstrumentRunTemplateData {
+  runId: string
+  instrument?: string
+  methods: InstrumentMethod[]
+  items: InstrumentRunItem[]
+  metadata: Record<string, unknown>
+}
+
+export type InstrumentRunTemplate = BioTemplateEnvelope<InstrumentRunTemplateData>
+
+export type InstrumentMethodInput = Partial<InstrumentMethod> & { name?: string }
+export type InstrumentRunItemInput = Partial<InstrumentRunItem> & { name?: string; sampleId?: string }
+
+export type DataFrameTemplate =
+  | SampleSheetTemplate
+  | SamplePrepTemplate
+  | CalibrationCurveTemplate
+  | TimeCourseTemplate
+  | ProtocolStepsTemplate
+  | AssayMatrixTemplate
+  | ReagentListTemplate
+  | FlowCytometryPanelTemplate
+  | InstrumentRunTemplate
+  | QpcrPlateTemplate
+
+export type {
+  QpcrChemistry,
+  QpcrControlKind,
+  QpcrPlateTemplate,
+  QpcrPlateTemplateData,
+  QpcrReaction,
+  QpcrSample,
+  QpcrTarget,
+} from './templateQpcrTypes'
+
+export type {
+  CreateAssayMatrixTemplateOptions,
+  CreateBioTemplatePackCollectionOptions,
+  CreateCalibrationCurveTemplateOptions,
+  CreateDoseResponseTemplateOptions,
+  CreateElisaAssayCollectionOptions,
+  CreateFlowCytometryAssayCollectionOptions,
+  CreateFlowCytometryPanelTemplateOptions,
+  CreateInstrumentRunTemplateOptions,
+  CreateLcmsBatchCollectionOptions,
+  CreatePlateMapTemplateOptions,
+  CreateProtocolStepsTemplateOptions,
+  CreateQpcrExpressionCollectionOptions,
+  CreateQpcrPlateTemplateOptions,
+  CreateReagentListTemplateOptions,
+  CreateSamplePrepTemplateOptions,
+  CreateSampleSheetTemplateOptions,
+  CreateTargetedMetabolomicsCollectionOptions,
+  CreateTimeCourseTemplateOptions,
+  CreateWellPlateScreenCollectionOptions,
+  CreateWesternBlotAssayCollectionOptions,
+} from './templateCreateOptions'
+
+export type {
+  AssayMatrixColumnsAdapterResult,
+  AssayMatrixDataFrameAdapterResult,
+  AssayMatrixRowsAdapterResult,
+  AssayMatrixSampleOptionsAdapterResult,
+  CalibrationCurveColumnsAdapterResult,
+  CalibrationCurveDataFrameAdapterResult,
+  CalibrationCurveRowsAdapterResult,
+  DataFrameAdapterResult,
+  DoseConditionsAdapterResult,
+  FlowPanelColumnsAdapterResult,
+  FlowPanelDataFrameAdapterResult,
+  FlowPanelRowsAdapterResult,
+  InstrumentRunColumnsAdapterResult,
+  InstrumentRunDataFrameAdapterResult,
+  InstrumentRunRowsAdapterResult,
+  InstrumentRunScheduleEventsAdapterResult,
+  InstrumentRunStepsAdapterResult,
+  PlateMapEditorAdapterResult,
+  ProtocolColumnsAdapterResult,
+  ProtocolDataFrameAdapterResult,
+  ProtocolRowsAdapterResult,
+  ProtocolStepsAdapterResult,
+  QpcrColumnsAdapterResult,
+  QpcrDataFrameAdapterResult,
+  QpcrRowsAdapterResult,
+  QpcrWellMapAdapterResult,
+  ReagentColumnsAdapterResult,
+  ReagentDataFrameAdapterResult,
+  ReagentListItemsAdapterResult,
+  ReagentRowsAdapterResult,
+  SampleColumnsAdapterResult,
+  SampleDataFrameAdapterResult,
+  SampleOptionsAdapterResult,
+  SamplePrepColumnsAdapterResult,
+  SamplePrepDataFrameAdapterResult,
+  SamplePrepRowsAdapterResult,
+  SampleRowsAdapterResult,
+  TemplateDataFrameAdapterResult,
+  TimeCourseColumnsAdapterResult,
+  TimeCourseDataFrameAdapterResult,
+  TimeCourseRowsAdapterResult,
+  TimeCourseStepsAdapterResult,
+  WellMapAdapterResult,
+} from './templateAdapterTypes'

package/src/templates/wellPlateScreenCollectionBuilder.ts

@@ -0,0 +1,36 @@
+import { DEFAULT_SAMPLE_COLORS } from './builderDefaults'
+import { createDoseResponseTemplate } from './doseResponseBuilder'
+import { createPlateMapTemplate } from './plateMapBuilder'
+import { createSampleSheetTemplate } from './sampleSheetBuilder'
+import { presetSampleRecords } from './sampleNormalizers'
+import { createTemplateCollection } from './templateEnvelopes'
+import type {
+  CreateWellPlateScreenCollectionOptions,
+  TemplateCollectionEnvelope,
+} from './types'
+
+export function createWellPlateScreenCollection(
+  options: CreateWellPlateScreenCollectionOptions = {}
+): TemplateCollectionEnvelope {
+  const sampleRecords = presetSampleRecords(options.samples ?? ['Control', 'Treatment'])
+  const plate = createPlateMapTemplate({
+    name: options.plateName ?? 'Screen plate',
+    format: options.plateFormat ?? 96,
+    samples: 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 doseResponse = createDoseResponseTemplate({
+    compounds: options.compounds ?? { 'Compound A': [10, 1, 0.1] },
+    unit: options.unit ?? 'uM',
+    replicates: options.replicates ?? 3,
+    layout: plate,
+  })
+  return createTemplateCollection(
+    [plate, sampleSheet, doseResponse],
+    { preset: 'wellplate-screen', ...(options.metadata ?? {}) }
+  )
+}

package/src/templates/westernBlotAssayCollectionBuilder.ts

@@ -0,0 +1,68 @@
+import { createAssayMatrixTemplate } from './assayMatrixBuilder'
+import { idFromName } from './builderIdUtils'
+import { createProtocolStepsTemplate } from './protocolStepsBuilder'
+import { createReagentListTemplate } from './reagentListBuilder'
+import { createSampleSheetTemplate } from './sampleSheetBuilder'
+import { presetSampleRecords } from './sampleNormalizers'
+import { createTemplateCollection } from './templateEnvelopes'
+import type {
+  CreateWesternBlotAssayCollectionOptions,
+  TemplateCollectionEnvelope,
+} from './types'
+
+export function createWesternBlotAssayCollection(
+  options: CreateWesternBlotAssayCollectionOptions = {}
+): TemplateCollectionEnvelope {
+  const sampleRecords = presetSampleRecords(options.samples ?? ['Control', 'Treatment'])
+  const loadingControl = options.loadingControl ?? 'ACTB'
+  const targetNames = (options.targets ?? ['Target protein']).map(target =>
+    typeof target === 'string' ? target : target.name ?? target.id
+  )
+  const featureNames = loadingControl && !targetNames.includes(loadingControl)
+    ? [...targetNames, loadingControl]
+    : targetNames
+  const sampleSheet = createSampleSheetTemplate({ samples: sampleRecords })
+  const reagentList = createReagentListTemplate({
+    reagents: [
+      { id: 'primary-antibody', name: 'Primary antibody', kind: 'antibody', storageCondition: '4C' },
+      { id: 'secondary-antibody', name: 'Secondary antibody', kind: 'antibody', storageCondition: '4C' },
+      { id: 'lysis-buffer', name: 'Lysis buffer', kind: 'buffer', storageCondition: '4C' },
+      { id: 'blocking-buffer', name: 'Blocking buffer', kind: 'buffer', storageCondition: '4C' },
+      { id: 'wash-buffer', name: 'TBST wash buffer', kind: 'buffer', storageCondition: 'RT' },
+      { id: 'substrate', name: 'Detection substrate', kind: 'reagent', storageCondition: '4C' },
+    ],
+    metadata: { assay: 'western-blot' },
+  })
+  const protocol = createProtocolStepsTemplate({
+    steps: [
+      { id: 'lyse-samples', type: 'addition', name: 'Lyse samples', duration: 30 },
+      { id: 'run-gel', type: 'custom', name: 'Run SDS-PAGE', duration: 90 },
+      { id: 'transfer', type: 'transfer', name: 'Transfer to membrane', duration: 60 },
+      { id: 'block', type: 'incubation', name: 'Block membrane', duration: 60 },
+      { id: 'primary-antibody', type: 'incubation', name: 'Primary antibody incubation', duration: 960 },
+      { id: 'secondary-antibody', type: 'incubation', name: 'Secondary antibody incubation', duration: 60 },
+      { id: 'detect', type: 'measurement', name: 'Detect and quantify bands', duration: 30 },
+    ],
+    metadata: { assay: 'western-blot' },
+  })
+  const assayMatrix = createAssayMatrixTemplate({
+    samples: sampleRecords.map(sample => ({
+      sampleId: sample.sampleId,
+      name: sample.name,
+      group: sample.group,
+      metadata: sample.metadata ?? {},
+    })),
+    features: featureNames.map((feature, index) => ({
+      id: idFromName(feature, `feature-${index + 1}`),
+      name: feature,
+      type: 'protein',
+      unit: 'relative intensity',
+      metadata: { loadingControl: feature === loadingControl },
+    })),
+    metadata: { assay: 'western-blot', loadingControl },
+  })
+  return createTemplateCollection(
+    [sampleSheet, reagentList, protocol, assayMatrix],
+    { preset: 'western-blot-assay', ...(options.metadata ?? {}) }
+  )
+}