Naming of Primitives

[mszulcz-mitre]

From the Python source files in labop/labop/lib/, it seems like some Primitives have names that are verb phrases (e.g. PickColonies, Dilute, Incubate, HoldOnIce) and some have names that are noun phrases (e.g. SerialDilution, PlateCoordinates, Rows). To me, the classes named with verb phrases are more clear and easier to use since I think of a primitive step in a protocol as an action. The classes named with noun phrases, however, are sometimes not clear how to use, and as a result, I end up re-reading their descriptions in labop/labop/lib/ to understand what action they represent. For example, the Primitive PlateCoordinates represents the action Select only the samples with specified row/column combination from a sample collection.

For me, it would clarify how to use Primitives if they were named with verb phrases when possible. For example, PlateCoordinates could be named SelectSamplesByPlateCoordinates. Maybe it's a bit verbose, but the added clarity seems worth it. CulturePlates could become CreateCulturePlates. EmptyContainer could become AllocateEmptyContainer (this naming would also emphasize that 'Empty' is an adjective, not a verb).

[danbryce]

I agree that verbs tend to make more sense. This may be an artifact of how we started with Autoprotocol primitives and augmented them with additional primitives that we needed. I think that majority of primitives corresponding to physical operations are verbs, but information-related primitives such as PlateCoordinates are not. This suggests that the standard needs a convention for naming primitives, which is certainly valid.

…

On Nov 4, 2022, at 1:16 AM, mszulcz-mitre ***@***.***> wrote: From the Python source files in labop/labop/lib/, it seems like some Primitives have names that are verb phrases (e.g. PickColonies, Dilute, Incubate, HoldOnIce) and some have names that are noun phrases (e.g. SerialDilution, PlateCoordinates, Rows). To me, the classes named with verb phrases are more clear and easier to use since I think of a primitive step in a protocol as an action. The classes named with noun phrases, however, are sometimes not clear how to use, and as a result, I end up re-reading their descriptions in labop/labop/lib/ to understand what action they represent. For example, the Primitive PlateCoordinates represents the action Select only the samples with specified row/column combination from a sample collection. For me, it would clarify how to use Primitives if they were named with verb phrases when possible. For example, PlateCoordinates could be named SelectSamplesByPlateCoordinates. Maybe it's a bit verbose, but the added clarity seems worth it. CulturePlates could become CreateCulturePlates. EmptyContainer could become AllocateEmptyContainer (this naming would also emphasize that 'Empty' is an adjective, not a verb). — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you are subscribed to this thread.

[mszulcz-mitre]

I agree that a naming convention would be useful.

You mention information-related primitives. I don't mean to beat a dead horse, but maybe you'd accept a few more comments? For me, it's difficult to reconcile information primitives with the ontology. In the ontology, paml:Primitive derives from uml:Behavior, which describes "how a state changes over time" (LabOP specification, Section 4.5). An object that records information rather than expressing an action seems to not fit that description. An information-related object seems more related to classes like paml:Material or paml:SampleCollection rather than paml:Primitive.

In the case of PlateCoordinates, for example, it seems like the relevant information object is a paml:SampleCollection, and paml:PlateCoordinates defines the action of selecting based on that input:

labop/labop/lib/sample_arrays.py

Lines 22 to 26 in 9ea0789

	p = labop.Primitive('PlateCoordinates')
	p.description = 'Select only the samples with specified row/column combination from a sample collection'
	p.add_input('source', 'http://bioprotocols.org/labop#SampleCollection')
	p.add_input('coordinates', 'http://bioprotocols.org/uml#ValueSpecification')
	p.add_output('samples', 'http://bioprotocols.org/labop#SampleCollection')

Is that correct?

[bbartley]

For me, it's difficult to reconcile information primitives with the ontology.

I agree. The "EmptyContainer" Primitive is a great example. I think that using Primitives to represent noun-like entities is a very confusing to teach and explain to new users. I think there may be some changes to the data model we might consider to avoid this anti-pattern.

[jakebeal]

I support the renamings suggested by @mszulcz-mitre

[danbryce]

Short term: rename to use verbs
Long term: Handle constructors differently. Keep operations as verbs.

[mszulcz-mitre]

As part of the renaming effort, it might also be useful to rename one of the libraries. Currently, there's a library of primitives named sample_arrays.py:

labop/labop/lib/sample_arrays.py

Lines 4 to 7 in 9ea0789

	#############################################
	# Set up the document
	doc = sbol3.Document()
	LIBRARY_NAME = 'sample_arrays'

There's also a non-primitive class named paml:SampleArray. Renaming the library might help new users avoid confusing them.

I'm not sure I have a good suggestion for a different name right now. Does anyone have any ideas? For me, the challenge is that the library seems to contain a variety of primitives that are difficult to summarize in a single word or phase. For example, while most of its primitives have a paml:SampleCollection or paml:SampleArray as an input or output, they do different things with them: some create them, some allocate them, and some select them. There's also a few primitives that don't have a paml:SampleCollection or paml:SampleArray as an input or output:

labop/labop/lib/sample_arrays.py

Lines 114 to 124 in 9ea0789

	p = labop.Primitive('LoadRackOnInstrument')
	p.description = 'Insert a tube rack, pipette tip rack, or microwell plate into an addressed location on a robotic platform'
	p.add_input('rack', 'http://bioprotocols.org/uml#ValueSpecification')
	p.add_input('coordinates', 'http://bioprotocols.org/uml#ValueSpecification', optional=True)
	doc.add(p)
	p = labop.Primitive('ConfigureRobot')
	p.description = 'Specify an instrument configuration consisting of optional instrument modules, such as pipettes, heat blocks, thermocyclers, etc, which are represented by Agents'
	p.add_input('instrument', 'http://www.w3.org/ns/prov#Agent')
	p.add_input('mount', 'http://bioprotocols.org/uml#ValueSpecification', optional=True)
	doc.add(p)

labop/labop/lib/sample_arrays.py

Lines 78 to 81 in 9ea0789

	p = labop.Primitive('EmbeddedImage') # This Primitive should move to a separate library
	p.add_input('image', 'http://bioprotocols.org/uml#ValueSpecification')
	p.add_input('caption', 'http://bioprotocols.org/uml#ValueSpecification')
	doc.add(p)

The code for EmbeddedImage notes that it should be moved to a different library. Maybe I'm not seeing the unifying idea for the library, but does it make sense to consider separating more of the primitives until there's sufficient similarities that a good name becomes obvious?

[saisam17]

Is there an alphabetized or ordered list of all the primitives in a notebook somewhere with notes on the parameters? I want to implement some sort and search functions for the lay researcher to understand the parameters. It would be helpful to see all of the primitives (A-Z) if they are specified someplace.