deepcave.plugins¶

# Plugins

This module provides a base class for all the available plugins. It provides different utilities to handle the plugins and check for compatibility in the runs.

## Classes

Plugin: Base class for all plugins.

Classes

Plugin()

Base class for all plugins.

class deepcave.plugins.Plugin[source]¶

Bases: Layout, ABC

Base class for all plugins.

Provides different utilities to handle the plugins and check for compatibility in the runs.

Properties¶

inputsList[Tuple[str, str, bool, Any]]: The registered inputs.
outputsList[Tuple[str, str, bool]]: The registered outputs.
previous_inputsDict[str, Dict[str, str]]: The previous inputs.
raw_outputsOptional[Dict[str, Any]]: The raw outputs.
activate_run_selectionbool: Shows a dropdown to select a run in the inputs layout. This feature is useful if only one run could be viewed at a time. Moreover, it prevents the plugin to calculate results across all runs.
idstr: The unique identifier for the plugin.
runsList[AbstractRun]: A list of the abstract runs.
groupsList[Group]: A list of the groups.
helpstr: The path to the documentation.
namestr: The name of the plugin. It is shown in the navigation and title.
button_captionstr: Caption of the button. Shown only, if StaticPlugin is used.

__call__(render_button=False)[source]¶

Return the components for the plugin.

Basically, all blocks and elements of the plugin are stacked-up here.

Parameters:

render_button (bool, optional) – Whether to render the button or not. By default False.

Returns:

Layout as list of components.

Return type:

List[Component]

Raises:

NotMergeableError – If runs are not compatible.
FileNotFoundError – If the help file can not be found.

property all_runs: List[AbstractRun]¶

Get all runs and include the groups as a list.

Returns:: The list with all runs and included groups.
Return type:: List[AbstractRun]

static check_run_compatibility(run)[source]¶

Check if a run is compatible with this plugin.

If a plugin is not compatible, you can not select the run.

Note

This function is only called if activate_run_selection is True.

Parameters:: run (AbstractRun) – One of the selected runs/groups.
Returns:: Returns True if the run is compatible.
Return type:: bool

check_runs_compatibility(runs)[source]¶

Needed if all selected runs need something in common.

(e.g. budget or objective). Since this function is called before the layout is created, it can be also used to set common values for the plugin.

Parameters:: runs (List[AbstractRun]) – Selected runs.
Raises:: NotMergeableError – If runs are not compatible, an error is thrown.
Return type:: None

generate_inputs(**kwargs)[source]¶

Generate inputs for the process and load_outputs required for api mode.

The arguments are validated against the input schema.

Note

Arguments are only available at runtime. Therefore, no api can be shown beforehand.

Parameters:: kwargs (Any) – Additional keyword arguments.
Returns:: The inputs for the run.
Return type:: Dict[str, Any]
Raises:: ValueError – If an unknown input is passed. If an input is missing.

classmethod generate_outputs(runs, inputs)[source]¶

Check whether run selection is active and accepts either one or multiple runs at once.

Calls process internally.

Parameters:

runs (Union[AbstractRun, List[AbstractRun]]) – Run or runs to process.
inputs (Dict[str, Any]) – Input data. Only “real” inputs (not “filter” inputs) are necessary.

Returns:

Returns a data dictionary with the same outputs as process. If activate_run_selection is set, a Dict[str, Dict[str, Any]] is returned. The first dictionary is keyed by the run.id.

Return type:

Union[Dict[str, Any], Dict[str, Dict[str, Any]]]

classmethod get_base_url(cls)[source]¶

Generate the url for the plugin.

Returns:: Url for the plugin as string.
Return type:: str

static get_filter_layout(register)[source]¶

Layout for the filter block.

Parameters:: register (Callable) – The register method to register (user) variables. For more information, see ‘register_input’.
Returns:: Layouts for the filter block.
Return type:: List[Component]

static get_input_layout(register)[source]¶

Layout for the input block.

Parameters:: register (Callable) – The register method to register (user) variables. For more information, see ‘register_input’.
Returns:: Layouts for the input block.
Return type:: List[Component]

get_internal_id(id)[source]¶

Get the internal id.

Return type:: str

get_internal_input_id(id)[source]¶

Get the internal input id.

Return type:: str

get_internal_output_id(id)[source]¶

Get the internal output id.

Return type:: str

static get_mpl_output_layout(register)[source]¶

Layout for the matplotlib output block.

Parameters:: register (Callable) – The register method to register outputs. For more information, see ‘register_input’.
Returns:: Layout for the matplotlib output block.
Return type:: Optional[Union[Component, List[Component]]]

static get_output_layout(register)[source]¶

Layout for the output block.

Parameters:: register (Callable) – The register method to register outputs. For more information, see ‘register_input’.
Returns:: Layouts for the output block.
Return type:: Union[Component, List[Component]]

static get_run_input_layout(register)[source]¶

Generate the run selection input.

This is only the case if activate_run_selection is True.

Parameters:: register (Callable) – The register method to register (user) variables. For more information, see ‘register_input’.
Returns:: The layout of the run selection input.
Return type:: Component

get_selected_runs(inputs)[source]¶

Parse selected runs from inputs.

If self.activate_run_selection is set, return only selected run. Otherwise, return all possible runs.

