Parameters

Floe is designed to encourage reuse of WorkFloes and cubes. To facilitate this, Parameters can be added to both cubes and WorkFloes. Floe comes with built-in parameter classes for several different types of parameter. Just like WorkFloes and cubes, Parameters are represented internally using the Floe specification.

Parameter Types

There are seven fundamental parameter types in Floe:

  • BooleanParameter: True or False. The strings ‘1’ or ‘true’ are coerced to True, everything else is False.
  • DecimalParameter: A floating point value optionally bounded by min_value or max_value.
  • FileInputParameter: A string containing the name of a file to be used for input.
  • FileOutputParameter: A string containing the name of a file to be used for output.
  • IntegerParameter: An integer optionally bounded by min_value or max_value.
  • JSONParameter: A JSON object map (i.e. dictionary). Strings are deserialized into JSON.
  • StringParameter: A string, optionally bound by max_length.

Adding a cube parameter

Cube Parameters can be added by instantiating the parameter on the class:

# param_example_cubes.py
from floe.api import ComputeCube, IntegerParameter

class ExampleCube(ComputeCube):

    # Below is an example parameter that demonstrates some of the available features
    example_int = IntegerParameter(
        title="Example Integer",
        default=1,
        description="Provide a human-readable message here that describes the parameter",
        min_value=0,
        max_value=100,
    )

Specifying Parameters at run time

When a WorkFloe is executed as a script, Floe will collect all Parameters for all cubes and build an argument parser which recognizes those Parameters, where each cube parameter is prefixed by the name of the cube it belongs to.

In the example WorkFloe below, the FileInputCube and FileOutputCube both take Parameters that specify the filenames to read from and write to:

# example_floe.py
from my_cubes import PrinterCube, FileInputCube, FileOutputCube
from floe.api import WorkFloe

job = WorkFloe("Print Data Floe")
ifs = FileInputCube()
printer = PrinterCube()
ofs = FileOutputCube()

job.add_cubes(ifs, printer, ofs)

ifs.success.connect(printer.intake)
printer.success.connect(ofs.intake)

if __name__ == "__main__":
    job.run()

To display help:

$ python example_floe.py --help

To specify the data_in parameter for the ifs cube:

$ python example_floe.py --ifs-data_in mymolecules.oeb

Getting a Parameter value

When a WorkFloe is started, but before each cube’s begin() method is called, all parameter values are parsed and then made available to each cube as a Namespace stored as self.args. To get a Parameter’s value, reference the parameter’s name (not a promoted name) in the namespace as shown in the example below.

Example:

class ExampleCube(ComputeCube):

    example_param = StringParameter()

    def process(self, data, port):
        print("Parameter value is", self.args.example_param)

Grouping cube parameters

Parameters can be associated into logical groups as a hint to a user interface.

Example:

class ExampleCube(ComputeCube):

    repetition_string = StringParameter()
    repetition_times = IntegerParameter()
    repetition_group = ParameterGroup(
        "Example Parameter Group",
        parameters=[
            repetition_string,
            repetition_times,
        ],
        description="These parameters are associated with the repetition operation of this cube",
    )


    def process(self, data, port):
        print(self.args.repetition_string * self.args.repetition_times)

Promoting a cube parameter

By default, cube Parameters are namespaced with a prefix, that is the name of the cube the parameter belongs to. For example, if a cube named testcube had a parameter named limit, the full parameter name for the command line interface would be --testcube-limit. A parameter can be promoted to allow for a more terse name that no longer includes the parent cube. Additionally, promoted Parameters can assume a different promoted name.

When promoting multiple cubes parameters to the same name, each default attribute must also have the same value. Otherwise, the WorkFloe will fail validation. The default attribute can be modified by calling modify_parameter method on cube parameter.

Example:

# example_floe.py
from my_cubes import AnalyzerCube, PrinterCube
from floe.api import WorkFloe, FileInputCube, FileOutputCube, FileInputParameter, IntegerParameter

job = WorkFloe("Workfloe Parameter floe")
ifs = FileInputCube()

# Promote the 'data_in' parameter, with a different promoted name
ifs.modify_parameter(ifs.data_in, promoted=True, promoted_name="infile")

analyzer = AnalyzerCube()
printer = PrinterCube()

# Promote analyzer and printer cubes parameters to common name and set the 'default' attribute
analyzer.modify_parameter(analyzer.size, promoted=True, promoted_name="n_clusters", default=10)
printer.modify_parameter(printer.size, promoted=True, promoted_name="n_clusters", default=10)

ofs = FileOutputCube()

job.add_cubes(ifs, analyzer, printer, ofs)

ifs.success.connect(analyzer.intake)
analyzer.success.connect(printer.intake)
printer.success.connect(ofs.intake)

if __name__ == "__main__":
    job.run()

Note

Serializing a Floe into JSON will preserve promoted Parameters

Parameter Attributes

