@opentrons/shared-data 0.1.2-alpha.0 → 0.1.2-alpha.1

package/js/helpers/wellSets.ts

@@ -0,0 +1,155 @@
+// A "well set" is an array of wells corresponding to each tip of an 8 channel pipette.
+// Eg ['A1', 'C1', 'E1', 'G1', 'I1', 'K1', 'M1', 'O1'] is a well set in a 384 plate.
+//
+// A trough-like well that encompasses all 8 tips at once has a well set
+//  ['A1', 'A1', 'A1', 'A1', 'A1', 'A1', 'A1', 'A1']
+//
+// Well sets are determined by geometry.
+//
+// Labware with multiple positions for an 8-channel pipette have multiple well sets.
+// For example, a 96 plate has 12 well sets, one for each column.
+// A 384 plate has 48 well sets, 2 for each column b/c it has staggered columns.
+//
+// If a labware has no possible well sets, then it is not compatible with multi-channel pipettes.
+import uniq from 'lodash/uniq'
+
+import { getWellNamePerMultiTip } from './getWellNamePerMultiTip'
+import { get96Channel384WellPlateWells, getLabwareDefURI, orderWells } from '.'
+import type { LabwareDefinition2, PipetteNameSpecs } from '../types'
+
+type WellSetByPrimaryWell = string[][]
+
+// Compute all well sets for a labware def (non-memoized)
+function _getAllWellSetsForLabware(
+  labwareDef: LabwareDefinition2
+): WellSetByPrimaryWell {
+  const allWells: string[] = Object.keys(labwareDef.wells)
+
+  return allWells.reduce(
+    (acc: WellSetByPrimaryWell, well: string): WellSetByPrimaryWell => {
+      const wellSet = getWellNamePerMultiTip(labwareDef, well, 8)
+      if (wellSet === null) {
+        return acc
+      } else {
+        return [...acc, wellSet]
+      }
+    },
+    []
+  )
+}
+
+// creates memoized getAllWellSetsForLabware + getWellSetForMultichannel fns.
+export interface WellSetHelpers {
+  getAllWellSetsForLabware: (
+    labwareDef: LabwareDefinition2
+  ) => WellSetByPrimaryWell
+
+  getWellSetForMultichannel: (
+    labwareDef: LabwareDefinition2,
+    well: string,
+    channels: 8 | 96
+  ) => string[] | null | undefined
+
+  canPipetteUseLabware: (
+    pipetteSpec: PipetteNameSpecs,
+    labwareDef?: LabwareDefinition2,
+    trashName?: string
+  ) => boolean
+}
+
+export const makeWellSetHelpers = (): WellSetHelpers => {
+  const cache: Partial<{
+    [labwareDefURI: string]: {
+      labwareDef: LabwareDefinition2
+      wellSetByPrimaryWell: WellSetByPrimaryWell
+    } | null
+  }> = {}
+
+  const getAllWellSetsForLabware = (
+    labwareDef: LabwareDefinition2
+  ): WellSetByPrimaryWell => {
+    const labwareDefURI = getLabwareDefURI(labwareDef)
+    const c = cache[labwareDefURI]
+
+    // use cached version only if labwareDef is shallowly equal, in case
+    // custom labware defs are changed without giving them a new URI
+    if (c && c.labwareDef === labwareDef) {
+      return c.wellSetByPrimaryWell
+    }
+
+    const wellSetByPrimaryWell = _getAllWellSetsForLabware(labwareDef)
+
+    cache[labwareDefURI] = {
+      labwareDef,
+      wellSetByPrimaryWell,
+    }
+    return wellSetByPrimaryWell
+  }
+
+  const getWellSetForMultichannel = (
+    labwareDef: LabwareDefinition2,
+    well: string,
+    channels: 8 | 96
+  ): string[] | null | undefined => {
+    /** Given a well for a labware, returns the well set it belongs to (or null)
+     * for 8-channel access.
+     * Ie: C2 for 96-flat => ['A2', 'B2', 'C2', ... 'H2']
+     * Or A1 for trough => ['A1', 'A1', 'A1', ...]
+     **/
+    const allWellSetsFor8Channel = getAllWellSetsForLabware(labwareDef)
+    /**  getting all wells from the plate and turning into 1D array for 96-channel
+     */
+    const orderedWellsFor96Channel = orderWells(
+      labwareDef.ordering,
+      't2b',
+      'l2r'
+    )
+
+    let ninetySixChannelWells = orderedWellsFor96Channel
+    /**  special casing 384 well plates to be every other well
+     * both on the x and y ases.
+     */
+    if (orderedWellsFor96Channel.length === 384) {
+      ninetySixChannelWells = get96Channel384WellPlateWells(
+        orderedWellsFor96Channel,
+        well
+      )
+    }
+    return channels === 8
+      ? allWellSetsFor8Channel.find((wellSet: string[]) =>
+          wellSet.includes(well)
+        )
+      : ninetySixChannelWells
+  }
+
+  const canPipetteUseLabware = (
+    pipetteSpec: PipetteNameSpecs,
+    labwareDef?: LabwareDefinition2,
+    trashName?: string
+  ): boolean => {
+    if (pipetteSpec.channels === 1 || trashName != null) {
+      // assume all labware can be used by single-channel
+      return true
+    }
+    if (labwareDef != null) {
+      const allWellSets = getAllWellSetsForLabware(labwareDef)
+      return allWellSets.some(wellSet => {
+        const uniqueWells = uniq(wellSet)
+        // if all wells are non-null, and there are either 1 (reservoir-like)
+        // or 8 (well plate-like) unique wells in the set,
+        // then assume both 8 and 96 channel pipettes will work
+        return (
+          uniqueWells.every(well => well != null) &&
+          [1, 8].includes(uniqueWells.length)
+        )
+      })
+    } else {
+      return false
+    }
+  }
+  return {
+    getAllWellSetsForLabware,
+    getWellSetForMultichannel,
+    canPipetteUseLabware,
+  }
+}

