Parameter API Reference#

Definitions of parameters types to configure custom Freva plugins.

Plugin parameters are defined in the plugin wrapper class. Please refer to evaluation_system.api.plugin for more information on how to set up a plugin wrapper class.

class evaluation_system.api.parameters.Bool(name=None, default=None, mandatory=False, max_items=None, item_separator=',', regex=None, version=1, help='No help available.', print_format='%s', impact=0)#

Bases: ParameterType

A boolean parameter.

Parameters:

kwargs – Additional ParameterType parameters.

Example

from evaluation_system.api import plugin, parameters
class MyPlugin(plugin.PluginAbstract):
    __parameters__ = parameters.ParameterDictionary(
        parameters.Bool(
                    name="convert_variables",
                    default=True,
                    help="Convert the variables",
                    ),
    )
base_type#

alias of bool

parse(value: Any) → bool#

Convert a string to a boolean value.

The following values will be mapped

true, t, yes, y, on, 1 => TRUE false, f, no, n, off, 2 => FALSE

Parameters:

value (Union[str, int, bool]) – Input representation of the boolean such as true, false, t, y, f, …

Raises:

ValidationException: – if the given input value can not be converted to a bool.

class evaluation_system.api.parameters.CacheDirectory(impact=9, **kwargs)#

Bases: Directory

A parameter representing a cache directory in the system.

Parameters:

kwargs – Additional ParameterType parameters.

Example

from evaluation_system.api import plugin, parameters
class MyPlugin(plugin.PluginAbstract):
    __parameters__ = parameters.ParameterDictionary(
        parameters.CacheDirectory(
                    name="cache_directory",
                    default="/scratch",
                    help="Set the path to a temporary directory",
                    ),
    )
class evaluation_system.api.parameters.Date(*args, **kwargs)#

Bases: String

A date parameter.

Parameters:

kwargs – Additional ParameterType parameters.

Example

from evaluation_system.api import plugin, parameters
class MyPlugin(plugin.PluginAbstract):
    __parameters__ = parameters.ParameterDictionary(
        parameters.Date(
                    name="time",
                    default="1950-01-10",
                    help="Select a timestamp",
                    ),
    )
class evaluation_system.api.parameters.File(file_extension='nc', **kwargs)#

Bases: String

A parameter representing a file in the system.

Parameters:

  • file_extension (str, default: nc) – Suffix (file types) of the files that should be considered.

  • kwargs – Additional ParameterType parameters.

Example

from evaluation_system.api import plugin, parameters
class MyPlugin(plugin.PluginAbstract):
    __parameters__ = parameters.ParameterDictionary(
        parameters.File(
                    name="input_file",
                    file_extension="geojson",
                    mandatory=False,
                    help="Select a geojson file.",
                    ),
    )
class evaluation_system.api.parameters.Float(**kwargs)#

Bases: ParameterType

A float parameter.

Parameters:

kwargs – Additional ParameterType parameters.

Example

from evaluation_system.api import plugin, parameters
class MyPlugin(plugin.PluginAbstract):
    __parameters__ = parameters.ParameterDictionary(
        parameters.Float(
                    name="mul",
                    default=3.16,
                    help="Set a multiply factor."
                    ),
    )
base_type#

alias of float

class evaluation_system.api.parameters.InputDirectory(name=None, default=None, mandatory=False, max_items=None, item_separator=',', regex=None, version=1, help='No help available.', print_format='%s', impact=0)#

Bases: String

A parameter representing a input directory in the system.

Parameters:

kwargs – Additional ParameterType parameters.

Example

from evaluation_system.api import plugin, parameters
class MyPlugin(plugin.PluginAbstract):
    __parameters__ = parameters.ParameterDictionary(
        parameters.InputDirectory(
                    name="input_directory",
                    default="/work/data",
                    mandatory=False,
                    help="Select the input directory",
                    ),
    )
class evaluation_system.api.parameters.Integer(**kwargs)#

Bases: ParameterType

An integer parameter.

Parameters:

kwargs – Additional ParameterType parameters.

Example

from evaluation_system.api import plugin, parameters
class MyPlugin(plugin.PluginAbstract):
    __parameters__ = parameters.ParameterDictionary(
        parameters.Integer(
                    name="const",
                    default=3,
                    help="Set a constant factor"
                    ),
    )
base_type#

alias of int

evaluation_system.api.parameters.ParameterBaseType#

Type definitions of all possible parameter types.

alias of str | int | float | bool | PrintableList

class evaluation_system.api.parameters.ParameterDictionary(*parameters: ParameterType)#

Bases: dict

Directory holding all plugin parameters for a Freva plugin.

This class behaves like a built-in dict with additional features. The most prominent feature is that the order of added items is preserved, as opposed to a normal build-in dict.

Parameters:

parameters (ParameterType) – collection of parameters of type ParameterType. Note: The order of the parameters will be preserved.