Parameters:: inputs (Dict[str, Any]) – The inputs to parse.
Returns:: The selected runs.
Return type:: List[AbstractRun]
Raises:: PreventUpdate – If activate_run_selection is set but run is not available.

property groups: List[Group]¶

Get the groups as a list.

Returns:: The list with the groups.
Return type:: List[Group]

load_dependency_inputs(run, previous_inputs, inputs)[source]¶

Load the content as in ‘load_inputs’ but called after inputs have changed.

Provides a lot of flexibility.

Note

Only the changes have to be returned. The returned dictionary will be merged with the inputs.

Parameters:

run (Optional[Union[AbstractRun, List[AbstractRun]]], optional) – The selected run from the user. In case of activate_run_selection, only one run is passed. Defaults to None.
previous_inputs (Dict[str, Any]) – Previous content of the inputs.
inputs (Dict[str, Any]) – Current content of the inputs.

Returns:

Dictionary with the changes.

Return type:

Dict[str, Any]

load_inputs()[source]¶

Load the content for the defined inputs in get_input_layout and get_filter_layout.

This method is necessary to pre-load contents for the inputs. So, if the plugin is called for the first time or there are no results in the cache, the plugin gets its content from this method.

Returns:: Content to be filled.
Return type:: Dict[str, Any]

static load_mpl_outputs(runs, inputs, outputs)[source]¶

Read in the raw data and prepare them for the layout.

Note

The passed inputs are cleaned and therefore differs compared to load_inputs or load_dependency_inputs. Inputs are cleaned s.t. only the first value is used. Also, boolean values are casted to booleans.

Parameters:

runs (Union[AbstractRun, Dict[str, AbstractRun]]) – All selected runs. If activate_run_selection is set, only the selected run is returned.
inputs (Dict[str, Dict[str, str]]) – Input and filter values from the user.
outputs (Dict[str, Union[str, Dict[str, str]]]) – Raw outputs from the runs. If activate_run_selection is set, a Dict[str, str] is returned.

Returns:

The components must be in the same position as defined in get_output_layout.

Return type:

Union[Component, List[Component]]

static load_outputs(runs, inputs, outputs)[source]¶

Read in the raw data and prepare them for the layout.

Note

Parameters:

runs (Union[AbstractRun, Dict[str, AbstractRun]]) – All selected runs. If activate_run_selection is set, only the selected run is returned.
inputs (Dict[str, Dict[str, str]]) – Input and filter values from the user.
outputs (Dict[str, Union[str, Dict[str, str]]]) – Raw outputs from the runs. If activate_run_selection is set, a Dict[str, str] is returned.

Returns:

The components must be in the same position as defined in get_output_layout.

Return type:

Union[Component, List[Component]]

static load_run_inputs(runs, groups, check_run_compatibility)[source]¶

Load the options for get_run_input_layout.

Both runs and groups are displayed.

Parameters:

runs (List[AbstractRun]) – The runs to display.
groups (List[Group]) – The groups to display.
check_run_compatibility (Callable[[AbstractRun], bool]) – If a single run is compatible. If not, the run is not shown.

Returns:

Both runs and groups, separated by a separator.

Return type:

Dict[str, Any]

static process(run, inputs)[source]¶

Return raw data based on a run and input data.

Warning

The returned data must be JSON serializable.

Note

Parameters:

run (AbstractRun) – The run to process.
inputs (Dict[str, Any]) – Input data.

Returns:

Serialized dictionary.

Return type:

Dict[str, Any]

register_callbacks()[source]¶

Following callbacks are registered: - If inputs changes, the changes are pasted back. This is in particular interest if input dependencies are used. - Raw data dialog to display raw data. - Callback to be redirected to the config if clicked on it.

Raises:: RuntimeError – If no run id is found.
Return type:: None

register_input(id, attributes='value', filter=False, type=None)[source]¶

It is important to register the inputs. This is, because callbacks have to be defined before the server is started. After registering all inputs, an internal mapping is created.

Parameters:

id (str) – Specifies the id of the input.
attributes (Union[str, List[str]], optional) – Attributes which should be passed to the (dash) component, by default (“value”,).
filter (bool, optional) – Specifies if the input is a filter. By default False.
type (Any, optional) – Type to which the first attribute should be casted to. By default str.

Returns:

id – Unique id for the input and plugin. This is necessary because ids are defined globally.

Return type:

str

register_output(id, attributes='value', mpl=False)[source]¶

Parameters:

id (str) – Specifies the id of the output.
attributes (Union[str, List[str]], optional) – Attribute, by default “value”
mpl (bool, optional) – Specifies if the registration is for matplotlib or default, by default False

Returns:

id – Unique id for the output and plugin. This is necessary because ids are defined globally.

Return type:

str

property runs: List[AbstractRun]¶

Get the runs as a list.

Returns:: The list with the runs.
Return type:: List[AbstractRun]

Modules

`deepcave.plugins.budget`	# budget
`deepcave.plugins.dynamic`	# Dynamic
`deepcave.plugins.hyperparameter`	# hyperparameter
`deepcave.plugins.objective`	# objective
`deepcave.plugins.static`	# Static
`deepcave.plugins.summary`	# summary

deepcave.runs.trial

deepcave.plugins.budget

DeepCAVE Documentation

deepcave.plugins¶

Properties¶