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: int | None = None) → None¶

Commit and close the shared database connection/cursor, if open.

Parameters:: channel (Optional[int]) – unused; this writer shares a single connection across all channels, so there is no per-channel resource to close independently.

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

Declare the settings this database writer exposes, on top of the base contract.

Called by poriscope when the plugin is instantiated or reconfigured, to build the settings dialog and to sanity-check whatever the user enters; the accepted values are then readable through self.settings. See get_empty_settings() for the structure of the dict and what Type, Value, Min, Max, Options and Units mean in it, and for the reserved keys the GUI builds file pickers from.

The super() call supplies the mandatory "MetaEventFitter" key, which is how this plugin is wired to its data source.

The keys this plugin adds:

Output File - the SQLite database to write fitted events and their sublevels into.
Experiment Name - the label these events are filed under, so one database can hold several runs.
Voltage (mV) - the applied bias, stored with the experiment.
Membrane Thickness (nm) and Conductivity (S/m) - stored with the experiment so that downstream analysis can convert blockage depths into pore and molecule geometry.

Parameters:

globally_available_plugins (Optional[Dict[str, List[str]]]) – a dict containing all data plugins that exist to date, keyed by metaclass. Must include “MetaEventFitter” as a key, with explicitly set Type MetaEventFitter.
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]]

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

Permanently delete the given channel’s row (and, via cascading foreign keys, its events/sublevels/data rows) from the database, so a subsequent write starts from a clean slate. This is destructive, not a resource-cleanup step.

Parameters:

channel (Optional[int]) – channel ID. Note that channel=None does not reset all channels; SQL channel_id = NULL never matches, so no rows are deleted.

Raises:

RuntimeError – if the configured experiment cannot be found in the database
sqlite3.Error – if the delete fails, so that the caller cannot treat an unreset channel as a clean slate

Private Methods¶

SQLiteDBWriter._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.

SQLiteDBWriter._initialize_database(channel: int | None = 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

Raises:

ValueError – if event or sublevel metadata declares an unsupported datatype
RuntimeError – if database initialization fails at the SQL level
sqlite3.Error – if a database operation fails
Exception – if an unexpected error occurs during initialization

SQLiteDBWriter._validate_settings(settings: dict) → None¶

Refuse an existing output file that is not a fitted-metadata database.

A new or empty file is created as one, and an existing metadata database is appended to. Anything else is refused here, when the plugin is configured, rather than failing on every channel once writing starts - an events database from the Raw Data tab in particular, which also has an events table.

Parameters:: settings (dict) – Parameters for event detection.
Raises:: ValueError – If the output file exists and is not an SQLite database, or is one without the fitted-metadata tables.

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

Raises:

RuntimeError – if the configured experiment cannot be found in the database
sqlite3.Error – if a database operation fails

SQLiteDBWriter._write_event(channel: int, event_metadata: Dict[str, int | float | str | bool], sublevel_metadata: Dict[str, List[int | float | str | bool]], event_data: ndarray[tuple[int, ...], dtype[float64]], raw_data: ndarray[tuple[int, ...], dtype[float64]], fit_data: ndarray[tuple[int, ...], dtype[float64]], abort: bool | None = False, last_call: bool | None = False) → bool¶

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
event_metadata (Dict[str, Union[int, float, str, bool]]) – a dict of metadata associated to the event
sublevel_metadata (Dict[str, List[Union[int, float, str, bool]]]) – 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 filtered data for the event
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 if the row already existed (rejected by INSERT OR IGNORE). Any other failure (a genuine database error) is raised rather than returned, so the caller can report the real reason instead of assuming a duplicate row.

Return type:

bool

Raises:

ValueError – if a database connection cannot be opened
RuntimeError – if the experiment or channel cannot be found in the database, or if the event insert reports success without producing a row id
sqlite3.Error – if a database operation fails
Exception – if an unexpected error occurs while writing the event

SQLiteDBWriter._write_experiment_metadata(channel: int | None = None) → None¶

Write any information you need to save about the experiment itself

Parameters:: channel (Optional[int]) – int indicating which output to flush
Raises:: sqlite3.Error – if a database operation fails