CUSUM¶

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

CUSUM.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

CUSUM.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[npt.NDArray[np.float64]]

Raises:

AttributeError – if this instance is not linked to a MetaEventLoader

CUSUM.get_empty_settings(globally_available_plugins: Dict[str, List[str]] | None = None, standalone: bool = False) → 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. Type is required; Value may be omitted or set to None, both meaning there is no default and the user must supply one. 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.

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

Private Methods¶

CUSUM._calculate_threshold(length: int, step: float, min_threshold: float = 0.4, max_threshold: float = 10.0) → float¶

Calculate an optimal threshold value based on signal length and step size.

Exact Python port of the C functions get_cusum_threshold and ARL.

Parameters:

length (int) – the length of the event data, in samples
step (float) – the CUSUM step size, in units of the local baseline standard deviation
min_threshold (float) – the smallest threshold value to consider, default 0.4
max_threshold (float) – the largest threshold value to consider, default 10.0

Returns:

the calculated optimal threshold

Return type:

float

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

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

Build a dict of metadata units, or None if unitless. Keys must match columns defined in _populate_event_metadata() All of this metadata must be populated during fitting.

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

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

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

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

Runs adaptive-threshold CUSUM log-likelihood-ratio changepoint detection on the event, with Step Size normalized by the local baseline standard deviation, retrying with adjusted parameters if too many or too few sublevels are found. Returned indices are pre-pended with 0 if 0 is not already the first entry.

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 entries that details sublevel transitions. Normally this would be as a list of ints, but can be a list of tuples or other entries if more info is needed. First entry must correspond to the start of the event.

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

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

Raises:

ValueError – if baseline_std is None, or if the sublevel current at the start and end of the event differ by more than twice the local baseline standard deviation (baseline mismatch)

CUSUM._post_process_events(channel: int) → None¶

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

CUSUM._pre_process_events(channel: int) → None¶

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

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