NanoTrees¶

class NanoTrees(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¶

NanoTrees.close_resources(channel: int | None = None) → None¶

Perform any actions necessary to gracefully close resources before app exit. If channel is not None, handle only that channel, else close all of them.

Parameters:: channel (Optional[int]) – channel ID

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

Construct an array of data corresponding to the fit 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 fitted data for the event, or None if fitting is not complete or the event was rejected

Return type:

Optional[NDArray[np.float64]]

Raises:

AttributeError – if this instance is not linked to a MetaEventLoader

NanoTrees.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:

Smallest Significant Sublevel (pA) - the shallowest step the tree is allowed to keep as a real sublevel.
Time Scaling - the factor by which the significance a sublevel must reach grows with its duration, so a brief step is held to a stricter standard than a long one.
Exceptional Sublevel Sensitivity - how far a candidate may fall short of Smallest Significant Sublevel and still be kept when the fit otherwise supports it.

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

NanoTrees.get_rise_time(data: ndarray[tuple[int, ...], dtype[_ScalarType_co]]) → int¶: estimte the system rise time

NanoTrees.get_skip_region(data: ndarray[tuple[int, ...], dtype[_ScalarType_co]], quantile: float = 0.95) → int¶: estimate region to skip when averaging from the system rise time

NanoTrees.l50_max_height(settings: dict, sublevel: ndarray[tuple[int, ...], dtype[_ScalarType_co]], previousHeight: float | None = None) → float¶: # Height Function used to estimate the current level within short sublevels

Private Methods¶

NanoTrees._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]]]

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

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

NanoTrees._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]]]

NanoTrees._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]]

NanoTrees._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 (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]]

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

NanoTrees._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 (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, NDArray[Numeric]]

NanoTrees._post_process_events(channel: int) → None¶

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

NanoTrees._pre_process_events(channel: int) → None¶

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

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