Adding parameters to custom blocks
Last updated
Last updated
Custom DSP, Learn and Transformation blocks can have custom parameters. You use these to give the user an option to visually configure the block. For example to select the cutoff for a filter in a DSP block, or what data augmentation to apply in an ML algorithm.
Each parameter is defined as a JSON object. Here's a basic example:
This renders the following UI element:
Here "name" maps to the label of the element, "help" is shown under a tooltip, "value" is the default value of the element, and "type" is enforced if you enter an invalid value.
"param" is the parameter that'll be sent to your block. Depending on the type of block this is either:
DSP Blocks: Passed in an HTTP request to the block, and then (by default) passed as an argument to the Python function implementing the block. See Building custom processing blocks > Adding configuration options.
All other blocks: Passed in as command line arguments, prefixed with --
. E.g. for the example above your block will be called with --scale-axes 1
.
Parameters are described in a parameters.json
file placed in the root of your block. This is then automatically picked up by the Studio when rendering your block.
For DSP blocks the parameters.json file also contains metadata for the block, and the parameters are listed in the parameters
object. Additionally, DSP blocks can contain multiple groups. Each group has a header element that is rendered.
This is rendered as:
For learn blocks the parameters.json
file just contains an array of items.
This is rendered as:
And passed into your script as:
If a learn block has no parameters (either no parameters.json
file or one with an empty array) then the 'Number of training cycles' (maps to --epochs
) and 'Learning rate' (maps to --learning-rate
) elements are rendered.
For transformation blocks the parameters.json
file just contains an array of items.
This is rendered as:
And passed into your script as:
Transformation blocks have two extra types: dataset
and bucket
. Both render a dropdown menu listing all datasets or all configured cloud buckets in your organization. The name of the dataset/bucket will be passed in to your script (e.g. in the configuration above ei-data-dev
is passed in).
The supported properties for the type
attribute are:
These all render a text box.
This renders a dropdown menu and needs to be paired with a valid
parameter listing all options. E.g.:
Renders as:
And:
To use a different label and value for the select element you can pass in an array of objects to valid
. E.g.:
Here the UI renders the label ("gpu (NDP101)" and "log-bin (NDP120/200)") but the values ("gpu" or "log-bin") are actually passed to your blocks.
This renders a checkbox. E.g.:
Renders as:
Boolean values are passed into your transformation and learn blocks with either the value 0 (false) or 1 (true):
If you don't want a value (so just --do-log
passed into the script) then use a flag
(see the next section).
A flag renders exactly the same as a boolean, but for transformation and learn blocks the parameter is passed to your script differently.
If the value is true
then the parameter is just passed in as an argument, e.g.:
If the value is false
then the parameter is omitted.
This renders a dropdown menu with all your organizational datasets. E.g.:
Renders as:
The name of the dataset is passed into your script.
This renders a dropdown menu with all your organizational buckets. E.g.:{
Renders as:
The name of the bucket is passed into your script.
Parameters can be shown depending on the state of other parameters using the showIf
property. E.g.:
Here the 'How much augmentation' property is shown only when the 'Apply augmentation' checkbox is checked.
Default state:
State when the checkbox is checked:
You can also use neq
as the operator to show elements when a clause is not true. Other operators are currently not supported.
DSP Blocks can have multiple implementation versions. This is used heavily in our internal code to add new functionality to existing blocks without breaking earlier implementations. You set the latest implementation version in the info
object of the parameters.json
file (new blocks are created with this implementation version). E.g.:
Then to show certain parameters only for certain implementation versions, you use the showForImplementationVersion
property:
Now the FFT
parameter is only shown for implementation versions 3 and 4. You can find complete examples of this behavior in the spectral analysis DSP block.