package/js/index.ts

@@ -0,0 +1,14 @@
+export * from './constants'
+export * from './getLabware'
+export * from './helpers'
+export * from './pipettes'
+export * from './types'
+export * from './labwareTools'
+export * from './modules'
+export * from './fixtures'
+export * from './gripper'
+export * from '../protocol'
+export * from '../deck'
+export * from './titleCase'
+export * from './errors'
+export * from './fixtures'

package/js/labwareTools/__tests__/__snapshots__/createIrregularLabware.test.ts.snap

@@ -0,0 +1,3 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`test createIrregularLabware function failing to validate against labware schema throws w/o "strict" 1`] = `"Generated labware failed to validate, please check your inputs"`;

package/js/labwareTools/__tests__/__snapshots__/createLabware.test.ts.snap

@@ -0,0 +1,3 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`createLabware failing to validate against labware schema throws w/o "strict" 1`] = `"Generated labware failed to validate, please check your inputs"`;

package/js/labwareTools/__tests__/createDefaultDisplayName.test.ts

@@ -0,0 +1,111 @@
+import { createDefaultDisplayName } from '..'
+
+import type { RegularNameProps } from '..'
+
+interface TestCase {
+  testName: string
+  args: RegularNameProps
+  expected: string
+}
+
+describe('createDefaultDisplayName', () => {
+  const testCases: TestCase[] = [
+    {
+      testName: 'handle the minimal case',
+      args: {
+        displayCategory: 'wellPlate',
+        displayVolumeUnits: 'µL',
+        gridRows: 2,
+        gridColumns: 3,
+        totalLiquidVolume: 123,
+      },
+      expected: 'Generic 6 Well Plate 123 µL',
+    },
+    {
+      testName: 'handle a decimal in volume',
+      args: {
+        displayCategory: 'wellPlate',
+        displayVolumeUnits: 'µL',
+        gridRows: 2,
+        gridColumns: 3,
+        totalLiquidVolume: 12.3,
+      },
+      expected: 'Generic 6 Well Plate 12.3 µL',
+    },
+    {
+      testName: 'calculate wells = rows x cols',
+      args: {
+        displayCategory: 'wellPlate',
+        displayVolumeUnits: 'µL',
+        gridRows: 8,
+        gridColumns: 10,
+        totalLiquidVolume: 123,
+      },
+      expected: 'Generic 80 Well Plate 123 µL',
+    },
+    {
+      testName: 'handle tube rack (example of a different displayCategory)',
+      args: {
+        displayCategory: 'tubeRack',
+        displayVolumeUnits: 'µL',
+        gridRows: 2,
+        gridColumns: 3,
+        totalLiquidVolume: 123,
+      },
+      expected: 'Generic 6 Tube Rack 123 µL',
+    },
+    {
+      testName: 'append loadNamePostfix',
+      args: {
+        displayCategory: 'wellPlate',
+        displayVolumeUnits: 'µL',
+        gridRows: 2,
+        gridColumns: 3,
+        totalLiquidVolume: 123,
+        loadNamePostfix: ['spam  ', ' blah', 'PCR'],
+      },
+      expected: 'Generic 6 Well Plate 123 µL Spam Blah PCR',
+    },
+    {
+      testName: 'support brand name when specified (ignore extra whitespace)',
+      args: {
+        displayCategory: 'wellPlate',
+        displayVolumeUnits: 'µL',
+        gridRows: 2,
+        gridColumns: 3,
+        totalLiquidVolume: 123,
+        brandName: ' cool  brand ',
+      },
+      expected: 'Cool Brand 6 Well Plate 123 µL',
+    },
+    {
+      testName: 'support brand name when specified (capitalization)',
+      args: {
+        displayCategory: 'wellPlate',
+        displayVolumeUnits: 'µL',
+        gridRows: 2,
+        gridColumns: 3,
+        totalLiquidVolume: 123,
+        brandName: ' BIO tech',
+      },
+      expected: 'BIO Tech 6 Well Plate 123 µL',
+    },
+    {
+      testName: 'support mL when specified (volume number always in µL!)',
+      args: {
+        displayCategory: 'wellPlate',
+        displayVolumeUnits: 'mL',
+        gridRows: 2,
+        gridColumns: 3,
+        totalLiquidVolume: 123,
+      },
+      expected: 'Generic 6 Well Plate 0.123 mL',
+    },
+  ]
+
+  testCases.forEach(({ testName, args, expected }) => {
+    it(`should ${testName}`, () => {
+      expect(createDefaultDisplayName(args)).toEqual(expected)
+    })
+  })
+})