Example

from evaluation_system.api import plugin, parameters
class MyPlugin(plugin.PluginAbstract):
    __parameters__ = parameters.ParameterDictionary(
        parameters.String(name="title", default="The title"),
        parameters.Integer(name="int_value", mandatory=True),
        parameters.Float(name="float_value", default=0.0)
    )
get_help(width: int = 80, notebook: bool = False) → str#

Render plugin help string to be displayed in a cli context.

Parameters:

  • width (int, default: 80) – Column width used to wrap the help text.

  • notebook (bool, default: False) – Optimise output for jupyter notebooks

Returns:

Help test for this plugin configuration.

Return type:

str

get_parameter(param_name: str) → ParameterType#

Return the parameter object from the given name.

Parameters:

param_name (str) – Name of the parameter that is queried

Raises:

ValidationError: – if the parameter name doesn’t match anything stored here.

parameters() → list[ParameterType]#

All parameters stored in ParameterDictionary

parseArguments(**kwargs: Any) → Any#
parse_arguments(opt_arr: str | list[str], use_defaults: bool = False, complete_defaults: bool = False, check_errors: bool = True) → dict[str, str | int | float | bool | PrintableList | list[str | int | float | bool | PrintableList]]#

Parse a list of strings to a parameter dictionary.

The strings are of the type: key1=val1 or key2 multiple values can be defined by either defining the same key multiple times or by using the item_separator character

Parameters:

  • opt_arr (Union[str, list[str]]) – List of strings containing (“key=value”|”key”|”key=value1,value2” iff item_separator==’,’)

  • use_defaults (bool, default: False) – If the parameters defaults should be used when value is missing

  • complete_defaults (bool, default: False) – Return a complete configuration containing None for those not provided parameters that has no defaults.

  • check_errors (bool, default: True) – Check for configuration errors.

Returns:

dictionary holding the plugin configuration.

Return type:

