BaseDataPlugin¶

class BaseDataPlugin(settings: Optional[dict] = None)

Bases: ABC

BaseDataPlugin is an abstraction of the functionality and interface that is common to all data plugins. What this means practically is that there is a chain of inheritance: all data plugins inherits from their respective base class, all of which inherit from BaseDataPlugin.

It handles stuff like instantiating the plugins, constructing settings dictionaries, and sanity checking the inputs, as well as a handful of bookkeeping functions used by the poriscope GUI to manage interactions between the MVC architecture and the data plugins themselves - basically, anything that involves interaction with the nuts and bolts of the poriscope GUI.

What You Get by Inheriting from Base Data Plugin¶

Warning

You probably do not need to inherit directly from BaseDataPlugin, as this is a general base class for the specific base classes from which Data Plugins are built. If your intention is to build a data plugin that fits one of the existing subtypes, you should inherit instead refer to one of the following pages:

If you are planning to build an entirely new type of Data Plugin not in the list above, we strongly suggest contacting the poriscope developers first.

As soon as you subclass a base class from BaseDataPlugin, the following happens:

The poriscope GUI will know how to interact with this plugin type, and will manage its relationship to other plugin classes on which it might depend
Your plugin will handle basic sanity checks on settings at instantiation without any extra work needed
Several abstract functions are defined that can be realized either at the base class or subclass level that define a common API for all data plugins

Note

For the most part, users will not have to worry much about anything in this base class, as all other abstract base classes for data plugins inherit from this one and will define the relevant interface at the subclass level. However, in the unlikely event that you are defining an entirely new class of data plugin, it will need to inherit from this base in order to fully integrate into poriscope. Because integrating a new base into poriscope requires registration in core app elements, it is strongly encouraged that you contact the repository managers before trying in order to assess whether there is a simpler solution.

Public Methods¶

Abstract Methods¶

These methods must be implemented by subclasses.

abstractmethod BaseDataPlugin.close_resources(channel: int | None = None) → None¶

Perform any actions necessary to gracefully close resources before app exit. If channel is not None, handle only that channel, else close all of them.

Parameters:: channel (Optional[int]) – channel ID

abstractmethod BaseDataPlugin.get_empty_settings(globally_available_plugins: Dict[str, List[str]] | None = None, standalone=False) → Dict[str, Dict[str, Any]]¶

Get a dict populated with keys needed to initialize the filter if they are not set yet. This dict must have the following structure, but Min, Max, and Options can be skipped or explicitly set to None if they are not used. Value and Type are required. All values provided must be consistent with Type.

settings = {'Parameter 1': {'Type': <int, float, str, bool>,
                                 'Value': <value> or None,
                                 'Options': [<option_1>, <option_2>, ... ] or None,
                                 'Min': <min_value> or None,
                                 'Max': <max_value> or None
                                },
                ...
                }

Parameters:

globally_available_plugins (Optional[ Dict[str, List[str]]]) – a dict containing all data plugins that exist to date, keyed by metaclass. Must include “MetaReader” as a key, with explicitly set Type MetaReader.
standalone (bool) – False if this is called as part of a GUI, True otherwise. Default False

Returns:

the dict that must be filled in to initialize the filter

Return type:

Dict[str, Dict[str, Any]]

abstractmethod BaseDataPlugin.report_channel_status(channel: int | None = None, init=False) → str¶

Return a string detailing any pertinent information about the status of analysis conducted on a given channel

Parameters:

channel (Optional[int]) – channel ID
init (bool) – is the function being called as part of plugin initialization? Default False

Returns:

the status of the channel as a string

Return type:

str

abstractmethod BaseDataPlugin.reset_channel(channel: int | None = None) → None¶

Perform any actions necessary to reset a channel to its starting state. If channel is not None, handle only that channel, else reset all of them.

Parameters:: channel (Optional[int]) – channel ID

Concrete Methods¶

BaseDataPlugin.apply_settings(settings: dict) → None¶

Validate that settings are correct and reasonable, and set params if the check passes

