refactor(api, shared-data): rename certain liquid class properties

[jbleon95]

Overview

This PR refactors some liquid class property names and organization of properties. The two major changes are fully changing mmFromEdge to mmToEdge and re-organizing positionReference and offset properties.

mmFromEdge to mmToEdge was already partially in the code in some places, so this change just fully changes it everywhere else. This name is viewed as more readable and understandable, as the property is measured from the edge's well.

The larger change was to positionReference and offset. Previously these were two properties that were flatly defined in the submerge field, the retract field and in the top level aspirate, singleDispense and multiDispense fields. This refactor changes it so that these two properties are now bound together in a new TipPosition type, and named appropriately and descriptively in each of the above fields.

For submerge these are now under submerge.start_position. For retract, it is now under retract.end_position. For aspirate it is now under aspirate.aspirate_position and for singleDispense and multiDispense it is now under fooDispense.dispense_position. All of these clearly highlight if the position reference and offset refers to the starting position, liquid handling position, or end position.

Test Plan and Hands on Testing

Unit tests and updated snapshot tests should cover the changes, and ensured the following protocol passed analysis

requirements = {
    "robotType": "Flex",
    "apiLevel": "2.23"
}

metadata = {
    "protocolName":'Liquid Class New Property names',
}

def run(protocol_context):
    tiprack = protocol_context.load_labware("opentrons_flex_96_tiprack_200ul", "C2")
    trash = protocol_context.load_trash_bin('A3')
    pipette_1k = protocol_context.load_instrument("flex_1channel_1000", "left", tip_racks=[tiprack])
    nest_plate = protocol_context.load_labware("nest_96_wellplate_2ml_deep", "D1")
    arma_plate = protocol_context.load_labware("armadillo_96_wellplate_200ul_pcr_full_skirt", "D3")

    water_class = protocol_context.define_liquid_class("water")
    transfer_properties = water_class.get_for(pipette_1k, tiprack)

    transfer_properties.aspirate.retract.touch_tip.mm_from_edge = 2
    transfer_properties.dispense.retract.touch_tip.mm_from_edge = -2
    transfer_properties.multi_dispense.retract.touch_tip.mm_from_edge = 0

    transfer_properties.aspirate.submerge.start_position.position_reference = "well-top"
    transfer_properties.aspirate.submerge.start_position.offset = (0, 0, -1)
    transfer_properties.aspirate.aspirate_position.position_reference = "well-bottom"
    transfer_properties.aspirate.aspirate_position.offset = (0, 0, 1)
    transfer_properties.aspirate.retract.end_position.position_reference = "well-top"
    transfer_properties.aspirate.retract.end_position.offset = (0, 0, 1)

    transfer_properties.dispense.submerge.start_position.position_reference = "well-top"
    transfer_properties.dispense.submerge.start_position.offset = (0, 0, -1)
    transfer_properties.dispense.dispense_position.position_reference = "well-center"
    transfer_properties.dispense.dispense_position.offset = (0, 0, 1)
    transfer_properties.dispense.retract.end_position.position_reference = "well-top"
    transfer_properties.dispense.retract.end_position.offset = (0, 0, 1)

    transfer_properties.multi_dispense.submerge.start_position.position_reference = "well-top"
    transfer_properties.multi_dispense.submerge.start_position.offset = (0, 0, -1)
    transfer_properties.multi_dispense.dispense_position.position_reference = "liquid-meniscus"
    transfer_properties.multi_dispense.dispense_position.offset = (0, 0, 1)
    transfer_properties.multi_dispense.retract.end_position.position_reference = "well-top"
    transfer_properties.multi_dispense.retract.end_position.offset = (0, 0, 1)

    pipette_1k.starting_tip = tiprack['B1']

    pipette_1k.transfer_with_liquid_class(
        liquid_class=water_class,
        volume=100,
        source=nest_plate.columns()[0][:2],
        dest=arma_plate.columns()[0][:2],
        new_tip="always",
        trash_location=trash,
    )

Changelog

• renamed more mmToEdge and mm_to_edge to mmFromEdge and mm_from_edge
• refactored positionReference and offset to be in new tipPosition type and named appropriately in transfer property fields

Review requests

Risk assessment

Lowish, doesn't change any execution code but touches a lot of areas.

[codecov]

Codecov Report

Attention: Patch coverage is 23.80952% with 32 lines in your changes missing coverage. Please review.

Project coverage is 61.53%. Comparing base (a957f28) to head (55c8e07).
Report is 27 commits behind head on edge.

Files with missing lines	Patch %	Lines
...r/src/steplist/formLevel/handleFormChange/utils.ts	0.00%	32 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##             edge   #17310       +/-   ##
===========================================
+ Coverage   25.45%   61.53%   +36.07%     
===========================================
  Files        3018     3030       +12     
  Lines      234749   237525     +2776     
  Branches    20157    21178     +1021     
===========================================
+ Hits        59767   146156    +86389     
+ Misses     174966    91190    -83776     
- Partials       16      179      +163     

Flag	Coverage Δ
protocol-designer	19.29% <0.00%> (+0.48%)	⬆️
step-generation	4.39% <0.00%> (+0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...red_data/liquid_classes/liquid_class_definition.py	96.50% <100.00%> (-0.08%)	⬇️
...r/src/steplist/formLevel/handleFormChange/utils.ts	18.86% <0.00%> (-0.31%)	⬇️

... and 1705 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[emilyburghardt]

Just adding a comment- will leave actual approval to Sanniti, etc. on the actual changes.

I think the changes to position reference - start, end, and aspirate/dispense position reference- are going to make a huge difference in user understanding. I had it worked out while just documenting this, but especially when it comes to users editing their own liquid class... will be super helpful.

[sanni-t]

This looks great! The new positioning structure gives much more clarity.
Just have some suggestions for the position descriptions.

[jerader]

nit, can you deconstruct aspiratePosition from aspirate like in line 682 and then this could be:

Suggested change

	const {
	positionReference: aspiratePositionReference,
	offset: aspirateOffset,
	} = aspirate.aspiratePosition
	const {
	positionReference: aspiratePositionReference,
	offset: aspirateOffset,
	} = aspiratePosition

its just cleaner this way to read and we prefer this :D

[jerader]

same here

[jerader]

same here