Basic_PeakFinder¶

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

Abstract base class to analyze and flag the start and end times of regions of interest in a timeseries for further analysis.

Public Methods¶

Basic_PeakFinder.close_resources(channel: int | None = None) → None¶: Perform any actions necessary to gracefully close resources before app exit

Basic_PeakFinder.construct_fitted_event(channel: int, index: int) → ndarray[tuple[int, ...], dtype[float64]] | None¶

Construct an array of data corresponding to the peaks for the specified event

Parameters:

channel (int) – analyze only events from this channel
index (int) – the index of the target event

Returns:

numpy array of peaked data for the event, or None

Return type:

Optional[npt.NDArray[np.float64]]

Raises:

RuntimeError – if peakfinding is not complete yet

Basic_PeakFinder.enumerate_peaks(sublevel_starts: List[Dict[str, Any]], num_states: int, sublevel_types: List[str] | None = None) → List[int | None]¶

Assign unique peak IDs to sublevels labeled as ‘peak’.

Parameters:

sublevel_starts (List[Dict[str, Any]]) – List of dictionaries describing sublevels, each with a ‘type’ key.
num_states (int) – Total number of sublevels to process.
sublevel_types (Optional[List[str]]) – List of sublevel types (‘peak’ or ‘event_baseline’). If None, falls back to edge type checking.

Returns:

List of peak IDs or None for non-peak sublevels.

Return type:

List[Optional[int]]

Basic_PeakFinder.find_mode_blockage_level(data: ndarray[tuple[int, ...], dtype[float64]] | None, baseline_mean: float | None, baseline_std: float | None) → float¶

Estimate the level of unfolded blockage based on data distribution.

Parameters:

data (Optional[npt.NDArray[np.float64]]) – Array of current values or similar signal to analyze.
baseline_mean (Optional[float]) – Mean value of the baseline level.
baseline_std (Optional[float]) – Standard deviation of the baseline level.

Returns:

Estimated unfolded blockage level.

Return type:

float

Basic_PeakFinder.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 fitter 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 "MetaEventLoader" key, which is how this plugin is wired to its data source.

The keys this plugin adds:

Plot Features - how much of the detection geometry to draw over the event: All, Some or None.
Min Height (pA) - the smallest absolute depth a peak may have.
Min Prominence (pA) - how far a peak must stand out from the surrounding signal, which is what separates a real peak from a ripple on a broader one.
Relative Height - the fraction of the prominence at which each peak’s width is measured.
Window Length (μs) - the span scipy.signal.find_peaks searches when computing prominence.
Width (μs) - the narrowest peak that will be accepted.
Min Distance (μs) - the closest two accepted peaks may be.
Plateau Size (μs) - the flat top a peak must have to be accepted; 0 accepts any.

Parameters:

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

Get a list of horizontal and vertical lines and associated labels to overlay on the graph generated by construct_fitted_event()

Parameters:

channel (int) – analyze only events from this channel
index (int) – the index of the target event

Returns:

a list of x locations to plot vertical lines and a list of y locations to plot horizontal lines, list of tuples to plot little x’s, labels for the vertical lines, labels for the horizontal lines, labels for x’s. Must be lists of equal length, or None

Return type:

Tuple[Optional[List[float]], Optional[List[float]], Optional[List[Tuple[float, float]]], Optional[List[str]], Optional[List[str]], Optional[List[str]]]

Private Methods¶

Basic_PeakFinder._define_event_metadata_types() → Dict[str, Type[int | float | str | bool]]¶

Build a dict of metadata along with associated datatypes for use by the database writer downstream. Keys must match columns defined in _populate_event_metadata() All of this metadata must be populated during fitting. Options for dtypes are int, float, str, bool

Returns:: a dict of metadata keys and associated base dtypes
Return type:: Dict[str, Type[Union[int, float, str, bool]]]

Basic_PeakFinder._define_event_metadata_units() → Dict[str, str | None]¶

