ClassicCUSUM

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

Bases: CUSUM

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

Public Methods

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

  • Step Size (σ) - the smallest change the detector should call a sublevel transition, in baseline standard deviations rather than the pA CUSUM takes. That is the only difference between the two fitters.

  • Sensitivity - divides the detection threshold that CUSUM chooses from the event’s length and the step size. 1, the default and the minimum, is the most conservative; higher values call smaller or shorter steps, at the cost of more false transitions.

  • Rise Time (us) - how much of the signal either side of a transition to exclude from the level averages.

  • Max Sublevels - the largest number of sublevels an event may be fitted with before it is rejected; 0 removes the limit.

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

Private Methods

ClassicCUSUM._locate_sublevel_transitions(data: ndarray[tuple[int, ...], dtype[float64]], samplerate: float, padding_before: int | None, padding_after: int | None, baseline_mean: float | None, baseline_std: float | None) → List[Any] | None

Runs the same CUSUM log-likelihood-ratio changepoint detection as CUSUM, but Step Size is already expressed in units of the local baseline standard deviation (σ) and is used directly rather than normalized against it, unlike CUSUM. 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