@morscherlab/mld-sdk 0.6.0

package/src/composables/useConcentrationUnits.ts

@@ -0,0 +1,245 @@
+import { computed, type ComputedRef } from 'vue'
+
+// Concentration unit types
+export type MolarityUnit = 'pM' | 'nM' | 'µM' | 'mM' | 'M'
+export type MassVolumeUnit = 'pg/mL' | 'ng/mL' | 'µg/mL' | 'mg/mL' | 'g/mL'
+export type PercentageUnit = '% v/v' | '% w/v' | '% w/w'
+export type ConcentrationUnit = MolarityUnit | MassVolumeUnit | PercentageUnit | string
+
+export interface ConcentrationValue {
+  value: number
+  unit: ConcentrationUnit
+}
+
+export interface UnitCategory {
+  label: string
+  units: ConcentrationUnit[]
+}
+
+export interface UseConcentrationUnitsReturn {
+  unitCategories: ComputedRef<UnitCategory[]>
+  molarityUnits: MolarityUnit[]
+  massVolumeUnits: MassVolumeUnit[]
+  percentageUnits: PercentageUnit[]
+  convert: (value: number, from: ConcentrationUnit, to: ConcentrationUnit, mw?: number) => number | null
+  formatWithUnit: (concentration: ConcentrationValue, precision?: number) => string
+  parseConcentration: (input: string) => ConcentrationValue | null
+  getBaseUnit: (unit: ConcentrationUnit) => ConcentrationUnit
+  getConversionHint: (concentration: ConcentrationValue) => string | null
+  isMolarity: (unit: ConcentrationUnit) => boolean
+  isMassVolume: (unit: ConcentrationUnit) => boolean
+  isPercentage: (unit: ConcentrationUnit) => boolean
+}
+
+// Conversion factors to base unit (M for molarity, g/mL for mass/volume)
+const MOLARITY_FACTORS: Record<MolarityUnit, number> = {
+  'pM': 1e-12,
+  'nM': 1e-9,
+  'µM': 1e-6,
+  'mM': 1e-3,
+  'M': 1,
+}
+
+const MASS_VOLUME_FACTORS: Record<MassVolumeUnit, number> = {
+  'pg/mL': 1e-12,
+  'ng/mL': 1e-9,
+  'µg/mL': 1e-6,
+  'mg/mL': 1e-3,
+  'g/mL': 1,
+}
+
+// Percentage conversion factors (for potential future use)
+// const PERCENTAGE_FACTORS: Record<PercentageUnit, number> = {
+//   '% v/v': 0.01,
+//   '% w/v': 0.01,
+//   '% w/w': 0.01,
+// }
+
+const MOLARITY_UNITS: MolarityUnit[] = ['pM', 'nM', 'µM', 'mM', 'M']
+const MASS_VOLUME_UNITS: MassVolumeUnit[] = ['pg/mL', 'ng/mL', 'µg/mL', 'mg/mL', 'g/mL']
+const PERCENTAGE_UNITS: PercentageUnit[] = ['% v/v', '% w/v', '% w/w']
+
+export function useConcentrationUnits(): UseConcentrationUnitsReturn {
+  const unitCategories = computed<UnitCategory[]>(() => [
+    { label: 'Molarity', units: MOLARITY_UNITS },
+    { label: 'Mass/Volume', units: MASS_VOLUME_UNITS },
+    { label: 'Percentage', units: PERCENTAGE_UNITS },
+  ])
+
+  function isMolarity(unit: ConcentrationUnit): unit is MolarityUnit {
+    return MOLARITY_UNITS.includes(unit as MolarityUnit)
+  }
+
+  function isMassVolume(unit: ConcentrationUnit): unit is MassVolumeUnit {
+    return MASS_VOLUME_UNITS.includes(unit as MassVolumeUnit)
+  }
+
+  function isPercentage(unit: ConcentrationUnit): unit is PercentageUnit {
+    return PERCENTAGE_UNITS.includes(unit as PercentageUnit)
+  }
+
+  function getBaseUnit(unit: ConcentrationUnit): ConcentrationUnit {
+    if (isMolarity(unit)) return 'M'
+    if (isMassVolume(unit)) return 'g/mL'
+    if (isPercentage(unit)) return '% w/v'
+    return unit
+  }
+
+  function convert(
+    value: number,
+    from: ConcentrationUnit,
+    to: ConcentrationUnit,
+    mw?: number
+  ): number | null {
+    if (from === to) return value
+    if (value === 0) return 0
+
+    // Same category conversion
+    if (isMolarity(from) && isMolarity(to)) {
+      const baseValue = value * MOLARITY_FACTORS[from]
+      return baseValue / MOLARITY_FACTORS[to]
+    }
+
+    if (isMassVolume(from) && isMassVolume(to)) {
+      const baseValue = value * MASS_VOLUME_FACTORS[from]
+      return baseValue / MASS_VOLUME_FACTORS[to]
+    }
+
+    if (isPercentage(from) && isPercentage(to)) {
+      // Percentage conversions within same category are direct
+      return value
+    }
+
+    // Cross-category conversion (requires molecular weight)
+    if (mw && mw > 0) {
+      // Molarity to Mass/Volume
+      if (isMolarity(from) && isMassVolume(to)) {
+        // Convert to M, then to g/mL using MW, then to target unit
+        const molarConc = value * MOLARITY_FACTORS[from]
+        const massConc = molarConc * mw // g/mL (MW in g/mol, concentration in mol/L = g/L)
+        return massConc / MASS_VOLUME_FACTORS[to]
+      }
+
+      // Mass/Volume to Molarity
+      if (isMassVolume(from) && isMolarity(to)) {
+        // Convert to g/mL, then to M using MW, then to target unit
+        const massConc = value * MASS_VOLUME_FACTORS[from]
+        const molarConc = massConc / mw // M (g/mL / g/mol = mol/L)
+        return molarConc / MOLARITY_FACTORS[to]
+      }
+    }
+
+    return null // Cannot convert without MW or between incompatible units
+  }
+
+  function formatWithUnit(concentration: ConcentrationValue, precision: number = 3): string {
+    const { value, unit } = concentration
+    if (value === 0) return `0 ${unit}`
+
+    // Use appropriate precision based on value magnitude
+    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 after decimal point
+    formattedValue = formattedValue.replace(/\.?0+$/, '')
+    formattedValue = formattedValue.replace(/\.?0+e/, 'e')
+
+    return `${formattedValue} ${unit}`
+  }
+
+  function parseConcentration(input: string): ConcentrationValue | null {
+    const trimmed = input.trim()
+    if (!trimmed) return null
+
+    // Match number followed by optional unit
+    const match = trimmed.match(/^([-+]?\d*\.?\d+(?:[eE][-+]?\d+)?)\s*(.*)$/)
+    if (!match) return null
+
+    const value = parseFloat(match[1])
+    if (isNaN(value)) return null
+
+    let unit = match[2].trim()
+    if (!unit) {
+      return null // Unit is required
+    }
+
+    // Normalize common variations
+    unit = unit
+      .replace(/uM/i, 'µM')
+      .replace(/um/i, 'µM')
+      .replace(/ug\/ml/i, 'µg/mL')
+      .replace(/ng\/ml/i, 'ng/mL')
+      .replace(/mg\/ml/i, 'mg/mL')
+      .replace(/pg\/ml/i, 'pg/mL')
+      .replace(/g\/ml/i, 'g/mL')
+
+    return { value, unit }
+  }
+
+  function getConversionHint(concentration: ConcentrationValue): string | null {
+    const { value, unit } = concentration
+    if (value === 0) return null
+
+    // Find adjacent unit for conversion hint
+    if (isMolarity(unit)) {
+      const index = MOLARITY_UNITS.indexOf(unit)
+      // If value is large, suggest next higher unit
+      if (value >= 1000 && index < MOLARITY_UNITS.length - 1) {
+        const nextUnit = MOLARITY_UNITS[index + 1]
+        const converted = convert(value, unit, nextUnit)
+        if (converted !== null) {
+          return formatWithUnit({ value: converted, unit: nextUnit })
+        }
+      }
+      // If value is small, suggest next lower unit
+      if (value < 1 && index > 0) {
+        const prevUnit = MOLARITY_UNITS[index - 1]
+        const converted = convert(value, unit, prevUnit)
+        if (converted !== null) {
+          return formatWithUnit({ value: converted, unit: prevUnit })
+        }
+      }
+    }
+
+    if (isMassVolume(unit)) {
+      const index = MASS_VOLUME_UNITS.indexOf(unit)
+      if (value >= 1000 && index < MASS_VOLUME_UNITS.length - 1) {
+        const nextUnit = MASS_VOLUME_UNITS[index + 1]
+        const converted = convert(value, unit, nextUnit)
+        if (converted !== null) {
+          return formatWithUnit({ value: converted, unit: nextUnit })
+        }
+      }
+      if (value < 1 && index > 0) {
+        const prevUnit = MASS_VOLUME_UNITS[index - 1]
+        const converted = convert(value, unit, prevUnit)
+        if (converted !== null) {
+          return formatWithUnit({ value: converted, unit: prevUnit })
+        }
+      }
+    }
+
+    return null
+  }
+
+  return {
+    unitCategories,
+    molarityUnits: MOLARITY_UNITS,
+    massVolumeUnits: MASS_VOLUME_UNITS,
+    percentageUnits: PERCENTAGE_UNITS,
+    convert,
+    formatWithUnit,
+    parseConcentration,
+    getBaseUnit,
+    getConversionHint,
+    isMolarity,
+    isMassVolume,
+    isPercentage,
+  }
+}

package/src/composables/useDoseCalculator.ts

@@ -0,0 +1,369 @@
+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,
+}
+
+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,
+  }
+}