Package com.framed.cdss.actors

Class TrendClassificationActor

java.lang.Object
com.framed.core.Service
com.framed.cdss.Actor
com.framed.cdss.actors.TrendClassificationActor
public class TrendClassificationActor extends Actor
A specialized Actor that detects a decreasing trend (downward drift) in numeric channel values using a sliding window and a slope-based metric.

Trend definition (slope-based)

For each channel, this classifier maintains the last windowSize numeric samples:

   y0, y1, ..., y(n-1)   with n = windowSize

It computes the slope b of the best-fit line y = a + b*x using ordinary least squares, where x is the sample index 0..n-1:

   b = Σ((xi - x̄)(yi - ȳ)) / Σ((xi - x̄)^2)

The slope is measured in "value units per sample". For SpO₂, that is "% per sample".

Directional warning condition

This classifier is configured to warn on decreasing trends only. A warning is raised when:

   slope <= -delta

where delta is a non-negative threshold.

Persistence / Debouncing

To reduce false positives due to transient artifacts, the classifier optionally requires the decreasing condition to hold for persistWindows consecutive evaluated windows before it emits a warning. By default, persistWindows = 2.

Once in the "warning" state for a channel, this implementation emits a warning only on state entry, and resets once the condition is no longer met.

Inputs and outputs

  • Input: fireFunction(Map) is invoked with a snapshot channel -> value.
  • Output: A warning message is published to each configured output channel and also logged.

Assumptions: snapshot values are numeric (Number). Non-numeric values throw ClassCastException.

  • Constructor Details

    • TrendClassificationActor

      public TrendClassificationActor(EventBus eventBus, String id, org.json.JSONArray firingRules, org.json.JSONArray inputChannels, org.json.JSONArray outputChannels, org.json.JSONObject windowSizes, org.json.JSONObject persistWindows, org.json.JSONObject deltas, String direction)
      Constructs a TrendClassifier that warns on decreasing trends using regression slope, with configurable persistence.
      Parameters:
      eventBus - the event bus used by this actor; must not be null
      id - identifier of this classifier (often set in configuration); must not be null
      firingRules - firing rules as accepted by Actor; must not be null
      inputChannels - channels observed by this classifier; must not be null
      outputChannels - channels to publish warning messages to; must not be null
      windowSizes - number of recent samples per channel used for trend detection; must be >= 2
      persistWindows - required number of consecutive satisfied windows; must be >= 1
      deltas - non-negative threshold per Channel; warning if slope <= -delta
      Throws:
      NullPointerException - if any required argument is null
      IllegalArgumentException - if windowSize < 2, delta < 0, or persistWindows < 1

  • Method Details

    • fireFunction

      public void fireFunction(Map<String,Object> latestSnapshot)
      Updates per-channel windows with the newest snapshot values, computes the regression slope when enough samples exist, and emits warnings for channels exhibiting a persistent decreasing trend.

      Behavior per channel:

      1. If the channel is missing in the snapshot, it is skipped.
      2. The numeric value is appended to the channel window (oldest removed if full).
      3. Once the window is full, compute regression slope over the window.
      4. If slope <= -delta, increment the persistence counter; otherwise reset it.
      5. If the counter reaches persistWindows, enter warning state and emit a warning once.
      6. If slope no longer meets the condition, exit warning state.
      Specified by:
      fireFunction in class Actor
      Parameters:
      latestSnapshot - snapshot map channel -> value; values must be Number
      Throws:
      ClassCastException - if any encountered snapshot value is not numeric