Parameters:: settings (dict) – a dict containing the information needed

BaseDataPlugin.force_serial_channel_operations() → bool¶

Purpose: Indicate whether operations on different channels must be serialized (not run in parallel).

For plugins that do not depend on other data plugins, by default this simply returns False, meaning that it is acceptable and thread-safe to run operations on different channels in different threads on this plugin. If such operation is not thread-safe, this function should be overridden to simply return True. In the case where your plugin depends on another plugin (for example, event finder plugins depend on reader plugins), then your plugin should defer thread safety considerations to the plugin on which it depends.

Returns:: True if only one channel can run at a time, False otherwise
Return type:: bool

BaseDataPlugin.get_dependents() → Set[Tuple[str, str]]¶

Get the set of (metaclass, key) tuples representing this plugin’s dependents.

Returns:: Set of dependents
Return type:: Set[Tuple[str, str]]

BaseDataPlugin.get_key() → str¶

Get the key used to identify this plugin within the global app scope

Returns:: the key of the reader
Return type:: str

BaseDataPlugin.get_parents() → Set[Tuple[str, str]]¶

Get the set of (metaclass, key) tuples representing this plugin’s parents.

Returns:: Set of parents
Return type:: Set[Tuple[str, str]]

BaseDataPlugin.get_raw_settings() → dict | None¶

Get the settings that were applied during initialization of the instance

Returns:: the dict that must be filled in to initialize the plguin
Return type:: Optional[dict]

BaseDataPlugin.register_dependent(metaclass: str, key: str) → None¶

Returns:: the dict that must be filled in to initialize the plguin
Return type:: Optional[dict]

BaseDataPlugin.register_parent(metaclass: str, key: str) → None¶

Returns:: the dict that must be filled in to initialize the plguin
Return type:: Optional[dict]

BaseDataPlugin.set_key(key: str) → None¶

Set the key used to identify this plugin within the global app scope

Parameters:: str – they key of the plugin

BaseDataPlugin.unregister_dependent(metaclass: str, key: str) → None¶

Returns:: the dict that must be filled in to initialize the plguin
Return type:: Optional[dict]

BaseDataPlugin.unregister_parent(metaclass: str, key: str) → None¶

Returns:: the dict that must be filled in to initialize the plguin
Return type:: Optional[dict]

BaseDataPlugin.update_raw_settings(key, val) → None¶

Update raw settings when needed

Returns:: the dict that must be filled in to initialize the plguin
Return type:: Optional[dict]

Private Methods¶

Abstract Methods¶

These methods must be implemented by subclasses.

abstractmethod BaseDataPlugin._finalize_initialization()¶

Apply the provided paramters and intialize any internal structures needed Should Raise if initialization fails.

This function is called at the end of the class constructor to perform additional initialization specific to the algorithm being implemented. kwargs provided to the base class constructor are available as class attributes.

abstractmethod BaseDataPlugin._init() → None¶: called at the start of base class initialization

abstractmethod BaseDataPlugin._validate_settings(settings: dict) → None¶

Validate that the settings dict contains the correct information for use by the subclass.

Parameters:: settings (dict) – Parameters for event detection.
Raises:: ValueError – If the settings dict does not contain the correct information.

Concrete Methods¶

BaseDataPlugin.__enter__()¶: Enter the context management. Return self to be used within a ‘with’ statement.

BaseDataPlugin.__exit__(exc_type, exc_val, exc_tb)¶: Exit the context management. Close resources.

BaseDataPlugin.__init__(settings: dict | None = None)¶

BaseDataPlugin._validate_param_ranges(settings: dict) → None¶

Validate that the filter_params dict contains correct data types

param settings: A dict specifying the parameters of the filter to be created. Required keys depend on subclass. :type settings: dict :raises TypeError: If the filter_params parameters are of the wrong type

BaseDataPlugin._validate_param_types(settings: Dict[str, Setting]) → None¶

Validate that the filter_params dict contains correct data types, but only checks primitives. More detailed parameter checking should follow a call to super() in an override.