@opentrons/shared-data 0.0.0-alpha.14

package/js/helpers/parseProtocolData.ts

@@ -0,0 +1,141 @@
+import Ajv from 'ajv'
+import labwareV2Schema from '../../labware/schemas/2.json'
+import protocolSchemaV1 from '../../protocol/schemas/1.json'
+import protocolSchemaV2 from '../../protocol/schemas/2.json'
+import protocolSchemaV3 from '../../protocol/schemas/3.json'
+import protocolSchemaV4 from '../../protocol/schemas/4.json'
+import protocolSchemaV5 from '../../protocol/schemas/5.json'
+
+import type { ErrorObject } from 'ajv'
+import type { JsonProtocolFile } from '../../protocol'
+
+export type ProtocolParseErrorKey = 'INVALID_FILE_TYPE' | 'INVALID_JSON_FILE'
+
+interface ProtocolParseErrorDetails {
+  rawError?: string
+  schemaErrors?: ErrorObject[] | null
+}
+
+export type ProtocolParseErrorHandler = (
+  errorKey: ProtocolParseErrorKey,
+  errorDetails?: ProtocolParseErrorDetails
+) => unknown
+
+type ProtocolSchema =
+  | typeof protocolSchemaV1
+  | typeof protocolSchemaV2
+  | typeof protocolSchemaV3
+  | typeof protocolSchemaV4
+  | typeof protocolSchemaV5
+
+const SCHEMA_BY_VERSION: { [version: string]: ProtocolSchema } = {
+  '1': protocolSchemaV1,
+  '2': protocolSchemaV2,
+  '3': protocolSchemaV3,
+  '4': protocolSchemaV4,
+  '5': protocolSchemaV5,
+}
+
+export interface PythonProtocolMetadata {
+  source?: string
+  [key: string]: unknown
+}
+
+// data may be a full JSON protocol or just a metadata dict from Python
+export type ProtocolData =
+  | JsonProtocolFile
+  | { metadata: PythonProtocolMetadata }
+
+export function parseProtocolData(
+  file: File,
+  contents: string,
+  handleError?: ProtocolParseErrorHandler,
+  metadata?: PythonProtocolMetadata | null // optional Python protocol metadata
+): ProtocolData | null {
+  if (fileExtensionIsJson(file.name)) {
+    return validateJsonProtocolFileContents(contents, handleError)
+  } else if (fileExtensionIsPython(file.name)) {
+    // grab Python protocol metadata, if any
+    return metadata != null ? { metadata } : null
+  } else if (fileExtensionIsZip(file.name)) {
+    return null
+  }
+
+  handleError && handleError('INVALID_FILE_TYPE')
+  return null
+}
+
+export function fileExtensionIsPython(filename: string): boolean {
+  return Boolean(/\.py$/i.test(filename))
+}
+export function fileExtensionIsJson(filename: string): boolean {
+  return Boolean(/\.json$/i.test(filename))
+}
+export function fileExtensionIsZip(filename: string): boolean {
+  return Boolean(/\.zip$/i.test(filename))
+}
+export function fileIsBinary(file: File): boolean {
+  // bundles are always binary files, and currently nothing else is binary
+  return fileExtensionIsZip(file.name)
+}
+
+export function validateJsonProtocolFileContents(
+  fileContents: string,
+  handleError?: ProtocolParseErrorHandler
+): JsonProtocolFile | null {
+  try {
+    if (typeof fileContents !== 'string') {
+      handleError && handleError('INVALID_FILE_TYPE')
+      return null
+    } else {
+      const ajv = new Ajv({ allErrors: true, jsonPointers: true })
+      // protocol schema contains reference to v2 labware schema, so give AJV access to it
+      ajv.addSchema(labwareV2Schema)
+
+      const parsedProtocol = JSON.parse(fileContents) as any
+      let validateAgainstSchema
+      if ('protocol-schema' in parsedProtocol) {
+        // 'protocol-schema' key only present in V1
+        validateAgainstSchema = ajv.compile(protocolSchemaV1)
+      } else {
+        const { schemaVersion } = parsedProtocol
+        validateAgainstSchema = ajv.compile(
+          SCHEMA_BY_VERSION[String(schemaVersion)]
+        )
+      }
+
+      if (!validateAgainstSchema(parsedProtocol)) {
+        handleError &&
+          handleError('INVALID_JSON_FILE', {
+            schemaErrors: validateAgainstSchema.errors,
+          })
+        return null
+      }
+
+      return parsedProtocol
+    }
+  } catch (error) {
+    handleError && handleError('INVALID_JSON_FILE', { rawError: error })
+    return null
+  }
+}
+
+export function getProtocolDesignerApplicationName(
+  protocol: JsonProtocolFile
+): string | null {
+  if (
+    'designerApplication' in protocol &&
+    protocol.designerApplication != null
+  ) {
+    return 'name' in protocol.designerApplication &&
+      protocol.designerApplication.name != null
+      ? protocol.designerApplication.name
+      : null
+  } else if (
+    'designer-application' in protocol &&
+    protocol['designer-application']['application-name'] != null
+  ) {
+    return protocol['designer-application']['application-name']
+  }
+  return null
+}

package/js/helpers/volume.ts

@@ -0,0 +1,35 @@
+// utilities for working with volumes in µL
+import round from 'lodash/round'
+
+import type { LabwareVolumeUnits } from '../types'
+
+const SCALE_BY_UNITS = {
+  µL: 1,
+  mL: 1000,
+  L: 1000000,
+}
+
+export function getDisplayVolume(
+  volumeInMicroliters: number,
+  displayUnits: LabwareVolumeUnits = 'µL',
+  digits?: number
+): string {
+  const volume = volumeInMicroliters / SCALE_BY_UNITS[displayUnits]
+
+  return `${typeof digits === 'number' ? round(volume, digits) : volume}`
+}
+
+export function getAsciiVolumeUnits(displayUnits: LabwareVolumeUnits): string {
+  if (displayUnits === 'µL') return 'uL'
+
+  return displayUnits
+}
+
+export function ensureVolumeUnits(
+  maybeUnits: string | null | undefined
+): LabwareVolumeUnits {
+  if (maybeUnits === 'mL' || maybeUnits === 'ml') return 'mL'
+  if (maybeUnits === 'L' || maybeUnits === 'l') return 'L'
+
+  return 'µL'
+}

package/js/helpers/wellIsRect.ts

@@ -0,0 +1,6 @@
+import type { WellDefinition } from '../types'
+
+/** Well is either rect or circle. Depends on whether `diameter` exists */
+export function wellIsRect(wellDef: WellDefinition): boolean {
+  return !(typeof wellDef.diameter === 'number')
+}

package/js/helpers/wellSets.ts

@@ -0,0 +1,150 @@
+// 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
+  ) => 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
+  ): boolean => {
+    if (pipetteSpec.channels === 1) {
+      // assume all labware can be used by single-channel
+      return true
+    }
+
+    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)
+      )
+    })
+  }
+  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()
+  })
+})