Parameter Attributes
Name Type Override Description
name string no The name of the parameter as referenced by a cube
required bool no Whether or not the parameter’s value must be set
default param yes The default value of the parameter
description string yes Explanatory text in a user interface
help_text string yes Alias for description
hidden bool yes Whether or not to show in a user interface
level string yes Indicates class of user expected to modify the parameter
choices list yes A list of valid values
many bool yes Indicates the parameter value is a list of its type
max_length int, None yes The max length of a string; None implies no limit
max_value int, None yes The max value of an integer; None implies no upper limit
min_value int, None yes The min value of the integer; None implies no lower limit
null bool yes Indicates that the value of the parameter may be None
promoted_name string, None yes Name of the parameter to hold when promoted
promoted bool yes Whether a parameter is to be elevated from a cube-level to WorkFloe
static bool yes Indicates that the value of the parameter is static
title string, None yes The title of the parameter to use in a user interface
order int, None yes The display order of the parameter in a user interface

Specifying parameter choices

A parameter can be defined with a set of valid choices. By default, only one choice can be selected. Multiple choices can be selected if many is set to True.

class ExampleCube(ComputeCube):

    example_param = StringParameter(
         choices=["Foo", "bar", "Fizz"],
         default="Foo",
     )

    def process(self, data, port):
        print("Parameter value is", self.args.example_param)

When defining the default on a parameter with choices, the value must be within choices. None is also valid when required is set to True.

Providing a static value for a parameter

Sometimes, it is useful to fix a value of a parameter for a specific use of a cube. This can be achieved simply, as demonstrated in the following example:

# example.py
from param_example_cubes import ExampleCube

# Instantiate the cube
example = ExampleCube()

# Fix the value of the 'example_int' parameter on the example cube
example.set_parameters(example_int=42)

Note

Serializing a Floe into JSON will preserve static Parameters, so long as the value of the parameter can be serialized as well.

Ordering cube parameters for user interface display

The order attribute defines the sequence in which parameters will be displayed in the Orion UI. By default, the UI will set parameter order equal to the rank of the cube that defines this parameter. The order can be modified with the modify_parameter() function. The value of the order attribute is a positive integer from 0 to 999, where parameters with lower order will be displayed first in the user interface. Order ties will be broken by sorting parameters alphabetically by name.

Example:

# example_floe.py
from my_cubes import PrinterCube, FileInputCube, FileOutputCube
from floe.api import WorkFloe, FileInputParameter

job = WorkFloe("Workfloe Parameter floe")
ifs = FileInputCube()

# Promote the 'data_in' parameter, and change its default order
ifs.modify_parameter(ifs.data_in, promoted=True, promoted_name="infile", order=3)

printer = PrinterCube()

# Change the order of 'limit' parameter, but do not promote it
ifs.modify_parameter(printer.limit, order=1)

ofs = FileOutputCube()

job.add_cubes(ifs, printer, ofs)

ifs.success.connect(analyzer.intake)
analyzer.success.connect(printer.intake)
printer.success.connect(ofs.intake)

if __name__ == "__main__":
    job.run()

When a Cube parameter has an order attribute set by the Cube author, promoting this parameter in a Floe will set its order to rank of the cube in the Floe, unless the order is explicitly modified by Floe author.

For local development invoking WorkFloe floe run my_workfloe_name.py --help will print the parameters grouped and ordered as in Orion UI:

  • Input (based on parameter type)
  • Output (based on parameter type)
  • Promoted + Required (includes only promoted or required parameters without default)

Within each group, parameters are ordered by order attribute, then by cube rank, then parameter title.

Basic vs. Advanced Parameters

Parameters can be marked as ‘basic’ or ‘advanced’ using the level argument, as shown in the example below. All Parameters are ‘basic’ by default. There are no side effects to setting level, it is only present as an aid to user interfaces.

# param_example_cubes.py
from floe.api import ComputeCube, IntegerParameter

class ExampleCube(ComputeCube):

    # Below is an example parameter that demonstrates some of the available features
    example_int = IntegerParameter(
        default=1,
        description="Provide a human-readable message here that describes the parameter",
        min_value=0,
        max_value=100,
        level="basic"
    )

Overriding parameter fields on a cube

Any attribute for a cube parameter may be modified using the modify_parameter() function.

from floe.api import ComputeCube, IntegerParameter

class ExampleCube(ComputeCube):

    # Below is an example parameter that demonstrates some of the available features
    example_int = IntegerParameter(
        default=1,
        description="Provide a human-readable message here that describes the parameter",
        min_value=0,
        max_value=100,
        level="basic"
    )

cube = ExampleCube()
cube.modify_parameter(
    cube.example_int,
    default=10,
    promoted=True,
    promoted_name="count"
)

Overriding defaults in a derived class

Each parameter has several attributes that can be overridden on a cube by modifying parameter_overrides.

Note

The parameter_overrides class attribute should never be modified aside from its initial definition in a class. Because it is a class attribute, any modifications to parameter_overrides will modify its value for every use of that class.

class ExampleParamOverrideCube(ExampleCube):

    parameter_overrides = {
        "example_int": {
            "default": 2,
            "hidden": True,
        },
    }

Parameter Methods

If a custom parameter is needed, then subclass one of the fundamental types and override one or more methods.

Parameter.get_runtime_value(value)

The get_runtime_value(value) method is used to transform a parameter’s value into a (possibly different) value required by a cube. Parameter validation is performed before this method is called.