ClassicBlockageFinder¶

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

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

Private Methods¶

ClassicBlockageFinder._filter_events(event_starts: List[int], event_ends: List[int], channel: int, last_end=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) – Bool indicating whether this is the first chunk of data in the series to be analyzed
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:

Tuple[List[int], List[str]]

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:

tuple[List[int], List[int],bool]

ClassicBlockageFinder._gaussian(x: float, A: float, m: float, s: float) → float¶

Evaluate a Gaussian function at a given point.

Parameters:

x (float) – Input value at which to evaluate the function.
A (float) – Amplitude of the Gaussian.
m (float) – Mean (center) of the Gaussian.
s (float) – Standard deviation (spread) of the Gaussian.

Returns:

Value of the Gaussian function at x.

Return type:

float

ClassicBlockageFinder._gaussian_fit(histogram: ndarray[tuple[int, ...], dtype[int64]], bins: ndarray[tuple[int, ...], dtype[float64]], mean_guess: float, stdev_guess: float) → tuple[float, float, float]¶

Fit a Gaussian function to histogram data using a linearized least squares approach.

Parameters:

histogram (npt.NDArray[np.int64]) – Array of counts in each histogram bin.
bins (npt.NDArray[np.float64]) – Center positions of histogram bins.
mean_guess (float) – Initial estimate of the Gaussian mean.
stdev_guess (float) – Initial estimate of the Gaussian standard deviation.

Returns:

Tuple containing (amplitude, mean, standard deviation) of the fitted Gaussian.

Return type:

tuple[float, float, float]

Raises:

ValueError – If standard deviation guess is invalid or the fit fails.

ClassicBlockageFinder._get_baseline_stats(data: ndarray[tuple[int, ...], dtype[float64]]) → tuple[float, float]¶

Get the local amplitude, mean, and standard deviation for a chunk of data. Assumes data is rectified.

Parameters:: data (npt.NDArray[np.float64]) – Chunk of timeseries data to compute statistics on.
Returns:: Tuple of mean and standard deviation of the baseline.
Return type:: tuple[float, float]

ClassicBlockageFinder._init() → None¶: called at the start of base class initialization

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