SQLiteDBWriter¶

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

Abstract base class for database writer that will store metadata and data from fitted events for postprocessing later

Public Methods¶

SQLiteDBWriter.close_resources(channel=None) → None¶

Perform any actions necessary to gracefully close resources before app exit. If channel is not None, handle only that channel; otherwise, close all channels.

Parameters:: channel (int) – channel ID

SQLiteDBWriter.get_empty_settings(globally_available_plugins=None, standalone=False)¶

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. EventFinder objects MUST include a MetaReader object in settings

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 (Mapping[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:

Mapping[str, Mapping[str, Union[int, float, str, list[Union[int,float,str,None], None]]]]

SQLiteDBWriter.reset_channel(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 (int) – channel ID

Private Methods¶

SQLiteDBWriter._column_exists(cursor, table_name, column_name)¶

Check whether a given column exists in the specified database table.

Parameters:

cursor (sqlite3.Cursor) – SQLite database cursor used to execute the query.
table_name (str) – Name of the table to inspect.
column_name (str) – Name of the column to check for existence.

Returns:

True if the column exists, False otherwise.

Return type:

bool

SQLiteDBWriter._init()¶

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.

SQLiteDBWriter._initialize_database(channel: int | None = None)¶

Do whatever you need to do to initialize the database file for a given channel before writing the first event

Parameters:: channel (Optional[int]) – int indicating which output to flush

SQLiteDBWriter._insert_event(cursor, event_metadata, experiment_id, channel_db_id)¶

Insert event metadata into the ‘events’ table. Return True on success, False on failure.

Parameters:

cursor (sqlite3.Cursor) – The SQLite cursor to execute the query.
event_metadata (Mapping[str, Union[int, float, str, bool]]) – A dictionary of metadata associated with the event.
experiment_id (int) – The ID of the experiment for which the event is being logged.

Returns:

True on success, False on failure

Return type:

bool

SQLiteDBWriter._insert_event_data(cursor, event_metadata, event_data, raw_data, fit_data, experiment_id, channel_db_id, event_db_id)¶

Insert the event data into the ‘data’ table after converting it to the appropriate binary format.

Parameters:

cursor (sqlite3.Cursor) – The SQLite cursor to execute the query.
event_metadata (Mapping[str, Union[int, float, str, bool]]) – A dictionary of metadata associated with the event.
event_data (np.ndarray) – A numpy array of filtered event data to be stored as binary in the database.
raw_data (np.ndarray) – A numpy array of raw event data to be stored as binary in the database.
fit_data (np.ndarray) – A numpy array of fitted event data to be stored as binary in the database.
experiment_id (int) – The ID of the experiment to which the data belongs.
channel (int) – The channel ID to associate with the event data.

Returns:

True on success, False on failure

Return type:

bool

SQLiteDBWriter._insert_sublevels(cursor, sublevel_metadata, experiment_id, channel_db_id, event_db_id)¶

Insert sublevel metadata into the ‘sublevels’ table.

Parameters:

cursor (sqlite3.Cursor) – The SQLite cursor to execute the query.
sublevel_metadata (Mapping[str, List[Union[int, float, str, bool]]]) – A dictionary of sublevel metadata, where each key corresponds to a list of values.
experiment_id (int) – The ID of the experiment for which the sublevels are being logged.

Returns:

True on success, False on failure

Return type:

bool

SQLiteDBWriter._validate_settings(settings)¶

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.

SQLiteDBWriter._write_channel_metadata(channel: int) → None¶

Write any information you need to save about the channel

Parameters:: channel (int) – int indicating which output to flush

SQLiteDBWriter._write_event(channel, event_metadata, sublevel_metadata, event_data, raw_data, fit_data, abort=False, last_call=False)¶

Write a single event worth of data and metadata to the database. Do NOT commit.

Parameters:

channel (int) – identifier for the channel to write events from
data (numpy.ndarray) – 1D numpy array of data to write to the active file in the specified channel.
event_metadata (Mapping[str, List[Union[int, float, str, bool]]]) – a dict of metadata associated to the event
event_metadata – a dict of lists of metadata associated to sublevels within the event. You can assume they all have the same length.
event_data (npt.NDArray[np.float64]) – the raw data for the event (not filtered)
raw_data (npt.NDArray[np.float64]) – A numpy array of raw event data to be stored as binary in the database.
fit_data (npt.NDArray[np.float64]) – A numpy array of fitted event data to be stored as binary in the database.
abort (Optional[bool]) – True if an abort request was issued in the caller, perform cleanup as needed
last_call (Optional[bool]) – True if this is the last time the function will be called, commit to file and clean up as needed

Returns:

True on successful write, False on failure or ignore

Return type:

bool

SQLiteDBWriter._write_experiment_metadata(channel=None) → None¶

Write any information you need to save about the experiment itself

Parameters:: channel (int) – int indicating which output to flush