Defining Parameters¶
To use parameters, you need to define them in a separate function within your protocol. Each parameter definition has two main purposes: to specify acceptable values, and to inform the protocol user what the parameter does.
Depending on the type of parameter, you’ll need to specify some or all of the following.
Attribute |
Details |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The add_parameters() Function¶
All parameter definitions are contained in a Python function, which must be named add_parameters and takes a single argument. Define add_parameters() before the run() function that contains protocol commands.
The examples on this page assume the following definition, which uses the argument name parameters. The type specification of the argument is optional.
def add_parameters(parameters: protocol_api.Parameters):
Within this function definition, call methods on parameters to define parameters. The next section demonstrates how each type of parameter has its own method.
Types of Parameters¶
The API supports four types of parameters: Boolean (bool), integer (int), floating point number (float), and string (str). It is not possible to mix types within a single parameter.
Boolean Parameters¶
Boolean parameters are True or False only.
parameters.add_bool(
variable_name="dry_run",
display_name="Dry Run",
description="Skip incubation delays and shorten mix steps.",
default=False
)
During run setup, the technician can toggle between the two values. In the Opentrons App, Boolean parameters appear as a toggle switch. On the touchscreen, they appear as On or Off, for True and False respectively.
New in version 2.18.
Integer Parameters¶
Integer parameters either accept a range of numbers or a list of numbers. You must specify one or the other; you can’t create an open-ended prompt that accepts any integer.
To specify a range, include minimum and maximum.
parameters.add_int(
variable_name="volume",
display_name="Aspirate volume",
description="How much to aspirate from each sample.",
default=20,
minimum=10,
maximum=100,
unit="µL"
)
During run setup, the technician can enter any integer value from the minimum up to the maximum. Entering a value outside of the range will show an error. At that point, they can correct their custom value or restore the default value.
To specify a list of numbers, include choices. Each choice is a dictionary with entries for display name and value. The display names let you briefly explain the effect each choice will have.
parameters.add_int(
variable_name="volume",
display_name="Aspirate volume",
description="How much to aspirate from each sample.",
default=20,
choices=[
{"display_name": "Low (10 µL)", "value": 10},
{"display_name": "Medium (20 µL)", "value": 20},
{"display_name": "High (50 µL)", "value": 50},
]
)
During run setup, the technician can choose from a menu of the provided choices.
New in version 2.18.
Float Parameters¶
Float parameters either accept a range of numbers or a list of numbers. You must specify one or the other; you can’t create an open-ended prompt that accepts any floating point number.
Specifying a range or list is done exactly the same as in the integer examples above. The only difference is that all values must be floating point numbers.
parameters.add_float(
variable_name="volume",
display_name="Aspirate volume",
description="How much to aspirate from each sample.",
default=5.0,
choices=[
{"display_name": "Low (2.5 µL)", "value": 2.5},
{"display_name": "Medium (5 µL)", "value": 5.0},
{"display_name": "High (10 µL)", "value": 10.0},
]
)
New in version 2.18.
String Parameters¶
String parameters only accept a list of values. You can’t currently prompt for free text entry of a string value.
To specify a list of strings, include choices. Each choice is a dictionary with entries for display name and value. Only the display name will appear during run setup.
A common use for string display names is to provide an easy-to-read version of an API load name. You can also use them to briefly explain the effect each choice will have.
parameters.add_str(
variable_name="pipette",
display_name="Pipette type",
choices=[
{"display_name": "1-Channel 50 µL", "value": "flex_1channel_50"},
{"display_name": "8-Channel 50 µL", "value": "flex_8channel_50"},
],
default="flex_1channel_50",
)
During run setup, the technician can choose from a menu of the provided choices.
New in version 2.18.