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 (int) – channel ID

NanoTrees.construct_fitted_event(channel, index)¶

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

Raises:

RuntimeError – if fitting is not complete yet

NanoTrees.get_empty_settings(globally_available_plugins=None, standalone=False)¶

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:

Dict[str, Dict[str, Any]]

Purpose: Provide a list of settings details to users to assist in instantiating an instance of your MetaEventFinder subclass.

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.

Your Eventfinder MUST include at least the “MetaReader” key, which can be ensured by calling super().get_empty_settings(globally_available_plugins, standalone) before adding any additional settings keys

This function must implement returning of a dictionary of settings required to initialize the filter, in the specified format. Values in this dictionary can be accessed downstream through the self.settings class variable. This structure is a nested dictionary that supplies both values and a variety of information about those values, used by poriscope to perform sanity and consistency checking at instantiation.

While this function is technically not abstract in MetaEventFinder, which already has an implementation of this function that ensures that settings will have the required MetaReader key available to users, in most cases you will need to override it to add any other settings required by your subclass. If you need additional settings, which you almost ccertainly do, you MUST call super().get_empty_settings(globally_available_plugins, standalone) before any additional code that you add. For example, your implementation could look like this:

settings = super().get_empty_settings(globally_available_plugins, standalone)
settings["Threshold"] = {"Type": float,
                        "Value": None,
                        "Min": 0.0,
                        "Units": "pA"
                        }
settings["Min Duration"] = {"Type": float,
                            "Value": 0.0,
                            "Min": 0.0,
                            "Units": "us"
                            }
settings["Max Duration"] = {"Type": float,
                            "Value": 1000000.0,
                            "Min": 0.0,
                            "Units": "us"
                            }
settings["Min Separation"] = {"Type": float,
                                "Value": 0.0,
                                "Min": 0.0,
                                "Units": "us"
                            }
return settings

which will ensure that your have the 3 keys specified above, as well as an additional key, "MetaReader", as required by eventfinders. In the case of categorical settings, you can also supply the “Options” key in the second level dictionaries.

NanoTrees.get_rise_time(data)¶: estimte the system rise time

NanoTrees.get_skip_region(data, quantile=0.95)¶: estimate region to skip when averaging from the system rise time

NanoTrees.l50_max_height(settings, sublevel, previousHeight=None) → float¶: # Height Function used to estimate the current level within short sublevels

Private Methods¶

NanoTrees._DNA(data: ndarray[tuple[int, ...], dtype[_ScalarType_co]], padding_before, padding_after, baseline_mean)¶: Function stands for Do Not Assume, and serves to calculate widths and height of sublevels without making any assumptions about the shape of the rise time

NanoTrees.__pass1(settings, data, DEBUG=False) → ndarray[tuple[int, ...], dtype[_ScalarType_co]]¶: Approximate level breakdown using Adaboost to overfit the event

NanoTrees.__pass2(settings, data, DEBUG=False) → ndarray[tuple[int, ...], dtype[_ScalarType_co]]¶: Refine the estimate from pass1 using decision trees; still overfit intentionally

NanoTrees._define_event_metadata_types()¶

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, Union[int, float, str, bool]]

NanoTrees._define_event_metadata_units()¶

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

NanoTrees._define_sublevel_metadata_types()¶

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, Union[int, float, str, bool]]

NanoTrees._define_sublevel_metadata_units()¶

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

NanoTrees._locate_sublevel_transitions(data, samplerate, padding_before, padding_after, baseline_mean, baseline_std)¶

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:

List[int]

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
AttributeError – if the fitting method cannot operate without provision of specific padding and baseline metadata and cannot rescue itself. This will cause a stop to processing of the dataset.

NanoTrees._ml_automation(data: ndarray[tuple[int, ...], dtype[_ScalarType_co]], searchStart: int = 3, searchEnd: int = 20, DEBUG=False) → ndarray[tuple[int, ...], dtype[_ScalarType_co]]¶: automatically estimate parameters needed for optimizing the fit sensitivity

NanoTrees._pass3(settings, data, DEBUG=False) → Sublevels¶: Merge Similar Heights with Iterative Height Updates

NanoTrees._pass4(settings, sublevels: Sublevels, raw, DEBUG=False) → Sublevels¶: Split Sublevels with Small Widths with Exceptional Small but Tall Sublevels

NanoTrees._pass5(settings, sublevels: Sublevels, raw, DEBUG=False) → Sublevels¶: Repeat Merge Similar Heights

NanoTrees._pass6(settings, sublevels: Sublevels, raw, DEBUG=False) → Sublevels¶: # Clear Baseline in case there are noisy sublevel transitions flagged in the baseline

NanoTrees._pass7(settings, sublevels: Sublevels, raw, DEBUG=False) → Sublevels¶: # Backtrack (Crude Implementation: Faster) to refine the estimate of sublevel changepoints

NanoTrees._populate_event_metadata(data, samplerate, baseline_mean, baseline_std, sublevel_metadata)¶

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

NanoTrees._populate_sublevel_metadata(data, samplerate, baseline_mean, baseline_std, sublevel_starts)¶

Build a dict of lists of sublevel metadata with whatever arbitrary keys you want to consider in your event fitter. Every list must have exactly the same length as the sublevel_starts list. 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 (HackyList) – 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]]

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._set_automation_hyperparameters(smallestSignificantSublevelStd, rise_time) → dict¶: automate setting most hyperparamters for the fit based on multiples of a few more elements

NanoTrees._slope_height_adjust(settings, sublevels: Sublevels, raw, DEBUG=False) → Sublevels¶: adjust the height estimate for slope-type sublevels

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