dict[str, Union[ParameterBaseType, list[ParameterBaseType]]

Raises:

ValidationError: – Raises a ValidationError if a wrong configuration was parsed.

synchronize(tool: str) → None#

Synchronize all entries for a plugin configuration of a given tool

Parameters:

tool (str) – Name of the tool to be synced

validate_errors(config_dict: dict[str, Any], raise_exception: bool = False) → dict[str, list[tuple[str, int]]]#

Checks if the given configuration dictionary is valid.

Parameters:

  • config_dict – the dictionary validated.

  • raise_exception – If an exception should be risen. In such a case only a message is elevated (this could be changed)

Returns:

a dictionary with missing items and those having to many of them or

Return type:

dict

Raises:

ValidationError: – If parameters are missing/duplicated and a raise_exception flag is set to True.

class evaluation_system.api.parameters.ParameterType(name=None, default=None, mandatory=False, max_items=None, item_separator=',', regex=None, version=1, help='No help available.', print_format='%s', impact=0)#

Bases: initOrder

Base class for all parameter types.

All available parameter types inherit from this class. The class creates a parameter object holding the following user defined information.

Parameters:

  • name (str) – Name of the parameter.

  • default (ParameterBaseType, default: str) – the default value of the given parameter. Note: this value must be a valid parameter value!

  • mandatory (bool, default: False) – boolean indicating if this parameter is required

  • max_items (int, default: 1) – If set to > 1 it will cause the values to be returned in a list (even if the user only provided 1). Raises an error if more than than max_items values are parsed.

  • item_separator (str, default: ,) – The string used to separate multiple values for this parameter. In some cases (at the shell, web interface, etc) the user have always the option to provide multiple values by re-using the same parameter name (e.g. param1=a param1=b produces {'param1': ['a', 'b']}). But the configuration file does not allow this at this time. Therefore is better to setup a separator, even though the user might not use it while giving input. It must not be a character, it can be any string (make sure it’s not a valid value!!)

  • regex (Optional[str], default: None) – A regular expression defining valid “string” values before parsing them to their defining classes (e.g. an Integer might define a regex of “[0-9]+” to prevent getting negative numbers). This will be used also on Javascript so don’t use fancy expressions or make sure they are understood by both python and Javascript.

  • help (str, default: No help available) – The help string describing what this parameter is good for.

  • print_format (str, default %s) – String format used to display parameter values, e.g. %.2f to display always 2 decimals for floats

  • impact – The impact of the parameter to the output, possible values are Parameter.Impact.affects_values, Parameter.Impact.affects_plots, Parameter. Impact.no_effects

base_type#

Type of this parameter.

alias of str

format(value: str | None = None) → str#

Format the default value or the given one to a string.

Parameters:

value (Optional[str], default: None) – the value to be formatted, if set to None the default value of this parameter will be used.

Returns:

formatted string value

Return type:

str

Note

This can be overwritten to provide more control over how values are being displayed.

get_type() → str#

Get the name of the class.

static infer_type(value: Any) → Type#

Infer the type of a given default.

parse(value: str | list[str]) → list[str | int | float | bool | PrintableList] | str | int | float | bool | PrintableList#

Parse a parameter value.

Parameters:

value (Union[str, list[str]]) – The parameter value that should be parsed.

Returns:

Parsed parameter value

Return type:

ParameterBaseType

synchronize(tool: str) → int#

Read the id of a tool from the database

Parameters:

tool – name of the plugin that is synchronised.

Returns:

database id entry for the plugin

Return type:

int

to_str(value: Any) → str#

Transform this value in a serializable string.

Parameters:

value (Any) – Value that is to be converted to a string

Returns:

String representation of the input value.

Return type:

str

class evaluation_system.api.parameters.Range(*args, **kwargs)#

Bases: String

A range parameter, e.g passing experiment lists (1970,1975,…,2000).

:param see ParameterType parameters for more details.:

Example

from evaluation_system.api import plugin, parameters
class MyPlugin(plugin.PluginAbstract):
    __parameters__ = parameters.ParameterDictionary(
        parameters.Range(
                    name="time_range",
                    default="1950:10:1980", # range(1950, 1990, 10)
                    help="Set a time range",
                    ),
    )
parse(value: Any) → PrintableList#

Parses a “RangeString” and returns a “PrintableList”.

Values can be a comma separated string, colon separated or a combination Values after “-” are deleted from the resulting list

Parameters:

value ('start:step:stop-value' --> 1970:5:2000-1985 or 1970:2000,1980-1990:1995)

Returns:

PrintableList of range items

Return type:

PrintableList

Raises:

ValueError: – Raises a ValueError if items can’t be parsed to list.

to_str(value: Any) → str#

Conevert input value to string.

class evaluation_system.api.parameters.SelectField(options: dict[str, str], allow_user_input: bool = False, multiple: bool = False, **kwargs)#

Bases: ParameterType

Select field to select parameter from predefined values.

Parameters:

  • options (dict[str, str]) – Directory representing the names and values of the predefined options.

  • allow_user_input (bool, default: False) – Set to True to allow user input beyond predefined options.

  • multiple (bool, default: False) – Allow that users can pick multiple options.

  • kwargs – Additional ParameterType parameters.

Example

from evaluation_system.api import plugin, parameters
class MyPlugin(plugin.PluginAbstract):
    __parameters__ = parameters.ParameterDictionary(
        parameters.SelectField(
                            name="options",
                            default="first",
                            options={1: "first", 2: "second"},
                            help="Select from options",
                              ),
    )
base_type#

alias of str

parse(value: str | list[str]) → PrintableList | str#

Parse a parameter value.

Parameters:

value (Union[str, list[str]]) – The parameter value that should be parsed.

Returns:

Parsed parameter value

Return type:

ParameterBaseType

Raises:

ValueError: – if value is not part of possible options.

class evaluation_system.api.parameters.SolrField(*args, facet: str | None = None, group: int = 1, multiple: bool = False, predefined_facets: list[str] | None = None, editable: bool = True, **kwargs)#

Bases: String

A parameter using solr for finding valid values.

Parameters:

  • facet (str) – Solr search facet used for this parameter

  • group (int, default: 1) – The group this search facet belongs to. This can be used to group different search facets together, for example for comparing multi model ensemble

  • multiple (bool, default: False) – flag indicating whether multiple facets are allowed.

  • predefined_facets (Optional[list[str]], default: None) – a list of strings that are set as default search facets

  • editable – flag indicating whether or not the value can be changed.

  • kwargs – additional ParameterType parameters.

Example

from evaluation_system.api import plugin, parameters
class MyPlugin(plugin.PluginAbstract):
    __parameters__ = parameters.ParameterDictionary(
        parameters.SolrField(
                        name="variable_name",
                        default="tas",
                        facet="variable",
                        max_items=1,
                        group=2,
                        predefined_facets={"time_frequency":["1hr"]},
                        help="Select the variable name",
                    ),
    )
class evaluation_system.api.parameters.String(name=None, default=None, mandatory=False, max_items=None, item_separator=',', regex=None, version=1, help='No help available.', print_format='%s', impact=0)#

Bases: ParameterType

A simple string parameter.

Parameters:

kwargs – Additional ParameterType parameters.

Example

from evaluation_system.api import plugin, parameters
class MyPlugin(plugin.PluginAbstract):
    __parameters__ = parameters.ParameterDictionary(
        parameters.String(
                    name="plot_tile",
                    mandatory=True,
                    default="Plot title",
                    help="Set a title for the plot"
                    ),
    )
base_type#

alias of str

class evaluation_system.api.parameters.Unknown(impact=0, mandatory=True, **kwargs)#

Bases: String

An unknown parameter for conversions.

:param see ParameterType parameters for more details.: