@opentrons/shared-data 0.0.0-alpha.2

package/js/helpers/getWellNamePerMultiTip.ts

@@ -0,0 +1,86 @@
+import range from 'lodash/range'
+import { get96Channel384WellPlateWells } from './get96Channel384WellPlateWells'
+import { getLabwareHasQuirk, orderWells, sortWells } from './index'
+import type { LabwareDefinition2 } from '../types'
+
+// TODO Ian 2018-03-13 pull pipette offsets/positions from some pipette definitions data
+const OFFSET_8_CHANNEL = 9 // offset in mm between tips
+
+const MULTICHANNEL_TIP_SPAN = OFFSET_8_CHANNEL * (8 - 1) // length in mm from first to last tip of multichannel
+
+export function findWellAt(
+  labwareDef: LabwareDefinition2,
+  x: number,
+  y: number
+): string | null | undefined {
+  return Object.keys(labwareDef.wells)
+    .sort(sortWells)
+    .find((wellName: string) => {
+      const well = labwareDef.wells[wellName]
+
+      if (well.shape === 'circular') {
+        return (
+          Math.sqrt(Math.pow(x - well.x, 2) + Math.pow(y - well.y, 2)) <
+          well.diameter / 2
+        )
+      }
+
+      // Not circular, must be a rectangular well
+      // For rectangular wells, (x, y) is at the center.
+      return (
+        Math.abs(x - well.x) < well.xDimension / 2 &&
+        Math.abs(y - well.y) < well.yDimension / 2
+      )
+    })
+}
+
+// "topWellName" means well at the "top" of the column we're accessing: usually A row, or B row for 384-format
+export function getWellNamePerMultiTip(
+  labwareDef: LabwareDefinition2,
+  topWellName: string,
+  channels: 8 | 96
+): string[] | null {
+  const topWell = labwareDef.wells[topWellName]
+  if (!topWell) {
+    console.warn(
+      `well "${topWellName}" does not exist in labware ${labwareDef?.namespace}/${labwareDef?.parameters?.loadName}, cannot getWellNamePerMultiTip`
+    )
+    return null
+  }
+
+  const { x, y } = topWell
+  let offsetYTipPositions: number[] = range(0, 8).map(
+    tipNo => y - tipNo * OFFSET_8_CHANNEL
+  )
+  const orderedWells = orderWells(labwareDef.ordering, 't2b', 'l2r')
+
+  if (getLabwareHasQuirk(labwareDef, 'centerMultichannelOnWells')) {
+    // move multichannel up in Y by half the pipette's tip span to center it in the well
+    offsetYTipPositions = offsetYTipPositions.map(
+      tipPosY => tipPosY + MULTICHANNEL_TIP_SPAN / 2
+    )
+  }
+  // Return null for containers with any undefined wells
+  const wellsAccessed = offsetYTipPositions.reduce(
+    (acc: string[] | null, tipPosY) => {
+      const wellForTip = findWellAt(labwareDef, x, tipPosY)
+      if (acc === null || !wellForTip) {
+        return null
+      }
+      return acc.concat(wellForTip)
+    },
+    []
+  )
+
+  let ninetySixChannelWells = orderedWells
+  //  special casing 384 well plates to be every other well
+  //  both on the x and y ases.
+  if (orderedWells.length === 384) {
+    ninetySixChannelWells = get96Channel384WellPlateWells(
+      orderedWells,
+      topWellName
+    )
+  }
+
+  return channels === 8 ? wellsAccessed : ninetySixChannelWells
+}

package/js/helpers/getWellTotalVolume.ts

@@ -0,0 +1,16 @@
+import type { LabwareDefinition2 } from '../types'
+export const getWellTotalVolume = (
+  labwareDef: LabwareDefinition2,
+  wellName: string
+): number | null | undefined => {
+  const well = labwareDef.wells[wellName]
+
+  if (!well) {
+    console.warn(
+      `No well "${wellName}" found for labware ${labwareDef?.namespace}/${labwareDef?.parameters?.loadName}/${labwareDef?.version}"`
+    )
+    return null
+  }
+
+  return well.totalLiquidVolume
+}

