SQLiteEventWriter

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

Bases: MetaWriter

Save events into a single file with baseline between them discarded

Public Methods

SQLiteEventWriter.close_resources(channel: int | None = None) → None

Do whatever needs doing to gracefully shut down on app exit

Parameters:

channel (Optional[int]) – channel ID

SQLiteEventWriter.get_committed_experiment_name(channel: int) → str | None

Name the experiment the output already holds channel under, if it does.

channels.channel_id is unique, so a file holds at most one row per channel and this reads its name. A file that does not exist yet, or has no channels table, holds no channel - and is not created by asking.

Parameters:

channel (int) – the channel to look up

Returns:

the stored experiment name, or None if the output does not hold the channel

Return type:

Optional[str]

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

Declare the settings this event 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 "MetaEventFinder" key, which is how this plugin is wired to its data source.

The keys this plugin adds:

  • Output File - the SQLite database to write events 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 “MetaEventFinder” as a key, with explicitly set Type MetaEventFinder.

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

SQLiteEventWriter.get_output_file_name() → Path

get the name of the output file

SQLiteEventWriter.reset_channel(channel: int | None = None) → None

Permanently delete the given channel’s row (and, via cascading foreign keys, its associated event rows) from the database, so a subsequent write starts from a clean slate. This is destructive, not a resource-cleanup step. The rows written afterwards take new id values rather than the deleted ones: AUTOINCREMENT never reuses a row id, and events are addressed by (channel_id, event_id), whose event_id does start again.

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:

  • ValueError – if settings have not been initialized or the output file path is not set in settings

  • sqlite3.Error – if the delete fails, so that the caller cannot treat an unreset channel as a clean slate

Private Methods

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

SQLiteEventWriter._init() → None

called at the start of base class initialization

SQLiteEventWriter._initialize_database(channel: int) → None

Open a database or file handle for writing events - this function will be called from every channel in the reader

Parameters:

channel (int) – the channel for which to initialize the database

Raises:

  • ValueError – if the output file path is not set in settings

  • RuntimeError – if database initialization fails at the SQL level

  • sqlite3.Error – if a database operation fails

  • Exception – if an unexpected error occurs during initialization

SQLiteEventWriter._set_output_dtype() → str

set the output dtype - should be a numpy numeric type:

self.output_dtype = ‘<u2’

SQLiteEventWriter._validate_settings(settings: dict) → None

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

An existing output file of another kind is refused by _refuse_an_output_file_of_another_kind, which raises ValueError.

Parameters:

settings (dict) – Parameters for event detection.

Raises:

KeyError – If the settings dict does not contain the correct information.

SQLiteEventWriter._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:

  • ValueError – if settings are not initialized or required settings are missing

  • RuntimeError – if the channel’s database ID cannot be determined after insertion

  • sqlite3.Error – if a database operation fails

SQLiteEventWriter._write_data(event: Dict[str, Any], channel: int, index: int, abort: bool | None = False, last_call: bool | None = False) → bool

Append one event’s samples and metadata to the active database file.

The event’s keys are the contract, and are documented on MetaWriter._write_data. data arrives in pA and is stored as it is.

Parameters:

  • event (Dict[str, Any]) – One event, as get_single_event_data builds it.

  • channel (int) – Int indicating the channel from which it was acquired.

  • index (int) – event index

  • abort (Optional[bool]) – True to discard the channel’s uncommitted batch and stop.

  • last_call (Optional[bool]) – True when this is the final event of the channel.

Returns:

success of the write operation.

Return type:

bool

Raises:

  • ValueError – if a database connection cannot be opened, or if start_sample, padding_before, or padding_after is None

  • sqlite3.Error – if a database operation fails

  • Exception – if an unexpected error occurs during the write