@opentrons/shared-data 0.0.1-alpha.20 → 0.1.0-alpha.0

package/js/helpers/parseProtocolData.ts

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

@@ -1,35 +0,0 @@
-// 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

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

@@ -1,155 +0,0 @@
-// 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

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

@@ -1,3 +0,0 @@
-// 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

@@ -1,3 +0,0 @@
-// 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

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

@@ -1,226 +0,0 @@
-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()
-  })
-})