package/js/labwareTools/__tests__/createIrregularLabware.test.ts

@@ -0,0 +1,226 @@
+import omit from 'lodash/omit'
+import range from 'lodash/range'
+
+import { splitWellsOnColumn, sortWells } from '../../helpers/index'
+import fixture_irregular_example_1 from '../../../labware/fixtures/2/fixture_irregular_example_1.json'
+
+import {
+  createIrregularLabware,
+  _irregularWellName,
+  _generateIrregularLoadName,
+  _calculateWellCoord,
+} from '..'
+
+import type { LabwareDefinition2, LabwareWellProperties } from '../../types'
+import type { IrregularLabwareProps } from '..'
+
+// NOTE: loadName needs to be replaced here b/c fixture has a non-default loadName
+const exampleLabware1 = {
+  ...fixture_irregular_example_1,
+  parameters: {
+    ...fixture_irregular_example_1.parameters,
+    loadName: 'generic_55_tuberack_50x3ml_5x10ml',
+  },
+} as LabwareDefinition2
+
+describe('test helper functions', () => {
+  it('Well name generated correctly', () => {
+    const grid = { row: 2, column: 2 }
+
+    const gridStart = [
+      { rowStart: 'A', colStart: '1', rowStride: 1, colStride: 2 },
+      { rowStart: 'B', colStart: '1', rowStride: 3, colStride: 1 },
+    ]
+    const expected1 = ['A1', 'B1', 'A3', 'B3']
+    const expected2 = ['B1', 'E1', 'B2', 'E2']
+
+    range(grid.column).forEach(colIdx => {
+      range(grid.row).forEach(rowIdx => {
+        const idx = colIdx * grid.row + rowIdx
+
+        const wellName1 = _irregularWellName(rowIdx, colIdx, gridStart[0])
+
+        expect(expected1[idx]).toEqual(wellName1)
+
+        const wellName2 = _irregularWellName(rowIdx, colIdx, gridStart[1])
+
+        expect(expected2[idx]).toEqual(wellName2)
+      })
+    })
+  })
+
+  it('XYZ generates correctly for each grid', () => {
+    const grid = { row: 1, column: 5 }
+    const offset = { x: 1, y: 0.5, z: 55.5 }
+    const spacing = [
+      { row: 10, column: 10 },
+      { row: 5, column: 14 },
+    ]
+    const well = [
+      omit(exampleLabware1.wells.A1, ['x', 'y', 'z']),
+      omit(exampleLabware1.wells.B1, ['x', 'y', 'z']),
+    ] as LabwareWellProperties[]
+
+    const expectedX1 = [1, 11, 21, 31, 41]
+    const expectedY1 = [0.5]
+    const expectedX2 = [1, 15, 29, 43, 57]
+    const expectedY2 = [0.5]
+
+    range(grid.column).forEach(colIdx => {
+      range(grid.row).forEach(rowIdx => {
+        const well1 = _calculateWellCoord(
+          rowIdx,
+          colIdx,
+          spacing[0],
+          offset,
+          well[0]
+        )
+
+        expect(well1.x).toBeCloseTo(expectedX1[colIdx], 2)
+        expect(well1.y).toBeCloseTo(expectedY1[rowIdx], 2)
+        expect(well1.z).toBeCloseTo(offset.z - well[0].depth, 2)
+
+        const well2 = _calculateWellCoord(
+          rowIdx,
+          colIdx,
+          spacing[1],
+          offset,
+          well[1]
+        )
+
+        expect(well2.x).toBeCloseTo(expectedX2[colIdx], 2)
+        expect(well2.y).toBeCloseTo(expectedY2[rowIdx], 2)
+        expect(well2.z).toBeCloseTo(offset.z - well[1].depth, 2)
+      })
+    })
+  })
+})
+
+describe('test createIrregularLabware function', () => {
+  let labware1: LabwareDefinition2
+  let labware1Args: IrregularLabwareProps
+
+  beforeEach(() => {
+    labware1Args = {
+      namespace: 'fixture',
+      metadata: {
+        displayName: 'Fake Irregular Container',
+        displayCategory: 'tubeRack',
+        displayVolumeUnits: 'mL',
+        tags: ['fake', 'opentrons'],
+      },
+      parameters: {
+        format: 'irregular',
+        isTiprack: false,
+        isMagneticModuleCompatible: false,
+      },
+      dimensions: {
+        xDimension: 127.76,
+        yDimension: 85.48,
+        zDimension: 64.48,
+      },
+      well: [
+        {
+          depth: 10.54,
+          shape: 'circular',
+          diameter: 10,
+          totalLiquidVolume: 3000,
+        },
+        {
+          depth: 20.54,
+          shape: 'circular',
+          diameter: 15,
+          totalLiquidVolume: 10000,
+        },
+      ],
+      offset: [
+        { x: 10, y: 10, z: 69.48 },
+        { x: 15, y: 15, z: 69.48 },
+      ],
+      grid: [
+        { row: 5, column: 10 },
+        { row: 1, column: 5 },
+      ],
+      spacing: [
+        { row: 5, column: 10 },
+        { row: 5, column: 10 },
+      ],
+      gridStart: [
+        { rowStart: 'A', colStart: '1', rowStride: 2, colStride: 1 },
+        { rowStart: 'B', colStart: '1', rowStride: 1, colStride: 1 },
+      ],
+    }
+    labware1 = createIrregularLabware(labware1Args)
+  })
+
+  it('irregular ordering generates as expected', () => {
+    const keyList = Object.keys(labware1.wells)
+    const generatedOrdering = splitWellsOnColumn(keyList.sort(sortWells))
+    expect(labware1.ordering).toEqual(generatedOrdering)
+  })
+
+  it('check labware matches fixture', () => {
+    expect(labware1).toEqual(exampleLabware1)
+  })
+
+  it('labware loadName generated correctly for multi-grid labware', () => {
+    const loadName = _generateIrregularLoadName({
+      grid: [
+        { row: 3, column: 2 },
+        { row: 1, column: 4 },
+      ],
+      well: [
+        {
+          depth: 20,
+          shape: 'circular',
+          totalLiquidVolume: 400,
+        } as LabwareWellProperties,
+        {
+          depth: 110,
+          shape: 'circular',
+          totalLiquidVolume: 2000,
+        } as LabwareWellProperties,
+      ],
+      totalWellCount: 10,
+      units: 'µL',
+      displayCategory: 'wellPlate',
+      brand: 'some brand',
+    })
+
+    expect(loadName).toEqual('somebrand_10_wellplate_6x400ul_4x2000ul')
+  })
+
+  it('labware loadName generated correctly for multi-grid labware in other units', () => {
+    const loadName = _generateIrregularLoadName({
+      grid: [{ row: 3, column: 2 }],
+      well: [
+        {
+          depth: 20,
+          shape: 'circular',
+          totalLiquidVolume: 4000,
+        } as LabwareWellProperties,
+      ],
+      totalWellCount: 6,
+      units: 'mL',
+      displayCategory: 'wellPlate',
+      brand: 'some brand',
+    })
+
+    expect(loadName).toEqual('somebrand_6_wellplate_6x4ml')
+  })
+
+  it('failing to validate against labware schema throws w/o "strict"', () => {
+    const args = {
+      ...labware1Args,
+      // negative y offset should fail schema validation by making well `y` negative
+      offset: [
+        { x: 10, y: -9999, z: 69.48 },
+        { x: 15, y: -9999, z: 69.48 },
+      ],
+    }
+    expect(() => createIrregularLabware(args)).toThrowErrorMatchingSnapshot()
+    expect(() =>
+      createIrregularLabware({ ...args, strict: false })
+    ).not.toThrow()
+  })
+})

