CLASS vlt.signal.timeseriesDetectorML.base¶

  vlt.signal.timeseriesDetectorML.base -  base class for time series machine learning detectors

  This class provides a framework for building machine learning-based detectors for time series data.
  It defines the interface for training, evaluation, and initialization, and provides static helper
  methods for data preparation and event detection.

Superclasses¶

none

Properties¶

Property	Description
detectorSamples

Methods¶

Method	Description
base	base class for time series machine learning detectors
buildTimeseriesDetectorMLFromDirectory	build a detector from a directory
detectEvents	Detect events in a time series
detectIndividualEvents	Detect discrete events from detector output likelihood
evaluateTimeSeries	vlt.signal.timeseriesDetectorML.base/evaluateTimeSeries is an undocumented builtin function.
negativeShoulderEvents	Generate negative observations from shoulders of positive events
timeStamps2NegativeObservations	Generate negative observations by random sampling
timeStamps2Observations	Extract observations from time series based on timestamps
train	vlt.signal.timeseriesDetectorML.base/train is an undocumented builtin function.

Methods help¶

base - base class for time series machine learning detectors

This class provides a framework for building machine learning-based detectors for time series data.
  It defines the interface for training, evaluation, and initialization, and provides static helper
  methods for data preparation and event detection.

    Documentation for vlt.signal.timeseriesDetectorML.base/base
       doc vlt.signal.timeseriesDetectorML.base

buildTimeseriesDetectorMLFromDirectory - build a detector from a directory

DETECTOR = vlt.signal.timeseriesDetectorML.base.buildTimeseriesDetectorMLFromDirectory(DIRNAME)

  Builds a new vlt.signal.timeseriesDetectorML object from a directory DIRNAME.

  The directory must contain:
    1) 'parameters.json' - a file that describes how to build the object.
       It should have a field 'timeseriesDetectorMLClassName' that has the classname
       of the object to create.
       It should have a field 'creatorInputArgs' that is a structure array with fields
       'name' and 'value'. These are the arguments to be passed to the creator.
       Argument names 'requiredArg1', 'requiredArg2', etc, are assumed to be required
       positional arguments. Other argument names are assumed to be name/value pairs.
    2) '*positive*.mat' files - one or more MAT-files that contain a variable 'positiveExamples'
       which is a matrix of positive examples.
    3) '*negative*.mat' files - one or more MAT-files that contain a variable 'negativeExamples'
       which is a matrix of negative examples.

  The DETECTOR is returned with its parameters trained on the positive and negative examples.

detectEvents - Detect events in a time series

[DETECTEDEVENTS, LIKELIHOOD] = DETECTEVENTS(OBJ, TIMESERIESDATA, OPTIONS)

    Detects events by finding threshold crossings in the likelihood signal
    and identifying the peak likelihood within each suprathreshold interval.
    The peak is defined as the maximum value in the interval. If multiple
    points share the maximum value, the center point (or left of center)
    is selected.

    Inputs:
    OBJ - The detector object.
    TIMESERIESDATA - The time series data vector.
    OPTIONS - Name-value arguments:
        'threshold' (double, default 0.5) - Detection threshold.
        'timestamps' (double, default []) - Optional time vector. If provided,
                                            returns event times instead of indices.
        'refractoryPeriod' (double, default 0.002) - Minimum distance from any positive event.
                                                     If 'timestamps' is provided, units are seconds.
                                                     Otherwise, units are samples (rounded).

    Outputs:
    DETECTEDEVENTS - Vector of sample indices (or times) where events were detected.
    LIKELIHOOD - The likelihood signal computed by the detector.

detectIndividualEvents - Detect discrete events from detector output likelihood

[EVENTTIMES, FILTERED_SIGNAL] = DETECTINDIVIDUALEVENTS(TIMESERIESTIMESTAMPS, DETECTOROUTPUT, OPTIONS)

    Smooths the detector output and finds peaks above a threshold to identify event times.
    Applies a refractory period to merge close detections.

    Inputs:
    TIMESERIESTIMESTAMPS - Time vector corresponding to the detector output.
    DETECTOROUTPUT - Likelihood signal from the detector.
    OPTIONS - Name-value arguments:
        'useGaussianBlur' (logical, default true) - Whether to smooth the output.
        'gaussianSigmaTime' (double, default 0.010) - Sigma for Gaussian smoothing (in time units).
        'refractoryPeriod' (double, default 0.010) - Minimum time between events.
        'threshold' (double, default 0.9) - Detection threshold.

    Outputs:
    EVENTTIMES - Vector of detected event timestamps.
    FILTERED_SIGNAL - The smoothed detector output signal.

