OmeroBlitz API
Home Previous Up Next Index

omero::grid::Param

Overview

class Param

A single parameter to a Job. For example, used by ScriptJobs to define what the input and output environment variables should be. Helper classes are available in the Python omero.scripts module, so that the following are equivalent:

# 1
a = omero.grid.Params()
a.optional = True
a.prototype = omero.rtypes.rstring("")
a.description = "An optional string which will be ignored by the script"
omero.scripts.client(inputs = {"a":a})
# 2
a = omero.scripts.String("a", optional=True, description=         * "An optional string which will be ignored by the script")
omero.scripts.client(a)
For advanced setters not available on the Type classes (like omero.script.String) use the getter type.param() and then set values directly.
a = omero.scripts.String("a")
a.param().values = ["hi", "bye"]

Used By

ParamMap

Data Member Index

description
Usage documentation of this param for script users.
optional
Whether or not a script will require this value to be present in the input or output.
useDefault
Whether or not the prototype should be used as a default.
prototype
RType which represents what the input or output value should look like.
min
Minimum value which an input may contain.
max
Maximum value which an input may contain.
values
An enumeration of acceptable values which can be used for this parameter.
grouping
Defines the grouping strategy for this Param.
namespaces
Defines machine readable interpretations for this parameter.

Data Members

string description;

Usage documentation of this param for script users. Example of a bad description: ""a long value"" Example of a good description: ""long representing the number of bins to be used by . A sensible value would be between 16 and 32""

bool optional;

Whether or not a script will require this value to be present in the input or output. If an input is missing or None when non-optional, then a ValidationException will be thrown on {@code processJob}. A missing output param will be marked after execution.

bool useDefault;

Whether or not the prototype should be used as a default. If true, then if the value is missing from the input OR output values, the prototype will be substituted.

param = ...;
inputs = ...;
if name in inputs:
value = inputs[name]
elif param.inputs[name].useDefault:
value = param.inputs[name].prototype

RType prototype;

RType which represents what the input or output value should look like. If this is a collection type (i.e. RCollection or RMap or their subclasses), then the first contents of the collection will be used (recursively).

param.prototype = rlist(rlist(rstring)))
requires that a list of list of strings be passed.

RType min;

Minimum value which an input may contain. If the prototype is a collection type, then the min type must match the type of the innermost non-collection instance. For example,

param.prototype = rlong(0)
param.min = rlong(-5)
but
param.prototype = rlist(rlong(0))
param.min = rlong(-5)

RType max;

Maximum value which an input may contain. If the prototype is a collection type, then the max type must match the type of the innermost non-collection instance. For example,

param.prototype = rlong(0)
param.max = rlong(5)
but
param.prototype = rlist(rlong(0))
param.max = rlong(5)

RList values;

An enumeration of acceptable values which can be used for this parameter. If {@code min} and {@code max} are set, this value will be ignored. If {@code prototype} is an RCollection or RMap instance, then the values in this RList will be of the member types of the collection or map, and not a collection or map instance.

string grouping;

Defines the grouping strategy for this Param.

A set of {@code Param} objects in a single {@code JobParams} can use dot notation to specify that they belong together, and in which order they should be presented to the user.

inputs = {"a" : Param(..., grouping = "1.1"),
"b" : Param(..., grouping = "1.2"),
"c" : Param(..., grouping = "2.2"),
"d" : Param(..., grouping = "2.1")}
defines two groups of parameters which might be display to the user so:
Group 1:                  Group 2:
+-----------------------+ +-----------------------+
| a:                    | | d:                    |
+-----------------------+ +-----------------------+
| b:                    | | c:                    |
+-----------------------+ +-----------------------+

Further dots (e.g. "1.2.3.5") can be used to specify deeper trees of parameters.

By most clients, Params missing grouping values (e.g. "") will be ordered after params with grouping values.

A group which has a boolean as the top-level object can be thought of as a checkbox which turns on or off all of the other group members. For example,

inputs = {"Image_Ids" : Param(prototype=rlist(), grouping = "1"),
"Scale_Bar" : Param(prototype=rbool(), grouping = "2"),
"Color"     : Param(prototype=rinternal(Color()), grouping = "2.1"),
"Size"      : Param(prototype=rlong(), grouping = "2.2")}

might be displayed as:


Scale Bar: [ on/off ]
======================
Color:  [rgb]
Size:   [ 10]

api::StringSet namespaces;

Defines machine readable interpretations for this parameter.

Where the description field should provide information for users, the assigned namespaces can define how clients may interpret the param.

{@code omero.constants.namespaces.NSDOWNLOAD}, for example, indicates that users may want to download the resulting file. The {@code prototype} of the {@code Param} should be one of: model::OriginalFile, model::FileAnnotation, or an annotation link (like model::ImageAnnotationLink) which points to a file annotation.


Home Previous Up Next Index