Runtime Parameters

Overview

This section details the process of defining parameters in a workflow that can then be set by a user when starting a run.

Parameters are variable values in a workflow that a user does not want to ‘hardcode’ in the workflow definition but instead wants to define them when going through the process of starting a run on LINQ.

An example would be defining a boolean parameter that determines if a labware would undergo a specific task or not.

Defining Parameters

Parameters can only be used in task arguments and the time_estimate field in a task.

Five different parameter types can be defined: Boolean, Float, Integer, String, and FileRef parameters. See each class definition below.

Here are some example parameter definitions:

from linq.parameters import (
    BooleanParameterDefinition,
    FloatParameterDefinition,
    IntegerParameterDefinition,
    StringParameterDefinition,
    FileRefParameterDefinition,
)

cold_plate_temperature = FloatParameterDefinition(
    id="cold_plate_temperature",
    name="Cold Plate Temperature",
    default=10.0,
)

centrifuge_option = BooleanParameterDefinition(
    id="scan_barcode",
    name="Scan Barcode",
    default=False,
)

number_of_cycles = IntegerParameterDefinition(
    id="number_of_cycles",
    name="Number of Cycles",
    default=3,
)

method_file_path = StringParameterDefinition(
    id="method_file_path",
    name="Method File Path",
    is_file_path=True,
)

config_file = StringParameterDefinition(
    id="config_file",
    name="Configuration File",
    is_file_path=True,
)

# For file references with automatic CSV-to-JSON conversion
data_file = FileRefParameterDefinition(
    id="data_file",
    name="Input Data File",
    default="samples.csv",
    always_required=False,
)

Tip

Use StringParameterDefinition with is_file_path=True for file paths that must exist at deploy time. Use FileRefParameterDefinition for runtime file references with automatic CSV-to-JSON conversion.

For workflow tasks to access parameters, the parameter definitions need to be defined (in a list) as an argument in the workflow object

workflow = Workflow(
    ...
    parameter_definitions=[cold_plate_temperature, centrifuge_option, method_file_path, data_file]
)

These parameters can then be used in the inputs argument of a task by referencing the desired parameter id

from linq.parameters import ParameterReference

incubate_in_cold_plate = workflow.add_task(
    ActionTask(
        ...
        inputs=Inputs(temperature=ParameterReference(parameter_id="cold_plate_temperature")),
    )
)

Setting Parameters

Parameters are set in the publish stage of workflow execution. Parameters can be set in two ways:

  1. As a response to CLI prompts.

  2. By providing a parameters.json configuration file.

Setting parameters through CLI prompts

When publishing a workflow with parameters defined and no parameters file provided, parameters are set through prompts on the command line.

foo@bar:~$ linq workcell publish <workflow-id>
Enter Float value for parameter 'Cold Plate Temperature' or hit enter to use default value '10.0':

Once all parameters are provided the publish command will execute.

Setting parameters through a parameters file

Alternatively, rather than manually entering every parameter value through prompts on the command line, a JSON file specifying parameter values can be provided as an argument to the publish command.

linq workcell publish <workflow-id> --parameters <path_to_parameters_json>

Example parameters JSON:

{
  "Cold Plate Temperature": 10.0,
  "Scan Barcode": true,
  "Method File Path": "path/to/method_file.txt",
  "Input Data File": "path/to/samples.csv"
}

Note

The parameters JSON schema is {<Type>ParameterDefinition.name: value}. For FileRefParameterDefinition, CSV files are automatically converted to JSON format during processing.

Setting individual parameters via CLI flags

You can also set individual parameters using the --param flag:

linq workcell publish <workflow-id> --param "Cold Plate Temperature=15.5" --param "Scan Barcode=true"

Parameters support quoted values for strings with spaces:

linq workcell publish <workflow-id> --param 'Input Data File="/path/to my file/samples.csv"'

CLI parameters take precedence over parameters file values when both are provided.

Time estimates as parameters

Parameters can also be used in place of time estimates. Time estimate parameters use Integer type parameters:

time_estimate_1 = IntegerParameterDefinition(
 id="time_estimate_1",
 name="Time Estimate",
 default=60, # In seconds
 )

incubate_in_cold_plate = workflow.add_task(
    ActionTask(
        ...
        time_estimate=ParameterReference(time_estimate_1)
        ...
    )
)

Parameter Types

class linq.parameters.BooleanParameterDefinition(*, id: str = ..., name: str = ..., always_required: bool = False, default: bool | None = ...)
class linq.parameters.FloatParameterDefinition(*, id: str = ..., name: str = ..., always_required: bool = False, default: float | None = None, minimum: float | None = None, maximum: float | None = None)
class linq.parameters.IntegerParameterDefinition(*, id: str = ..., name: str = ..., always_required: bool = False, default: int | None = None, minimum: int | None = None, maximum: int | None = None, multiple_of: int | None = None)
class linq.parameters.StringParameterDefinition(*, id: str = ..., name: str = ..., always_required: bool = False, default: str | None = None, is_file_path: bool | None = False, is_directory_path: bool = False)

CSV File Processing

FileRefParameterDefinition provides automatic CSV-to-JSON conversion for seamless data integration:

Automatic Conversion

When a FileRef parameter references a CSV file, it’s automatically converted to JSON format:

# CSV file: samples.csv
# sample_id,name,concentration
# S001,Control,25.5
# S002,Test A,30.2

# Becomes JSON:
# [
#   {"sample_id": "S001", "name": "Control", "concentration": "25.5"},
#   {"sample_id": "S002", "name": "Test A", "concentration": "30.2"}
# ]

Supported Delimiters

The CSV processor automatically detects common delimiters:

  • Comma (,) - most common

  • Semicolon (;) - European format

  • Tab (\t) - TSV files

Usage in Workflows

from linq.parameters import FileRefParameterDefinition, ParameterReference

# Define the parameter
sample_data = FileRefParameterDefinition(
    id="sample_data",
    name="Sample Data File",
    default="samples.csv"
)

# Use in workflow
workflow = Workflow(
    parameter_definitions=[sample_data]
)

# Reference in task
process_samples = workflow.add_task(
    ActionTask(
        inputs=Inputs(
            sample_list=ParameterReference(parameter_id="sample_data")
        )
    )
)