CUSUM¶
class CUSUM(settings: Optional[dict] = None)
Bases: MetaEventFitter
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:
- 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]]¶
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. Seeget_empty_settings()for the structure of the dict and whatType,Value,Min,Max,OptionsandUnitsmean 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(pA) - the smallest change in current the detector should call a sublevel transition, in absolute current.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, so a finite edge does not bias them.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:
Private Methods¶
- 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
- 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.
- 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
- 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
- CUSUM._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 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
- CUSUM._populate_event_metadata(data: ndarray[tuple[int, ...], dtype[float64]], samplerate: float, baseline_mean: float | None, baseline_std: float | None, sublevel_metadata: Dict[str, List[int | float | number]]) Dict[str, int | float | str | bool]¶
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:
- 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 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]]
- 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)