MetaEventLoader¶

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

Bases: BaseDataPlugin

What you get by inheriting from MetaEventLoader¶

MetaEventLoader is the base class for loading the data written by a MetaWriter subclass instance or any other method that produces an equivalent format.

Poriscope ships with SQLiteEventLoader, a subclass of MetaEventLoader that reads data written by the SQLiteDBWriter subclass. While additional subclasses can read almost any format you desire, we strongly encourage standardization around this format. Think twice before creating additional subclasses of this base class. It is not sufficient to write just a MetaEventLoader subclass. In addition to this base class, you will also need a paired MetaWriter subclass to write data in your target format.

Public Methods¶

Abstract Methods¶

These methods must be implemented by subclasses.

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

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

Purpose: Clean up any open file handles or memory on app exit.

This is called during app exit or plugin deletion to ensure proper cleanup of resources that could otherwise leak. Do this for all channels if no channel is specified, otherwise limit your closure to the specified channel. If no such operation is needed, it suffices to pass.

abstractmethod MetaEventLoader.get_channels() → List[int]¶

Returns:: keys of valid channels in the reader
Return type:: List[int]

Purpose: Get a list of all valid channel identifiers in the dataset

abstractmethod MetaEventLoader.get_num_events(channel: int) → int¶

Parameters:: channel (int) – the channel to consider
Returns:: The number of events in the channel
Return type:: int

Purpose: Return the number of events that exist in the specified channel

abstractmethod MetaEventLoader.get_samplerate(channel: int) → float¶

Parameters:: channel (int) – the channel to consider
Returns:: Sampling rate for the dataset.
Return type:: float

Purpose: Return the sampling rate used for event data in the specified channel

abstractmethod MetaEventLoader.get_valid_indices(channel: int) → List[int]¶

Parameters:: channel (int) – channel number from which to load data.
Returns:: A list of event ids
Return type:: List[int]
Raises:: ValueError if no event_ids exist

Purpose Return a list of indices correspond to the id of events within the given channel, or a list of all valid indices in the database if channel is not specified

abstractmethod MetaEventLoader.load_event(channel: int, index: int, data_filter: Callable | None = None) → Dict[str, int | float | ndarray[tuple[int, ...], dtype[float64]]]¶

Parameters:

channel (int) – channel number from which to load data.
index (int) – The unique identifier for the event to load

Returns:

data and context corresponding to the event, with baseline padding before and after

Return type:

Dict[str, Union[npt.NDArray[np.float64], int, float]]

Purpose: Load the data and metadata associated with a single specified event

Return the data and context for the event identified by index, optionally first applying a filter or preprofessing function to the data returned. You are responsible for raising an appropriate error if the index provided is invalid. The data must be returned as a dict with at least the following keys:

event = {
         'data': npt.NDArray[np.float64],  # the data in pA
         'absolute_start': int,             # the start index of the event relative to the start of the experiment
         'padding_before': int,            # number of data points in event['data'] before the event start estimate
         'padding_after': int,             # number of data points in event['data'] after the event end estimate
         'baseline_mean': float,           # local baseline mean value in pA - can be estimated from the padding if need be
         'baseline_std': float             # local baseline standard deviation in pA - can be estimated from the padding if need be
     }

Concrete Methods¶

MetaEventLoader.force_serial_channel_operations() → bool¶

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

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

MetaEventLoader.get_base_file() → Path¶

Return the full path to the file used to initiate this reader

Returns:: path to the file used to initiate the reader
Return type:: Path

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

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]]

Purpose: Provide a list of settings details to users to assist in instantiating an instance of your MetaWriter 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. 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
                               },
               ...
               }

Several parameter keywords are reserved: these are

‘Input File’ ‘Output File’ ‘Folder’

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

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.

While this function is technically not abstract in MetaEventLoader, which already has an implementation of this function that ensures that settings will have the required Input File key available to users, in most cases you will need to override it to add any other settings required by your subclass or to specify which files types are allowed. If you need additional settings, which you almost certainly do, you MUST call super().get_empty_settings(globally_available_plugins, standalone) before any additional code that you add. For example, your implementation could look like this, to limit it to sqlite files:

settings = super().get_empty_settings(globally_available_plugins, standalone)
settings["Input File"]["Options"] = [
                        "SQLite3 Files (*.sqlite3)",
                        "Database Files (*.db)",
                        "SQLite Files (*.sqlite)",
                        ]
return settings

which will ensure that your have the Input File key and limit visible options to sqlite3 files. By default, it will accept any file type as output, hence the specification of the Options key for the relevant plugin in the example above.

MetaEventLoader.get_event_generator(channel: int, data_filter: Callable | None = None) → Generator[Dict[str, ndarray[tuple[int, ...], dtype[_ScalarType_co]] | float | int], bool, None]¶

Parameters:

channel (int) – channel index to analyze.
data_filter (Optional[Callable]) – a filter function to apply to the data that is returned

Returns:

Generator yielding event data.

Return type:

Generator[Dict[str, Union[npt.NDArray, float, int]], bool, None]

Purpose: Load the all events in a specified channel and yield them to the caller one at a time

For each event in the specified channel, yield the data and context for the event identified by index, optionally first applying a filter or preprofessing function to the data returned. You are responsible for raising an appropriate error if the index provided is invalid. The data must be yielded as a dict with at least the following keys:

event = {
    'data': npt.NDArray[np.float64],  # the data in pA
    'absolute_start': int,             # the start index of the event relative to the start of the experiment
    'padding_before': int,            # number of data points in event['data'] before the event start estimate
    'padding_after': int,             # number of data points in event['data'] after the event end estimate
    'baseline_mean': float,           # local baseline mean value in pA - can be estimated from the padding if need be
    'baseline_std': float            # local baseline standard deviation in pA - can be estimated from the padding if need be
}

A reasonable (though possibly inefficient) implementation would acquire a list of valid event IDs in the channel and then

indices = [[get a list of valid indices for the channel]]
for index in indices:
    yield self.load_event(channel, index, data_filter)

The generator should cancel and exhaust itself in the event True is passed back through generator.send()

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

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

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

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 reset all of them. In most cases for MetaEventLoaders there is no need to reset and you can simplt pass.

Private Methods¶

Abstract Methods¶

These methods must be implemented by subclasses.

abstractmethod MetaEventLoader._init() → None¶

Purpose: Perform generic class construction operations.

This is called immediately at the start of class creation 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 readers simply pass this function.

abstractmethod MetaEventLoader._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¶

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

Initialize the MetaEventLoader instance.

Initialize instance attributes based on provided parameters and perform initialization tasks.

Parameters:: settings (dict) – an optional dict conforming to that which is required by the self.get_empty_settings() function

MetaEventLoader._finalize_initialization() → None¶

Purpose: Apply application-specific settings to the plugin, if needed.

If additional initialization operations are required beyond the defaults provided in BaseDataPlugin or MetaEventLoader that must occur after settings have been applied to the reader instance, you can override this function to add those operations, subject to the caveat below.

Warning

This function implements core functionality required for broader plugin integration into Poriscope. If you do need to override it, you MUST call super()._finalize_initialization() before any additional code that you add, and take care to understand the implementation of both apply_settings() and _finalize_initialization() before doing so to ensure that you are not conflicting with those functions.