package/js/helpers/index.ts

@@ -0,0 +1,346 @@
+import assert from 'assert'
+import uniq from 'lodash/uniq'
+
+import { OPENTRONS_LABWARE_NAMESPACE } from '../constants'
+import standardOt2DeckDef from '../../deck/definitions/4/ot2_standard.json'
+import standardFlexDeckDef from '../../deck/definitions/4/ot3_standard.json'
+import type {
+  DeckDefinition,
+  LabwareDefinition2,
+  ModuleModel,
+  RobotType,
+  ThermalAdapterName,
+} from '../types'
+
+export { getWellNamePerMultiTip } from './getWellNamePerMultiTip'
+export { getWellTotalVolume } from './getWellTotalVolume'
+export { wellIsRect } from './wellIsRect'
+export { orderWells } from './orderWells'
+export { get96Channel384WellPlateWells } from './get96Channel384WellPlateWells'
+
+export * from './parseProtocolData'
+export * from './volume'
+export * from './wellSets'
+export * from './getModuleVizDims'
+export * from './getVectorDifference'
+export * from './getVectorSum'
+export * from './getLoadedLabwareDefinitionsByUri'
+export * from './getOccludedSlotCountForModule'
+export * from './labwareInference'
+
+export const getLabwareDefIsStandard = (def: LabwareDefinition2): boolean =>
+  def?.namespace === OPENTRONS_LABWARE_NAMESPACE
+
+export const getLabwareDefURI = (def: LabwareDefinition2): string =>
+  constructLabwareDefURI(
+    def.namespace,
+    def.parameters.loadName,
+    String(def.version)
+  )
+
+export const constructLabwareDefURI = (
+  namespace: string,
+  loadName: string,
+  version: string
+): string => `${namespace}/${loadName}/${version}`
+
+// Load names of "retired" labware
+// TODO(mc, 2019-12-3): how should this correspond to LABWAREV2_DO_NOT_LIST?
+// see shared-data/js/getLabware.js
+const RETIRED_LABWARE = [
+  'geb_96_tiprack_10ul',
+  'geb_96_tiprack_1000ul',
+  'opentrons_1_trash_850ml_fixed',
+  'opentrons_10_tuberack_falcon_4x50ml_6x15ml_conical_acrylic',
+  'opentrons_24_tuberack_eppendorf_2ml_safelock_snapcap_acrylic',
+  'opentrons_24_tuberack_generic_0.75ml_snapcap_acrylic',
+  'opentrons_40_aluminumblock_eppendorf_24x2ml_safelock_snapcap_generic_16x0.2ml_pcr_strip',
+  'opentrons_96_aluminumblock_biorad_wellplate_200ul',
+  'tipone_96_tiprack_200ul',
+  'eppendorf_96_tiprack_1000ul_eptips',
+  'eppendorf_96_tiprack_10ul_eptips',
+  // Replaced by opentrons_96_wellplate_200ul_pcr_full_skirt
+  // https://opentrons.atlassian.net/browse/RLAB-230
+  'armadillo_96_wellplate_200ul_pcr_full_skirt',
+]
+
+export const getLabwareDisplayName = (
+  labwareDef: LabwareDefinition2
+): string => {
+  const { displayName } = labwareDef.metadata
+
+  if (
+    getLabwareDefIsStandard(labwareDef) &&
+    RETIRED_LABWARE.includes(labwareDef.parameters.loadName)
+  ) {
+    return `(Retired) ${displayName}`
+  }
+
+  return displayName
+}
+
+export const getTiprackVolume = (labwareDef: LabwareDefinition2): number => {
+  assert(
+    labwareDef.parameters.isTiprack,
+    `getTiprackVolume expected a tiprack labware ${getLabwareDefURI(
+      labwareDef
+    )}, but 'isTiprack' isn't true`
+  )
+  // NOTE: Ian 2019-04-16 assuming all tips are the same volume across the rack
+  const volume = labwareDef.wells.A1.totalLiquidVolume
+  assert(
+    volume >= 0,
+    `getTiprackVolume expected tip volume to be at least 0, got ${volume}`
+  )
+  return volume
+}
+
+export function getLabwareHasQuirk(
+  labwareDef: LabwareDefinition2,
+  quirk: string
+): boolean {
+  const quirks = labwareDef.parameters.quirks
+  return quirks ? quirks.includes(quirk) : false
+}
+
+export const intToAlphabetLetter = (
+  i: number,
+  lowerCase: boolean = false
+): string => String.fromCharCode((lowerCase ? 96 : 65) + i)
+// These utils are great candidates for unit tests
+export const toWellName = ({
+  rowNum,
+  colNum,
+}: {
+  rowNum: number
+  colNum: number
+}): string => String.fromCharCode(rowNum + 65) + (colNum + 1)
+
+function _parseWell(well: string): [string, number] {
+  const res = well.match(/([A-Z]+)(\d+)/)
+  const letters = res && res[1]
+  const number = res && parseInt(res[2])
+
+  if (!letters || number == null || Number.isNaN(number)) {
+    console.warn(
+      `Could not parse well ${well}. Got letters: "${
+        letters || 'void'
+      }", number: "${number || 'void'}"`
+    )
+    return ['', NaN]
+  }
+
+  return [letters, number]
+}
+
+/** A compareFunction for sorting an array of well names
+ * Goes down the columns (A1 to H1 on 96 plate)
+ * Then L to R across rows (1 to 12 on 96 plate)
+ */
+export function sortWells(a: string, b: string): number {
+  const [letterA, numberA] = _parseWell(a)
+
+  const [letterB, numberB] = _parseWell(b)
+
+  if (numberA !== numberB) {
+    return numberA > numberB ? 1 : -1
+  }
+
+  if (letterA.length !== letterB.length) {
+    // Eg 'B' vs 'AA'
+    return letterA.length > letterB.length ? 1 : -1
+  }
+
+  return letterA > letterB ? 1 : -1
+}
+
+export function splitWellsOnColumn(sortedArray: string[]): string[][] {
+  return sortedArray.reduce<string[][]>((acc, curr) => {
+    const lastColumn = acc.slice(-1)
+
+    if (lastColumn === undefined || lastColumn.length === 0) {
+      return [[curr]]
+    }
+
+    const lastEle = lastColumn[0].slice(-1)[0].slice(1)
+
+    if (Number(curr.slice(1)) > Number(lastEle)) {
+      return [...acc, [curr]]
+    } else {
+      return [...acc.slice(0, -1), [...lastColumn[0], curr]]
+    }
+  }, [])
+}
+
+export const getWellDepth = (
+  labwareDef: LabwareDefinition2,
+  well: string
+): number => labwareDef.wells[well].depth
+
+// NOTE: this is used in PD for converting "offset from top" to "mm from bottom".
+// Assumes all wells have same offset because multi-offset not yet supported.
+// TODO: Ian 2019-07-13 return {[string: well]: offset} to support multi-offset
+export const getWellsDepth = (
+  labwareDef: LabwareDefinition2,
+  wells: string[]
+): number => {
+  const offsets = wells.map(well => getWellDepth(labwareDef, well))
+
+  if (uniq(offsets).length !== 1) {
+    console.warn(
+      `expected wells ${JSON.stringify(
+        wells
+      )} to all have same offset, but they were different. Labware def is ${getLabwareDefURI(
+        labwareDef
+      )}`
+    )
+  }
+
+  return offsets[0]
+}
+
+export const getSlotHasMatingSurfaceUnitVector = (
+  deckDef: DeckDefinition,
+  addressableAreaName: string
+): boolean => {
+  const matingSurfaceUnitVector = deckDef.locations.addressableAreas.find(
+    aa => aa.id === addressableAreaName
+  )?.matingSurfaceUnitVector
+
+  return Boolean(matingSurfaceUnitVector)
+}
+
+export const getAreSlotsHorizontallyAdjacent = (
+  slotNameA?: string | null,
+  slotNameB?: string | null
+): boolean => {
+  if (slotNameA == null || slotNameB == null) {
+    return false
+  }
+  const slotANumber = parseInt(slotNameA)
+  const slotBNumber = parseInt(slotNameB)
+  if (isNaN(slotBNumber) || isNaN(slotANumber)) {
+    return false
+  }
+  const orderedSlots = standardOt2DeckDef.locations.cutouts
+  // intentionally not substracting by 1 because trash (slot 12) should not count
+  const numSlots = orderedSlots.length
+  if (slotBNumber > numSlots || slotANumber > numSlots) {
+    return false
+  }
+  const slotWidth = orderedSlots[1].position[0] - orderedSlots[0].position[0]
+  const slotAPosition = orderedSlots[slotANumber - 1].position
+  const slotBPosition = orderedSlots[slotBNumber - 1].position
+
+  const yPositionSlotA = slotAPosition[1]
+  const yPositionSlotB = slotBPosition[1]
+
+  const xPositionSlotA = slotAPosition[0]
+  const xPositionSlotB = slotBPosition[0]
+
+  const areSlotsHorizontallyAdjacent =
+    yPositionSlotA === yPositionSlotB &&
+    Math.abs(xPositionSlotA - xPositionSlotB) === slotWidth
+
+  return areSlotsHorizontallyAdjacent
+}
+export const getAreSlotsVerticallyAdjacent = (
+  slotNameA?: string | null,
+  slotNameB?: string | null
+): boolean => {
+  if (slotNameA == null || slotNameB == null) {
+    return false
+  }
+  const slotANumber = parseInt(slotNameA)
+  const slotBNumber = parseInt(slotNameB)
+
+  if (isNaN(slotBNumber) || isNaN(slotANumber)) {
+    return false
+  }
+  const orderedSlots = standardOt2DeckDef.locations.cutouts
+  // intentionally not substracting by 1 because trash (slot 12) should not count
+  const numSlots = orderedSlots.length
+
+  if (slotBNumber > numSlots || slotANumber > numSlots) {
+    return false
+  }
+  // take the y coord of slot 4, and subtact from y coord of slot 1
+  const slotHeight = orderedSlots[3].position[1] - orderedSlots[0].position[1]
+  const slotAPosition = orderedSlots[slotANumber - 1].position
+  const slotBPosition = orderedSlots[slotBNumber - 1].position
+
+  const yPositionSlotA = slotAPosition[1]
+  const yPositionSlotB = slotBPosition[1]
+
+  const xPositionSlotA = slotAPosition[0]
+  const xPositionSlotB = slotBPosition[0]
+
+  const areSlotsVerticallyAdjacent =
+    xPositionSlotA === xPositionSlotB &&
+    Math.abs(yPositionSlotA - yPositionSlotB) === slotHeight
+
+  return areSlotsVerticallyAdjacent
+}
+//  TODO(jr, 11/12/23): rename this utility to mention that it
+//  is only used in the OT-2, same with getAreSlotsHorizontallyAdjacent
+//  and getAreSlotsVerticallyAdjacent
+export const getAreSlotsAdjacent = (
+  slotNameA?: string | null,
+  slotNameB?: string | null
+): boolean =>
+  getAreSlotsHorizontallyAdjacent(slotNameA, slotNameB) ||
+  getAreSlotsVerticallyAdjacent(slotNameA, slotNameB)
+
+export const getIsLabwareAboveHeight = (
+  labwareDef: LabwareDefinition2,
+  height: number
+): boolean => labwareDef.dimensions.zDimension > height
+
+export const getAdapterName = (labwareLoadname: string): ThermalAdapterName => {
+  let adapterName: ThermalAdapterName = 'Universal Flat Adapter'
+
+  if (
+    labwareLoadname ===
+    'opentrons_96_pcr_adapter_nest_wellplate_100ul_pcr_full_skirt'
+  ) {
+    adapterName = 'PCR Adapter'
+  } else if (
+    labwareLoadname === 'opentrons_96_deep_well_adapter_nest_wellplate_2ml_deep'
+  ) {
+    adapterName = 'Deep Well Adapter'
+  } else if (
+    labwareLoadname ===
+    'opentrons_96_flat_bottom_adapter_nest_wellplate_200ul_flat'
+  ) {
+    adapterName = '96 Flat Bottom Adapter'
+  }
+
+  return adapterName
+}
+
+export const getCalibrationAdapterLoadName = (
+  moduleModel: ModuleModel
+): string | null => {
+  switch (moduleModel) {
+    case 'heaterShakerModuleV1':
+      return 'opentrons_calibration_adapter_heatershaker_module'
+    case 'temperatureModuleV2':
+      return 'opentrons_calibration_adapter_temperature_module'
+    case 'thermocyclerModuleV2':
+      return 'opentrons_calibration_adapter_thermocycler_module'
+    default:
+      console.error(
+        `${moduleModel} does not have an associated calibration adapter`
+      )
+      return null
+  }
+}
+
+export const getDeckDefFromRobotType = (
+  robotType: RobotType
+): DeckDefinition => {
+  // @ts-expect-error imported JSON not playing nice with TS. see https://github.com/microsoft/TypeScript/issues/32063
+  return robotType === 'OT-3 Standard'
+    ? standardFlexDeckDef
+    : standardOt2DeckDef
+}

