SQLiteEventLoader¶

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

Subclass of MetaEventLoader for loading event data from SQLite databases.

This class provides methods to extract, filter, and stream event data stored in SQLite databases generated by Poriscope. It supports efficient querying and generator-based iteration over large event datasets.

Public Methods¶

SQLiteEventLoader.close_resources(channel: int | None = None) → None¶: Perform any actions necessary to gracefully close resources before app exit

SQLiteEventLoader.get_channels() → List[int]¶

Return the keys of valid channels in the reader

Returns:

keys of valid channels in the reader

Return type:

List[int]

Raises:

ValueError – if no channels are found
sqlite3.Error – if a database operation fails
Exception – if an unexpected error occurs while fetching channels

SQLiteEventLoader.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 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. 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’

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.

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

SQLiteEventLoader.get_num_events(channel: int) → int¶

get the number of events available in the given channel

Parameters:

channel (int) – the channel to consider

Returns:

The number of events in the channel for the given experiment

Return type:

int

Raises:

sqlite3.Error – if a database operation fails
Exception – if an unexpected error occurs while counting events

SQLiteEventLoader.get_samplerate(channel: int) → float¶

Return the sampling rate for the channel.

Parameters:

channel (int) – the channel to consider

Returns:

Sampling rate for the dataset.

Return type:

float

Raises:

ValueError – if no samplerate is found for the given channel
sqlite3.Error – if a database operation fails
Exception – if an unexpected error occurs while fetching the samplerate

SQLiteEventLoader.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
sqlite3.Error – if a database operation fails
Exception – if an unexpected error occurs while fetching event ids

Purpose Return a list of indices corresponding to the id of events within the given channel. channel is required; there is no “all channels” mode.

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

Parameters:

channel (int) – channel number from which to load data.
index (int) – The unique identifier for the event to load
data_filter (Optional[Callable]) – an optional filter function to apply to the data before it is returned

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

Raises:

IndexError – if no event with the given index exists for the given channel
ValueError – if a value error occurs while loading the event
sqlite3.Error – if a database operation fails
Exception – if an unexpected error occurs while loading the event

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
     }

SQLiteEventLoader.reset_channel(channel: int | None = None) → None¶: Perform any actions necessary to gracefully close resources before app exit

Private Methods¶

SQLiteEventLoader._finalize_initialization() → None¶

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.

SQLiteEventLoader._init() → None¶

Purpose: Perform generic class construction operations.

All data plugins have this function and must provide an implementation. 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.

SQLiteEventLoader._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:: KeyError – If the settings dict does not contain the correct information.