package/js/labwareTools/__tests__/createLabware.test.ts

@@ -0,0 +1,147 @@
+import omit from 'lodash/omit'
+import range from 'lodash/range'
+import { createRegularLabware } from '..'
+import fixture_regular_example_1 from '../../../labware/fixtures/2/fixture_regular_example_1.json'
+import fixture_regular_example_2 from '../../../labware/fixtures/2/fixture_regular_example_2.json'
+
+import type {
+  LabwareDefinition2,
+  LabwareWellProperties,
+  LabwareOffset,
+} from '../../types'
+
+import type { RegularLabwareProps } from '..'
+
+// NOTE: loadName needs to be replaced here b/c fixture has a non-default loadName
+const exampleLabware1 = {
+  ...fixture_regular_example_1,
+  parameters: {
+    ...fixture_regular_example_1.parameters,
+    loadName: 'opentrons_2_wellplate_100ul',
+  },
+} as LabwareDefinition2
+
+const exampleLabware2 = {
+  ...fixture_regular_example_2,
+  parameters: {
+    ...fixture_regular_example_2.parameters,
+    loadName: 'generic_6_wellplate_1ml',
+  },
+} as LabwareDefinition2
+
+describe('createLabware', () => {
+  let labware1: LabwareDefinition2
+  let labware2: LabwareDefinition2
+  let labware2Args: RegularLabwareProps
+  let well1: LabwareWellProperties
+  let well2: LabwareWellProperties
+  let offset1: LabwareOffset
+  let offset2: LabwareOffset
+
+  beforeEach(() => {
+    well1 = omit(exampleLabware1.wells.A1, [
+      'x',
+      'y',
+      'z',
+    ]) as LabwareWellProperties
+
+    well2 = omit(exampleLabware2.wells.A1, [
+      'x',
+      'y',
+      'z',
+    ]) as LabwareWellProperties
+
+    offset1 = { x: 10, y: 10, z: 55 }
+    offset2 = { x: 10, y: 10, z: 40 }
+
+    labware1 = createRegularLabware({
+      metadata: exampleLabware1.metadata,
+      parameters: exampleLabware1.parameters,
+      dimensions: exampleLabware1.dimensions,
+      offset: offset1,
+      grid: { row: 1, column: 2 },
+      spacing: { row: 10, column: 10 },
+      well: well1,
+      brand: exampleLabware1.brand,
+      namespace: 'fixture',
+    })
+    labware2Args = {
+      metadata: exampleLabware2.metadata,
+      parameters: exampleLabware2.parameters,
+      dimensions: exampleLabware2.dimensions,
+      offset: offset2,
+      grid: {
+        row: 3,
+        column: 2,
+      },
+      spacing: {
+        row: 10,
+        column: 10,
+      },
+      well: well2,
+      namespace: 'fixture',
+    }
+    labware2 = createRegularLabware(labware2Args)
+  })
+
+  it('snapshot tests', () => {
+    expect(labware1).toEqual(exampleLabware1)
+    expect(labware2).toEqual(exampleLabware2)
+  })
+
+  it('ordering generates as expected', () => {
+    expect(exampleLabware2.ordering).toEqual(labware2.ordering)
+  })
+
+  it('well XYZ generates correctly', () => {
+    const spacing = { row: 10, column: 10 }
+    const grid = { row: 3, column: 2 }
+    const { yDimension } = exampleLabware2.dimensions
+
+    const labware3 = createRegularLabware({
+      metadata: exampleLabware2.metadata,
+      parameters: exampleLabware2.parameters,
+      dimensions: exampleLabware2.dimensions,
+      offset: offset2,
+      grid,
+      spacing,
+      well: well2,
+    })
+
+    const expectedXByCol = range(
+      offset2.x,
+      offset2.x + grid.column * spacing.column,
+      spacing.column
+    )
+
+    const expectedYByRow = range(
+      yDimension - offset2.y,
+      yDimension - offset2.y - spacing.row * grid.row,
+      -spacing.row
+    )
+
+    labware3.ordering.forEach((column, cIndex) => {
+      column.forEach((wellName, rIndex) => {
+        const well = labware3.wells[wellName]
+
+        expect(well.x).toBeCloseTo(expectedXByCol[cIndex], 2)
+        expect(well.y).toBeCloseTo(expectedYByRow[rIndex], 2)
+        expect(well.z).toBeCloseTo(offset2.z - well.depth, 2)
+      })
+    })
+  })
+
+  it('failing to validate against labware schema throws w/o "strict"', () => {
+    const args = {
+      ...labware2Args,
+      // this spacing should make negative well `y` value and fail schema validation
+      spacing: {
+        row: 999,
+        column: 999,
+      },
+    }
+
+    expect(() => createRegularLabware(args)).toThrowErrorMatchingSnapshot()
+    expect(() => createRegularLabware({ ...args, strict: false })).not.toThrow()
+  })
+})