@morscherlab/mint-sdk 1.0.0-alpha.2

package/src/composables/useDoseCalculator.ts

@@ -0,0 +1,370 @@
+import {
+  useConcentrationUnits,
+  type ConcentrationValue,
+  type MolarityUnit,
+  type MassVolumeUnit,
+} from './useConcentrationUnits'
+
+// Volume units
+export type VolumeUnit = 'µL' | 'mL' | 'L'
+
+export interface VolumeValue {
+  value: number
+  unit: VolumeUnit
+}
+
+// Dilution calculation types
+export interface DilutionParams {
+  stockConcentration: ConcentrationValue
+  finalConcentration: ConcentrationValue
+  finalVolume: VolumeValue
+}
+
+export interface DilutionResult {
+  stockVolume: VolumeValue
+  diluentVolume: VolumeValue
+  dilutionFactor: number
+  valid: boolean
+  error?: string
+}
+
+// Serial dilution types
+export interface SerialDilutionParams {
+  startingConcentration: ConcentrationValue
+  dilutionFactor: number
+  numberOfDilutions: number
+  volumePerWell: VolumeValue
+}
+
+export interface SerialDilutionStep {
+  stepNumber: number
+  concentration: ConcentrationValue
+  transferVolume: VolumeValue
+  diluentVolume: VolumeValue
+}
+
+export interface SerialDilutionResult {
+  steps: SerialDilutionStep[]
+  totalStockVolume: VolumeValue
+  valid: boolean
+  error?: string
+}
+
+// Conversion types
+export interface ConversionResult {
+  result: ConcentrationValue
+  valid: boolean
+  error?: string
+}
+
+// Well concentration for plate integration
+export interface WellConcentration {
+  wellId: string
+  concentration: ConcentrationValue
+  volume?: VolumeValue
+}
+
+export interface UseDoseCalculatorReturn {
+  volumeUnits: VolumeUnit[]
+  calculateDilution: (params: DilutionParams) => DilutionResult
+  calculateSerialDilution: (params: SerialDilutionParams) => SerialDilutionResult
+  convertMassToMolar: (
+    mass: number,
+    massUnit: MassVolumeUnit,
+    mw: number
+  ) => ConcentrationValue
+  convertMolarToMass: (
+    molar: number,
+    molarUnit: MolarityUnit,
+    mw: number
+  ) => ConcentrationValue
+  convertVolume: (value: number, from: VolumeUnit, to: VolumeUnit) => number
+  formatVolume: (volume: VolumeValue, precision?: number) => string
+  generateWellConcentrations: (
+    result: SerialDilutionResult,
+    wellIds: string[]
+  ) => WellConcentration[]
+}
+
+const VOLUME_UNITS: VolumeUnit[] = ['µL', 'mL', 'L']
+
+const VOLUME_FACTORS: Record<VolumeUnit, number> = {
+  'µL': 1e-6,
+  'mL': 1e-3,
+  'L': 1,
+}
+
+/** Calculates single dilutions, serial dilution series, and plate-filling volumes for dose-response experiments. */
+export function useDoseCalculator(): UseDoseCalculatorReturn {
+  const { convert } = useConcentrationUnits()
+
+  function convertVolume(value: number, from: VolumeUnit, to: VolumeUnit): number {
+    if (from === to) return value
+    const baseValue = value * VOLUME_FACTORS[from]
+    return baseValue / VOLUME_FACTORS[to]
+  }
+
+  function formatVolume(volume: VolumeValue, precision: number = 3): string {
+    const { value, unit } = volume
+    if (value === 0) return `0 ${unit}`
+
+    let formattedValue: string
+    if (Math.abs(value) >= 1000) {
+      formattedValue = value.toExponential(precision - 1)
+    } else if (Math.abs(value) < 0.001) {
+      formattedValue = value.toExponential(precision - 1)
+    } else {
+      formattedValue = value.toPrecision(precision)
+    }
+
+    // Remove trailing zeros
+    formattedValue = formattedValue.replace(/\.?0+$/, '')
+    formattedValue = formattedValue.replace(/\.?0+e/, 'e')
+
+    return `${formattedValue} ${unit}`
+  }
+
+  function calculateDilution(params: DilutionParams): DilutionResult {
+    const { stockConcentration, finalConcentration, finalVolume } = params
+
+    // Validate inputs
+    if (stockConcentration.value <= 0) {
+      return {
+        stockVolume: { value: 0, unit: 'µL' },
+        diluentVolume: { value: 0, unit: 'µL' },
+        dilutionFactor: 0,
+        valid: false,
+        error: 'Stock concentration must be positive',
+      }
+    }
+
+    if (finalConcentration.value <= 0) {
+      return {
+        stockVolume: { value: 0, unit: 'µL' },
+        diluentVolume: { value: 0, unit: 'µL' },
+        dilutionFactor: 0,
+        valid: false,
+        error: 'Final concentration must be positive',
+      }
+    }
+
+    if (finalVolume.value <= 0) {
+      return {
+        stockVolume: { value: 0, unit: 'µL' },
+        diluentVolume: { value: 0, unit: 'µL' },
+        dilutionFactor: 0,
+        valid: false,
+        error: 'Final volume must be positive',
+      }
+    }
+
+    // Convert concentrations to same unit
+    const convertedFinal = convert(
+      finalConcentration.value,
+      finalConcentration.unit,
+      stockConcentration.unit
+    )
+
+    if (convertedFinal === null) {
+      return {
+        stockVolume: { value: 0, unit: 'µL' },
+        diluentVolume: { value: 0, unit: 'µL' },
+        dilutionFactor: 0,
+        valid: false,
+        error: 'Cannot convert between concentration units. Provide molecular weight for mass↔molarity conversion.',
+      }
+    }
+
+    // Check that stock is more concentrated than final
+    if (convertedFinal >= stockConcentration.value) {
+      return {
+        stockVolume: { value: 0, unit: 'µL' },
+        diluentVolume: { value: 0, unit: 'µL' },
+        dilutionFactor: 0,
+        valid: false,
+        error: 'Stock concentration must be higher than final concentration',
+      }
+    }
+
+    // Calculate using C1V1 = C2V2
+    const dilutionFactor = stockConcentration.value / convertedFinal
+    const finalVolumeInL = convertVolume(finalVolume.value, finalVolume.unit, 'L')
+    const stockVolumeInL = finalVolumeInL / dilutionFactor
+    const diluentVolumeInL = finalVolumeInL - stockVolumeInL
+
+    // Convert to appropriate unit (µL for small volumes, mL for larger)
+    let outputUnit: VolumeUnit = 'µL'
+    if (stockVolumeInL >= 0.001) outputUnit = 'mL'
+    if (stockVolumeInL >= 1) outputUnit = 'L'
+
+    return {
+      stockVolume: {
+        value: convertVolume(stockVolumeInL, 'L', outputUnit),
+        unit: outputUnit,
+      },
+      diluentVolume: {
+        value: convertVolume(diluentVolumeInL, 'L', outputUnit),
+        unit: outputUnit,
+      },
+      dilutionFactor,
+      valid: true,
+    }
+  }
+
+  function calculateSerialDilution(params: SerialDilutionParams): SerialDilutionResult {
+    const { startingConcentration, dilutionFactor, numberOfDilutions, volumePerWell } = params
+
+    // Validate inputs
+    if (startingConcentration.value <= 0) {
+      return {
+        steps: [],
+        totalStockVolume: { value: 0, unit: 'µL' },
+        valid: false,
+        error: 'Starting concentration must be positive',
+      }
+    }
+
+    if (dilutionFactor <= 1) {
+      return {
+        steps: [],
+        totalStockVolume: { value: 0, unit: 'µL' },
+        valid: false,
+        error: 'Dilution factor must be greater than 1',
+      }
+    }
+
+    if (numberOfDilutions < 1) {
+      return {
+        steps: [],
+        totalStockVolume: { value: 0, unit: 'µL' },
+        valid: false,
+        error: 'Number of dilutions must be at least 1',
+      }
+    }
+
+    if (volumePerWell.value <= 0) {
+      return {
+        steps: [],
+        totalStockVolume: { value: 0, unit: 'µL' },
+        valid: false,
+        error: 'Volume per well must be positive',
+      }
+    }
+
+    const steps: SerialDilutionStep[] = []
+    let currentConcentration = startingConcentration.value
+    const transferVolume = volumePerWell.value / (dilutionFactor - 1)
+    const diluentVolume = volumePerWell.value - transferVolume
+
+    for (let i = 0; i < numberOfDilutions; i++) {
+      steps.push({
+        stepNumber: i + 1,
+        concentration: {
+          value: currentConcentration,
+          unit: startingConcentration.unit,
+        },
+        transferVolume: {
+          value: i === 0 ? volumePerWell.value : transferVolume,
+          unit: volumePerWell.unit,
+        },
+        diluentVolume: {
+          value: i === 0 ? 0 : diluentVolume,
+          unit: volumePerWell.unit,
+        },
+      })
+      currentConcentration /= dilutionFactor
+    }
+
+    // Total stock needed for first well
+    const totalStockVolume: VolumeValue = {
+      value: volumePerWell.value + (transferVolume * (numberOfDilutions - 1)),
+      unit: volumePerWell.unit,
+    }
+
+    return {
+      steps,
+      totalStockVolume,
+      valid: true,
+    }
+  }
+
+  function convertMassToMolar(
+    mass: number,
+    massUnit: MassVolumeUnit,
+    mw: number
+  ): ConcentrationValue {
+    // Convert mass to g/mL, then to M using MW
+    const converted = convert(mass, massUnit, 'µM', mw)
+    if (converted !== null) {
+      return { value: converted, unit: 'µM' }
+    }
+    // Fallback to manual calculation
+    // mass (g/mL) / MW (g/mol) = mol/L = M
+    const massInGML = mass * getMassVolumeFactor(massUnit)
+    const molarConc = massInGML / mw
+    return { value: molarConc * 1e6, unit: 'µM' }
+  }
+
+  function convertMolarToMass(
+    molar: number,
+    molarUnit: MolarityUnit,
+    mw: number
+  ): ConcentrationValue {
+    // Convert M to mass using MW
+    const converted = convert(molar, molarUnit, 'µg/mL', mw)
+    if (converted !== null) {
+      return { value: converted, unit: 'µg/mL' }
+    }
+    // Fallback to manual calculation
+    // mol/L * MW (g/mol) = g/L = mg/mL
+    const molarInM = molar * getMolarityFactor(molarUnit)
+    const massConc = molarInM * mw * 1e6 // µg/mL
+    return { value: massConc, unit: 'µg/mL' }
+  }
+
+  function getMassVolumeFactor(unit: MassVolumeUnit): number {
+    const factors: Record<MassVolumeUnit, number> = {
+      'pg/mL': 1e-12,
+      'ng/mL': 1e-9,
+      'µg/mL': 1e-6,
+      'mg/mL': 1e-3,
+      'g/mL': 1,
+    }
+    return factors[unit]
+  }
+
+  function getMolarityFactor(unit: MolarityUnit): number {
+    const factors: Record<MolarityUnit, number> = {
+      'pM': 1e-12,
+      'nM': 1e-9,
+      'µM': 1e-6,
+      'mM': 1e-3,
+      'M': 1,
+    }
+    return factors[unit]
+  }
+
+  function generateWellConcentrations(
+    result: SerialDilutionResult,
+    wellIds: string[]
+  ): WellConcentration[] {
+    if (!result.valid || result.steps.length === 0) return []
+
+    return result.steps.slice(0, wellIds.length).map((step, index) => ({
+      wellId: wellIds[index],
+      concentration: step.concentration,
+      volume: step.transferVolume,
+    }))
+  }
+
+  return {
+    volumeUnits: VOLUME_UNITS,
+    calculateDilution,
+    calculateSerialDilution,
+    convertMassToMolar,
+    convertMolarToMass,
+    convertVolume,
+    formatVolume,
+    generateWellConcentrations,
+  }
+}

