The parameter statement

• Difficulty level: easy
• Time need to lean: 10 minutes or less
• Key points:
  • A parameter statement defines a parameter that can be passed from command line
  • SoS determines type of parameters from default values or types
  • --no-var is used to specify False for boolean parameters

The parameter statement specifies variables that can be specified from command line (or magics such as %run from SoS Notebook).

The basic format of the statement is

parameter: name = value

where

• name is the name of the parameter
• value is either a default value, or a type (e.g. str, int). Parameters specified with types are required

Parameters are specified with double dash syntax from command line.

Optional and required parameters

Parameters with default values are optional. The default value will be used if the parameter is left unspecified

When a type is specified, a parameter will be required and an error will be raised if a required parameter is not specified

If you have a parameter with underscore _, it can be specified with either underscore (_) or dash (-).

Type of parameters

The types of parameters are determined by the default value or type specification, and determines how they should be passed from command line.

Simple Python types

SoS automatically determines the type of default values and convert your input data to the type. For example, the type of cutoff is determined to be an integer so it accepts an integer value from command line:

An error will be raised if you pass a string,

even a float value

If you intended to accept an float value, use a default value in float:

Yes or no (Boolean types)

Boolean data types can be specified using --opt and --no-opt:

This works the same for boolean variables with default value:

List of strings

A list would be created if the parameter has a default value of type list. For example, a list ['A'] is returned because the default value has a list type.

SoS even understands the type of the values of the list and tries to follow it:

However, it is not yet possible to specify the type of values when you specify a required parameter of type list so all the values will be passed as strings:

SoS types

SoS types such as file_target and sos_targets. Generally speaking you can pass filenames as str or list of str, but passing SoS types such as file_target allow you to create variable in these types without type coercion.

For example, the file_target type is derived from pathlib.Path with automatic expansion of ~ and other features. If you pass a parameter with type file_target, SoS will convert passed string into a path object so that you can use it directly.

Similarly, if you pass a paths (a sequence of path), you parameter will be of type paths:

Scope of parameters

Parameters are usually defined in the global section of workflows, but it can also be defined in steps, in which case the scope of the parameter is limited to the step in which it is defined.

The following example has var_A and var_B defined in steps A and B. Although var_B is specified with a type, it is not required when workflow A is executed.

Parameters and subworkflows

Parameters are usually specified from command line but it can be specified from a subworkflow as it the (nested) workflow is executed with specified parameter.

The %run magic in this example executes the default workflow default, and executes the sub subworkflow with different parameters. You can also specify the workflow to execute directly.