package/js/helpers/labwareInference.ts

@@ -0,0 +1,92 @@
+import isEqual from 'lodash/isEqual'
+import uniqWith from 'lodash/uniqWith'
+import round from 'lodash/round'
+import sortedUniq from 'lodash/sortedUniq'
+import uniq from 'lodash/uniq'
+import type {
+  LabwareWell,
+  LabwareWellShapeProperties,
+  LabwareDefinition2,
+  LabwareWellGroupMetadata,
+  LabwareBrand,
+} from '../types'
+
+export interface LabwareWellGroupProperties {
+  xOffsetFromLeft: number
+  yOffsetFromTop: number
+  xSpacing: number | null
+  ySpacing: number | null
+  wellCount: number
+  shape: LabwareWellShapeProperties | null
+  depth: number | null
+  totalLiquidVolume: number | null
+  metadata: LabwareWellGroupMetadata
+  brand: LabwareBrand | null
+}
+const ROUNDING_PRECISION = 2
+
+export function getUniqueWellProperties(
+  definition: LabwareDefinition2
+): LabwareWellGroupProperties[] {
+  const { groups, wells, dimensions } = definition
+
+  return groups.map(group => {
+    const wellProps = group.wells.map(n => wells[n])
+
+    const wellDepths = wellProps.map<number>(w => w.depth)
+    const wellVolumes = wellProps.map<number>(w => w.totalLiquidVolume)
+    const wellShapes = wellProps.map<LabwareWellShapeProperties>(
+      (well: LabwareWell) =>
+        well.shape === 'circular'
+          ? { shape: well.shape, diameter: well.diameter }
+          : {
+              shape: well.shape,
+              xDimension: well.xDimension,
+              yDimension: well.yDimension,
+            }
+    )
+
+    const xStart = wellProps[0]?.x ?? 0
+    const yStart = wellProps[0]?.y ?? 0
+
+    return {
+      metadata: group.metadata,
+      brand: group.brand || null,
+      xSpacing: getSpacingIfUniform(wellProps, 'x'),
+      ySpacing: getSpacingIfUniform(wellProps, 'y'),
+      xOffsetFromLeft: xStart,
+      yOffsetFromTop: round(dimensions.yDimension - yStart, ROUNDING_PRECISION),
+      wellCount: wellProps.length,
+      depth: getIfConsistent(wellDepths),
+      totalLiquidVolume: getIfConsistent(wellVolumes),
+      shape: getIfConsistent(wellShapes),
+    }
+  })
+}
+
+export function getIfConsistent<T>(items: T[]): T | null {
+  return uniqWith(items, isEqual).length === 1 ? items[0] : null
+}
+
+// returning null means "spacing is irregular"; returning 0 means "there is only 1 well along the given axis"
+export function getSpacingIfUniform(
+  wells: LabwareWell[],
+  axis: 'x' | 'y'
+): number | null {
+  const wellPositions = sortedUniq(uniq(wells.map(well => well[axis])))
+  if (wellPositions.length < 2) return 0
+
+  const initialSpacing = round(
+    wellPositions[1] - wellPositions[0],
+    ROUNDING_PRECISION
+  )
+
+  for (let i = 2; i < wellPositions.length; i++) {
+    const pos = wellPositions[i]
+    const prevWellPos = wellPositions[i - 1]
+    const spacing = round(pos - prevWellPos, ROUNDING_PRECISION)
+    if (spacing !== initialSpacing) return null
+  }
+
+  return Math.abs(initialSpacing)
+}