Returns:: a dict of metadata keys and associated base dtypes
Return type:: Dict[str, Optional[str]]

Basic_PeakFinder._define_sublevel_metadata_types() → Dict[str, Type[int | float | str | bool]]¶

Build a dict of sublevel metadata along with associated datatypes for use by the database writer downstream. Keys must match columns defined in _populate_sublevel_metadata() All of this metadata must be populated during fitting. Options for dtypes are int, float, str, bool. Note that this is the type of entries in the associated list, it should not include the list element

Returns:: a dict of metadata keys and associated base dtypes
Return type:: Dict[str, Type[Union[int, float, str, bool]]]

Basic_PeakFinder._define_sublevel_metadata_units() → Dict[str, str | None]¶

Build a dict of sublevel metadata units , or None if unitless. Keys must match columns defined in _populate_sublevel_metadata() All of this metadata must be populated during fitting. it should not include the list element

Returns:: a dict of metadata keys and associated base dtypes
Return type:: Dict[str, Optional[str]]

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

Get a list of indices corresponding to the starting point of all sublevels within an event. Will be pre-pended with 0 if 0 is not the first entry. Plugin must handle gracefully the case where any of the arguments except data are None, as not all event loaders are guaranteed to return these values. Raising an an acceptable handler.

Parameters:

data (npt.NDArray[np.float64]) – an array of data from which to extract the locations of sublevel transitions
samplerate (float) – the sampling rate
padding_before (Optional[int]) – the number of data points before the estimated start of the event in the chunk
padding_after (Optional[int]) – the number of data points after the estimated end of the event in the chunk
baseline_mean (Optional[float]) – the local mean value of the baseline current
baseline_std (Optional[float]) – the local standard deviation of the baseline current

Returns:

a list of integers corresponding to sublevel transitions

Return type:

Optional[List[Any]]

Raises:

ValueError – if the event is rejected. Note that ValueError will skip and reject the event but will not stop processing of the rest of the dataset

Assemble a list of metadata to save in the event database later. Note that keys ‘start_time_s’ and ‘index’ are already handled in the base class and should not be touched here.

Parameters:

data (npt.NDArray[np.float64]) – an array of data from which to extract the locations of sublevel transitions
samplerate (float) – the sampling rate
baseline_mean (Optional[float]) – the local mean value of the baseline current
baseline_std (Optional[float]) – the local standard deviation of the baseline current
sublevel_metadata (Dict[str, List[Numeric]]) – the dict of sublevel metadata built by self._populate_sublevel_metadata()

Returns:

a dict of event metadata values

Return type:

Dict[str, Union[int, float, str, bool]]

Basic_PeakFinder._populate_sublevel_metadata(data: ndarray[tuple[int, ...], dtype[float64]], samplerate: float, baseline_mean: float | None, baseline_std: float | None, sublevel_starts: List[Any]) → Dict[str, ndarray[tuple[int, ...], dtype[int | float | number]]]¶

Build a dict of lists of sublevel metadata with whatever arbitrary keys you want to consider in your event fitter. Every list must have one value per sublevel - one fewer than the entries in sublevel_starts, whose last entry is the terminal boundary. Note that ‘index’ is already handled in the base class

Parameters:

data (npt.NDArray[np.float64]) – an array of data from which to extract the locations of sublevel transitions
samplerate (float) – the sampling rate
baseline_mean (Optional[float]) – the local mean value of the baseline current
baseline_std (Optional[float]) – the local standard deviation of the baseline current
sublevel_starts (List[Any]) – the list of sublevel start indices located in self._locate_sublevel_transitions()

Returns:

a dict of lists of sublevel metadata values, one list entry per sublevel for each piece of metadata

Return type:

Dict[str, npt.NDArray[Numeric]]

Basic_PeakFinder._post_process_events(channel: int) → None¶

Parameters:: channel (int) – the index of the channel to postprocess

Basic_PeakFinder._pre_process_events(channel: int) → None¶

Parameters:: channel (int) – the channel to preprocess

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