ClassicBlockageFinder¶
class ClassicBlockageFinder(settings: Optional[dict] = None)
Bases: MetaEventFinder
Event finder plugin for detecting transient blockages in nanopore signals using a threshold-based approach.
This subclass of MetaEventFinder implements a classic event detection strategy, where events are identified by thresholding rectified signal traces. The start and end of events are determined using hysteresis and configurable settings such as threshold, minimum/maximum duration, and minimum separation.
Core features: - Event detection based on baseline-normalized threshold crossings. - Configurable minimum and maximum event durations and separation. - Histogram-based baseline estimation with optional Gaussian fitting. - Supports chunked data processing with entry state handling across segments.
Required settings: - Threshold (in pA) - Min Duration (in µs) - Max Duration (in µs) - Min Separation (in µs) - MetaReader reference for data access
This class can be extended (e.g., BoundedBlockageFinder) to impose additional constraints such as baseline range limits.
Public Methods¶
- ClassicBlockageFinder.close_resources(channel: int | None = None) None¶
Perform any actions necessary to gracefully close resources before app exit
- Parameters:
channel (Optional[int]) – the channel identifier
- ClassicBlockageFinder.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 finder 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. Seeget_empty_settings()for the structure of the dict and whatType,Value,Min,Max,OptionsandUnitsmean in it, and for the reserved keys the GUI builds file pickers from.The
super()call supplies the mandatory"MetaReader"key, which is how this plugin is wired to its data source, and"Threshold", which the base declares without a unit because the base loop reads it; this plugin sets the unit.The keys this plugin adds or configures:
Threshold(pA) - how far below the fitted baseline the signal must fall for an event to start, in absolute current.Min Duration/Max Duration(us) - events outside this range are rejected.Min Separation(us) - two events closer together than this are rejected rather than merged.
- 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:
Private Methods¶
- ClassicBlockageFinder._filter_events(event_starts: List[int], event_ends: List[int], channel: int, last_end: int = 0) Tuple[List[int], List[str]]¶
Remove entries from self.event_starts and self.event_ends list based on any filter criteria defined in user settings
- Parameters:
event_starts (List[int]) – a list of starting data indices for events. You may assume that event_starts[0] < event_ends[0]. It is possible that there will be one more entry in this list than in event_ends.
event_ends (List[int]) – a list of ending data indices for events. You may assume that event_starts[0] < event_ends[0]
channel (int) – The channel index being processed. Unused by this implementation.
last_end (int) – the index of the end of the last accepted event
- Returns:
A list of indices to reject from the given list of event starts and ends, and a list of reason for rejection
- Return type:
- Raises:
RuntimeError – if no reader plugin has been set on this event finder
- ClassicBlockageFinder._find_events_in_chunk(data: ndarray[tuple[int, ...], dtype[float64]], mean: float, std: float, offset: int, entry_state: bool = False, first_chunk: bool = False) Tuple[List[int], List[int], bool]¶
Find the start and end points of events in the provided chunk of data and returns them as separate lists, along with a boolean indicating whether or not the chunk ended in the middle of an event. Should backtrack data to the baseline, since padding logic will assume that it can use data right up to the start and end found as baseline by default
- Parameters:
data (npt.NDArray[np.float64]) – Chunk of timeseries data to analyze. Assume it is rectified so that a blockage will always represent a reduction in absolute value.
mean (float) – Mean of the baseline on the given chunk. Must be positive.
std (float) – Standard deviation of the baseline on the given chunk
offset (int) – the index of the start of the chunk in the global dataset
entry_state (bool) – Bool indicating whether we start in the middle of an event (True) or not (False)
first_chunk (bool) – Bool indicating whether this is the first chunk of data in the series to be analyzed
- Raises:
ValueError – If event_params are invalid.
- Returns:
Lists of event start and end indices, and boolean entry state.
- Return type:
- ClassicBlockageFinder._get_baseline_stats(data: ndarray[tuple[int, ...], dtype[float64]]) tuple[float, float]¶
Get the local mean and standard deviation for a chunk of data. Assumes data is rectified.
The range is taken from the chunk itself, so every sample contributes; a finder that wants to restrict what counts as baseline overrides this and narrows the range it asks for. A chunk with no variation in it has no histogram to fit, and
_fit_baseline_histogram()raisesValueErrorfor it.