evaluateTimeSeries - vlt.signal.timeseriesDetectorML.base/evaluateTimeSeries is an undocumented builtin function.

negativeShoulderEvents - Generate negative observations from shoulders of positive events

[OBSERVATIONS, TFVALUES, NEWTIMESTAMPS] = NEGATIVESHOULDEREVENTS(TIMESERIESTIMESTAMPS, TIMESERIESDATA, POSITIVEEVENTTIMESTAMPS, DETECTORSAMPLES, OPTIONS)

    Generates negative examples by sampling the "shoulders" (near misses) of known positive events.
    It samples every time point within the specified shoulder windows.

    Inputs:
    TIMESERIESTIMESTAMPS - Time vector of the time series.
    TIMESERIESDATA - Data vector of the time series.
    POSITIVEEVENTTIMESTAMPS - Vector of known positive event timestamps.
    DETECTORSAMPLES - Size of the window to extract (in samples).
    OPTIONS - Name-value arguments:
        'leftShoulderOnset' (double, default -0.010) - Start time of left shoulder relative to event.
        'leftShoulderOffset' (double, default -0.005) - End time of left shoulder relative to event.
        'rightShoulderOnset' (double, default 0.005) - Start time of right shoulder relative to event.
        'rightShoulderOffset' (double, default 0.010) - End time of right shoulder relative to event.
        'refractoryPeriod' (double, default 0.002) - Minimum distance from any positive event.

    Outputs:
    OBSERVATIONS - Extracted data matrix.
    TFVALUES - Boolean vector (all false).
    NEWTIMESTAMPS - The timestamps selected.

timeStamps2NegativeObservations - Generate negative observations by random sampling

[OBSERVATIONS, TFVALUES, NEWTIMESTAMPS] = TIMESTAMPS2NEGATIVEOBSERVATIONS(TIMESERIESTIMESTAMPS, TIMESERIESDATA, DETECTEDTIMESTAMPS, DETECTORSAMPLES, OPTIONS)

    Generates negative examples by randomly sampling the time series at locations
    that are sufficiently far from known positive events (DETECTEDTIMESTAMPS).

    Inputs:
    TIMESERIESTIMESTAMPS - Time vector of the time series.
    TIMESERIESDATA - Data vector of the time series.
    DETECTEDTIMESTAMPS - Vector of known positive event timestamps.
    DETECTORSAMPLES - Size of the window to extract (in samples).
    OPTIONS - Name-value arguments:
        'minimumSpacingFromPositive' (double, default 0.050) - Minimum time distance from any positive event.
        'negativeDataSetSize' (double, default 2 * numel(detectedTimeStamps)) - Number of negative examples to generate.
        Also accepts options for timeStamps2Observations (though optimizeForPeak is usually false for random noise).

    Outputs:
    OBSERVATIONS - Extracted data matrix (detectorSamples x numExamples).
    TFVALUES - Boolean vector (all false).
    NEWTIMESTAMPS - The random timestamps selected.

timeStamps2Observations - Extract observations from time series based on timestamps

[OBSERVATIONS, TFVALUES, NEWTIMESTAMPS] = TIMESTAMPS2OBSERVATIONS(TIMESERIESTIMESTAMPS, TIMESERIESDATA, DETECTEDTIMESTAMPS, DETECTORSAMPLES, EXAMPLESAREPOSITIVES, OPTIONS)

    Extracts windows of data centered around specific timestamps. Can optionally optimize the
    timestamps to align with local peaks in the data.

    Inputs:
    TIMESERIESTIMESTAMPS - Time vector of the time series.
    TIMESERIESDATA - Data vector of the time series.
    DETECTEDTIMESTAMPS - Vector of timestamps around which to extract data.
    DETECTORSAMPLES - Size of the window to extract (in samples).
    EXAMPLESAREPOSITIVES - Boolean, true if these are positive examples (sets TFvalues).
    OPTIONS - Name-value arguments:
        'optimizeForPeak' (logical, default false) - Whether to align to local peaks.
        'peakFindingSamples' (double, default 10) - Window size for peak search (+/- samples).
        'useNegativeForPeak' (logical, default false) - If true, searches for local minimum instead of maximum.

    Outputs:
    OBSERVATIONS - Extracted data matrix (detectorSamples x numExamples).
    TFVALUES - Boolean vector indicating class (all true or all false).
    NEWTIMESTAMPS - The actual timestamps used for extraction (refined if optimized).

train - vlt.signal.timeseriesDetectorML.base/train is an undocumented builtin function.