package/src/composables/useExperimentData.ts

@@ -0,0 +1,86 @@
+import { ref, computed, type Ref, type ComputedRef } from 'vue'
+import { useApi } from './useApi'
+import type { TreeNode, SummaryData } from '../types'
+
+export interface UseExperimentDataOptions {
+  apiBaseUrl?: string
+  immediate?: boolean
+}
+
+export interface UseExperimentDataReturn {
+  data: Ref<Record<string, unknown> | null>
+  treeData: ComputedRef<TreeNode[]>
+  tableData: ComputedRef<Record<string, unknown>[]>
+  summaryData: ComputedRef<SummaryData | null>
+  isLoading: Ref<boolean>
+  error: Ref<string | null>
+  fetch: (experimentId: number) => Promise<void>
+  refresh: () => Promise<void>
+}
+
+/** Fetches and normalises experiment output data (tree, table, summary) from the platform API. */
+export function useExperimentData(
+  options: UseExperimentDataOptions = {},
+): UseExperimentDataReturn {
+  const api = useApi({ baseUrl: options.apiBaseUrl })
+
+  const data = ref<Record<string, unknown> | null>(null)
+  const isLoading = ref(false)
+  const error = ref<string | null>(null)
+  let lastExperimentId: number | null = null
+
+  const treeData = computed<TreeNode[]>(() => {
+    if (!data.value) return []
+    const tree = data.value.tree_data ?? data.value.treeData
+    return Array.isArray(tree) ? tree as TreeNode[] : []
+  })
+
+  const tableData = computed<Record<string, unknown>[]>(() => {
+    if (!data.value) return []
+    const table = data.value.table_data ?? data.value.tableData
+    return Array.isArray(table) ? table as Record<string, unknown>[] : []
+  })
+
+  const summaryData = computed<SummaryData | null>(() => {
+    if (!data.value) return null
+    const summary = data.value.summary_data ?? data.value.summaryData
+    if (summary && typeof summary === 'object' && 'metadata' in (summary as Record<string, unknown>)) {
+      return summary as SummaryData
+    }
+    return null
+  })
+
+  async function fetchData(experimentId: number): Promise<void> {
+    lastExperimentId = experimentId
+    isLoading.value = true
+    error.value = null
+    try {
+      const result = await api.get<Record<string, unknown>>(
+        `/experiments/${experimentId}/data`,
+      )
+      data.value = result
+    } catch (e) {
+      error.value = e instanceof Error ? e.message : 'Failed to fetch experiment data'
+      data.value = null
+    } finally {
+      isLoading.value = false
+    }
+  }
+
+  async function refresh(): Promise<void> {
+    if (lastExperimentId !== null) {
+      await fetchData(lastExperimentId)
+    }
+  }
+
+  return {
+    data,
+    treeData,
+    tableData,
+    summaryData,
+    isLoading,
+    error,
+    fetch: fetchData,
+    refresh,
+  }
+}