package/js/helpers/orderWells.ts

@@ -0,0 +1,69 @@
+import zipWith from 'lodash/zipWith'
+import uniq from 'lodash/uniq'
+import compact from 'lodash/compact'
+import flatten from 'lodash/flatten'
+
+export type WellOrderOption = 'l2r' | 'r2l' | 't2b' | 'b2t'
+
+// labware definitions in shared-data have an ordering
+// attribute which is an Array of Arrays of wells. Each inner
+// Array represents a physical column of wells on the labware
+// this function takes that 2d Array of columns and returns
+// the same wells in a 2d Array where each inner Array represents
+// a physical row of wells on the labware.
+// e.g.
+// [                      \       [
+//   ['A1', 'B1'],     === \        ['A1', 'A2']
+//   ['A2', 'B2']      === /        ['B1', 'B2']
+// ]                      /       ]
+//
+const _orderingColsToRows = (ordering: string[][]): string[][] =>
+  zipWith(...ordering, (...col) => compact(uniq(col)))
+
+// given a default "ordering" 2d array from labware definitions
+// where each inner array represents a physical column of wells
+// and well order option selections (e.g. 'l2r', 'r2l', 't2b', 'b2t')
+// this function returns a 1d array of wells from the labware
+// ordered by the given traversal technique
+export const orderWells = (
+  defaultOrdering: string[][],
+  first: WellOrderOption,
+  second: WellOrderOption
+): string[] => {
+  let orderedWells: string[][] = []
+
+  if (first === 't2b') {
+    if (second === 'l2r') {
+      orderedWells = defaultOrdering
+    } else if (second === 'r2l') {
+      orderedWells = defaultOrdering.slice().reverse()
+    }
+  } else if (first === 'b2t') {
+    if (second === 'l2r') {
+      orderedWells = defaultOrdering.map(col => col.slice().reverse())
+    } else if (second === 'r2l') {
+      orderedWells = defaultOrdering
+        .slice()
+        .reverse()
+        .map(col => col.slice().reverse())
+    }
+  } else if (first === 'l2r') {
+    if (second === 't2b') {
+      orderedWells = _orderingColsToRows(defaultOrdering)
+    } else if (second === 'b2t') {
+      orderedWells = _orderingColsToRows(defaultOrdering).slice().reverse()
+    }
+  } else if (first === 'r2l') {
+    if (second === 't2b') {
+      orderedWells = _orderingColsToRows(defaultOrdering).map(col =>
+        col.slice().reverse()
+      )
+    } else if (second === 'b2t') {
+      orderedWells = _orderingColsToRows(defaultOrdering)
+        .slice()
+        .reverse()
+        .map(col => col.slice().reverse())
+    }
+  }
+  return flatten(orderedWells)
+}