MetaFilter¶

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

This class, MetaFilter, is the base class for all things related to filtering and/or preprocessing raw data before it is passed to other plugins for analysis. While it is presented as a filtering method and the most common use case for it is Bessel filtering, it is not specifically limited to timeseries filtering per se, instead providing a general interface through which data can be passed or otherwise transformed before analysis.

What you get by inheriting from MetaFilter¶

MetaFilter will provide a common API with which to define data preprocessing steps that can be swapped in and out of data analysis pipelines.

Attributes:: logger (logging.Logger): Logger instance for logging messages.

Public Methods¶

Abstract Methods¶

These methods must be implemented by subclasses.

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

Purpose: Clean up any open file handles or memory.

This is called during app exit or plugin deletion to ensure proper cleanup of resources that could otherwise leak. 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 (taking care to respect thread safety if necessary). If no such operation is needed, it suffices to pass, which will be the case for most MetaFilter instances.

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

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

Purpose: Provide a list of settings details to users to assist in instantiating an instance of your MetaReader subclass.

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. Type is required; Value may be omitted or set to None, both meaning there is no default and the user must supply one. 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
                    },
               ...
     }

Several parameter keywords are reserved: these are

‘Input File’ ‘Output File’ ‘Folder’ and all MetaClass names

These must have Type str and will cause the GUI to generate appropriate widgets to allow selection of these elements when used.

In the case of filters, this function must implement returning of a dictionary of settings required to initialize the filter, in the specified format. Values in this dictionary can be accessed downstream through the self.settings class variable. This structure is a nested dictionary that supplies both values and a variety of information about those values, used by poriscope to perform sanity and consistency checking at instantiation. For example, the following settings would be appropriate for a low-pass Bessel filter:

settings = {
    "Cutoff": {
        "Type": float,
        "Value": None,
        "Min": 0,
        "Units": "Hz",
    },
    "Samplerate": {
        "Type": float,
        "Value": None,
        "Min": 0,
        "Units": "Hz",
    },
    "Poles": {
        "Type": int,
        "Value": 8,
        "Options": [2, 4, 6, 8, 10],
    }
}
return settings

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 MetaFilter.reset_channel(channel: int | None = None) → None¶

Purpose: Reset the state of a specific channel for a new operation or run.

This is called any time an operation on a channel needs to be cleaned up or reset for a new run. If channel is not None, handle only that channel, else close all of them. If calling part of this plugin from different channels to do not create persistent state changes in your plugin, you can simply pass this function, which will be the case for most MetaFilter instances.

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

Concrete Methods¶

MetaFilter.filter_data(data: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]¶

Apply the specified filter to the data, callable publicly. Actual filtering should be defined in private API.

Parameters:: data (npt.NDArray[np.float64]) – The data to be filtered
Returns:: The filtered data
Return type:: npt.NDArray[np.float64]

MetaFilter.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

MetaFilter.get_callable_filter() → Callable¶

Return a function that can be called to filter data on the fly using this filter object properties

Returns:: A function that can be called to filter a 1-d npt.NDArray[np.float64] object
Return type:: Callable

MetaFilter.report_channel_status(channel: int | None = None, init: bool = 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

Private Methods¶

Abstract Methods¶

These methods must be implemented by subclasses.

abstractmethod MetaFilter._apply_filter(data: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]¶

Purpose: Called to actually filter or otherwise preprocess data

Take in a 1D timeseries and apply the filter or preprocessing step provided by your plugin.

Parameters:: data (npt.NDArray[np.float64]) – The data to be filtered
Returns:: The filtered data
Return type:: npt.NDArray[np.float64]

abstractmethod MetaFilter._finalize_initialization() → None¶

Purpose: Perform generic class construction operations after settings are applied. This function is called at the end of the apply_settings() function to perform additional initialization specific to the algorithm being implemented.

Perform any initialization tasks required after settings are applied. You can access the values in the settings dict provided as needed in the class variable self.settings[key]['Value'] where key corresponds to the keys in the provided settings dict (as provided to apply_settings() or to the constructor). You can freely make class variables here and you can assume (if using the poriscope app) that this will only be called from a single thread. .

Should Raise if initialization fails.

abstractmethod MetaFilter._init() → None¶

Purpose: Perform generic class construction operations before settings are applied.

This is called immediately at the start of class creation but before settings have been applied, and is used to do whatever is required to set up your reader. Note that no app settings are available when this is called, so this function should be used only for generic class construction operations. Most filters simply pass this function.

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

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

Parameters:: settings (dict) – Parameters required to configure this filter.
Raises:: ValueError – If the settings dict does not contain the correct information.

Concrete Methods¶

MetaFilter.__init__(settings: dict | None = None) → None¶

Initialize the MetaFilter instance.

Parameters:: settings (Optional[dict]) – A dict specifying the parameters of the filter to be created. Required keys depend on subclass.