Standardised PLR Command Prefix Proposal

dev discussion
1

Hi everyone,

We do not have intuitive nor consistent command names in PLR which can be quite confusing and can waste time to figure out the correct command.

e.g. “get_” and “request_” are both not clearly defined and distinguished in the PLR ecosystem, and currently used quite interchangeably.

With the naming convention of the Plate definition in the Resource Management System (RMS) we’ve seen how beneficial informative, intuitive and consistent nomenclature can be.

I propose we implement a similar - but much simpler - nomenclature for “commands” in PLR:

Instead of a precise naming for every command - that would be silly - I propose usage of standardised, well-defined command prefixes:

Command Types
├── 1. Physical Machine Commands
│   ├── 1.1 ACTION      → move_, aspirate_, dispense_, pickup_, shake_
│   ├── 1.2 MEASUREMENT → read_
│   ├── 1.3 MEM-READ    → get_
│   └── 1.4 MEM-WRITE   → set_
└── 2. RMS / Resource Modeling Commands
    ├── 2.1 QUERY       → query_, filter_
    └── 2.2 UPDATE      → update_, assign_, unassign_

Major aim: create an intuitive link between what a command’s name is and what it will do in the physical OR the modelling world

I am aware that (1) finding common ground might be difficult based on individuals’ personal nomenclature preferences, and (2) implementation could be a long process for pre-existing functions, but could start to be implemented immediately for everything new coming into PLR.

Request: Please let me know what you think about this proposal in general and the first draft of what this might look like in practice (above).

Let’s use this thread to brainstorm feasibility and cost-benefit-ratio. :gem_stone:

2 Likes
2

as I told you in the past, this is very important for plr goals “one unified interface” and “standardization” so thanks for making the forum post

this is good for plate reading / spectrophotometry, but not as natural for other measurements

  • “get_weight”
  • “image”

read_weight could work, or measure_weight (to avoid get, which is reasonable)

curious what you think here

I like this for memory operations. I think we can apply them to both

  1. reading PLR memory, get_resource
  2. reading information from machines get_num_channels (async)

although there is an argument to name the second case request since we (PLR) are requesting something from the machine instead of “getting” something that’s already in PLR. I am leaning towards request_ for reading information from machines (that do not perform actions on machines), but not strongly.

we should stick closely to established words in functional programming / database querying imo, so that’s good. not sure how many actions we will have per “query_” and “filter_” though

2 Likes
3

just a PR renaming methods, adding a bunch of deprecation warnings probably, but good to get in before we have a version IMO because it’s quite disruptive in the transition but then super nice and stable after the update

2 Likes
4

I agree and really like this: get_ and request_ should have a clear distinction which this would give.

New version to discuss:

Command Types
├── 1. Physical Machine Commands
│   ├── 1.1 ACTION      → move_, aspirate_, dispense_, pickup_, shake_
│   ├── 1.2 MEASUREMENT → read_, capture_
│   ├── 1.3 MEM-READ    → request_
│   └── 1.4 MEM-WRITE   → set_
└── 2. RMS / Resource Modeling Commands
    ├── 2.1 QUERY       → get_
    └── 2.2 UPDATE      → update_, assign_, unassign_

I also think that “read_weight” works, and do agree that it does not work for images.
Images are ubiquitous though and need to be addressed: I can see in the Cytation backend it is called capture_ - which is intuitive to me and I added in the above proposal v2 as the second “measurement command” prefix.

I agree, I liked “query_” and “filter_” because they seem intuitive to me but ultimately sticking with “get_” and using maybe a filter argument as an argument for some get_<> functions is the way to go?

I use them a lot, e.g. (with updated name):

in addition to the usual culprits like lh.deck.get_resource() and lh.deck.get_location_wrt(), some convenience methods like…

def get_all_plates(deck: Deck, exclusion_filer: List = []):
  return [
    r for r in deck.get_all_children()
    if r.category == "plate" and all([excl_str not in r.name for excl_str in exclusion_filer])
  ]
1 Like