package/src/composables/useExperimentSave.ts

@@ -0,0 +1,192 @@
+import { ref, type Ref } from 'vue'
+import { useApi } from './useApi'
+
+export interface UseExperimentSaveOptions {
+  /** Default plugin_id for all save/load calls. */
+  pluginId?: string
+  /** Default schema version for design saves (defaults to "1.0"). */
+  schemaVersion?: string
+  /** Override API base URL. */
+  apiBaseUrl?: string
+}
+
+export interface UseExperimentSaveReturn {
+  /** Whether a save operation is in progress. */
+  isSaving: Ref<boolean>
+  /** Error message from the last failed operation, or null. */
+  error: Ref<string | null>
+  /** Timestamp of the last successful save, or null. */
+  lastSavedAt: Ref<Date | null>
+  /** Save design data for an experiment. */
+  saveDesign: (experimentId: number, data: Record<string, unknown>) => Promise<boolean>
+  /** Save analysis result for an experiment. */
+  saveAnalysis: (experimentId: number, result: Record<string, unknown>) => Promise<boolean>
+  /** Save design and/or analysis in one call. */
+  save: (experimentId: number, opts: {
+    design?: Record<string, unknown>
+    analysis?: Record<string, unknown>
+  }) => Promise<boolean>
+  /** Load design data for an experiment. */
+  loadDesign: (experimentId: number) => Promise<Record<string, unknown> | null>
+  /** Load analysis result for an experiment. */
+  loadAnalysis: (experimentId: number) => Promise<Record<string, unknown> | null>
+  /** Delete design data for an experiment. */
+  deleteDesign: (experimentId: number) => Promise<boolean>
+  /** Delete analysis result for an experiment. */
+  deleteAnalysis: (experimentId: number) => Promise<boolean>
+}
+
+/** Persists and loads experiment design and analysis data via the plugin's API endpoint. */
+export function useExperimentSave(
+  options: UseExperimentSaveOptions = {},
+): UseExperimentSaveReturn {
+  const api = useApi({ baseUrl: options.apiBaseUrl })
+  const pluginId = options.pluginId
+  const schemaVersion = options.schemaVersion ?? '1.0'
+
+  const isSaving = ref(false)
+  const error = ref<string | null>(null)
+  const lastSavedAt = ref<Date | null>(null)
+
+  function setError(e: unknown): void {
+    error.value = e instanceof Error ? e.message : 'Unknown error'
+  }
+
+  async function saveDesign(
+    experimentId: number,
+    data: Record<string, unknown>,
+  ): Promise<boolean> {
+    if (!pluginId) {
+      error.value = 'pluginId is required for saveDesign'
+      return false
+    }
+    isSaving.value = true
+    error.value = null
+    try {
+      await api.put(`/experiments/${experimentId}/data`, {
+        plugin_id: pluginId,
+        data,
+        schema_version: schemaVersion,
+      })
+      lastSavedAt.value = new Date()
+      return true
+    } catch (e) {
+      setError(e)
+      return false
+    } finally {
+      isSaving.value = false
+    }
+  }
+
+  async function saveAnalysis(
+    experimentId: number,
+    result: Record<string, unknown>,
+  ): Promise<boolean> {
+    if (!pluginId) {
+      error.value = 'pluginId is required for saveAnalysis'
+      return false
+    }
+    isSaving.value = true
+    error.value = null
+    try {
+      await api.put(`/experiments/${experimentId}/results/${pluginId}`, {
+        result,
+      })
+      lastSavedAt.value = new Date()
+      return true
+    } catch (e) {
+      setError(e)
+      return false
+    } finally {
+      isSaving.value = false
+    }
+  }
+
+  async function save(
+    experimentId: number,
+    opts: { design?: Record<string, unknown>; analysis?: Record<string, unknown> },
+  ): Promise<boolean> {
+    if ((opts.design || opts.analysis) && !pluginId) {
+      error.value = 'pluginId is required for save'
+      return false
+    }
+    isSaving.value = true
+    error.value = null
+    try {
+      if (opts.design) {
+        await api.put(`/experiments/${experimentId}/data`, {
+          plugin_id: pluginId,
+          data: opts.design,
+          schema_version: schemaVersion,
+        })
+      }
+      if (opts.analysis) {
+        await api.put(`/experiments/${experimentId}/results/${pluginId}`, {
+          result: opts.analysis,
+        })
+      }
+      lastSavedAt.value = new Date()
+      return true
+    } catch (e) {
+      setError(e)
+      return false
+    } finally {
+      isSaving.value = false
+    }
+  }
+
+  async function loadDesign(
+    experimentId: number,
+  ): Promise<Record<string, unknown> | null> {
+    try {
+      return await api.get<Record<string, unknown>>(`/experiments/${experimentId}/data`)
+    } catch {
+      return null
+    }
+  }
+
+  async function loadAnalysis(
+    experimentId: number,
+  ): Promise<Record<string, unknown> | null> {
+    if (!pluginId) return null
+    try {
+      return await api.get<Record<string, unknown>>(
+        `/experiments/${experimentId}/results/${pluginId}`,
+      )
+    } catch {
+      return null
+    }
+  }
+
+  async function deleteDesign(experimentId: number): Promise<boolean> {
+    try {
+      await api.delete(`/experiments/${experimentId}/data`)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  async function deleteAnalysis(experimentId: number): Promise<boolean> {
+    if (!pluginId) return false
+    try {
+      await api.delete(`/experiments/${experimentId}/results/${pluginId}`)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  return {
+    isSaving,
+    error,
+    lastSavedAt,
+    saveDesign,
+    saveAnalysis,
+    save,
+    loadDesign,
+    loadAnalysis,
+    deleteDesign,
+    deleteAnalysis,
+  }
+}