Implement a variant of the Pearson detection engine

Author: mesca

.env

@@ -4,7 +4,7 @@ DEVICE=dummy                            # EEG device
 EPOCH=0.250                             # Epoch length, in seconds
 LATENCY=0.08                            # If the signal has a constant latency, set it here
 PIPELINE=riemann                        # Classification pipeline (riemann, eegnet)
-CALIBRATION_LAYOUT=single               # Calibration layout (single, simple, grid, keyboard)
+CALIBRATION_LAYOUT=simple               # Calibration layout (single, simple, grid, keyboard)
 TASK_LAYOUT=simple                      # Task layout (simple, grid, keyboard)
 DYNAMIC_CODES=0                         # 1 to generate random codes or 0 to use static codes
 # SEED=42								# Optional random seed for reproducible dynamic codes

README.md

@@ -155,19 +155,39 @@ To create a new stimulus type, simply add a new image in [this folder](https://g
 
 The application classifies single flashes. Epochs are triggered at each frame on 250ms windows. The classification pipeline computes xdawn covariances projected on the tangent space followed by a linear discriminant analysis. The resulting probabilities are [accumulated](https://github.com/timeflux/burst/blob/main/nodes/predict.py) in a circular buffer on which correlation analysis is performed. When enough confidence is reached for a specific target, a final prediction is made.
 
-The accumulation engine is [configurable](https://github.com/timeflux/burst/blob/main/graphs/classification.yaml).
+Several accumulation engines are available, which can be configured either from the [classification graph](https://github.com/timeflux/burst/blob/main/graphs/classification.yaml) or adjusted in realtime using the contextual menu (by pressing the `s` key).
+
+The current default decision engine is _Steady_.
+
+#### Parameters available for all decision engines
 
 | Setting | Description  | Default |
 |---------|--------------|---------|
 | codes | The list of burst codes, one for each target | |
 | min_buffer_size | Minimum number of predictions to accumulate before emitting a prediction | 30 |
 | max_buffer_size | Maximum number of predictions to accumulate for each class | 200 |
+| recovery | Minimum duration in ms required between two consecutive epochs after a prediction | 300 |
+
+#### _Pearson_ decision engine
+
+This method computes the Pearson correlation for each frame and code. The final prediction is made when the `threshold` and `delta` limits are reached.
+
+| Setting | Description  | Default |
+|---------|--------------|---------|
 | threshold | Minimum value to reach according to the Pearson correlation coefficient | .75 |
 | delta | Minimum difference percentage to reach between the p-values of the two best candidates | .5 |
-| recovery | Minimum duration in ms required between two consecutive epochs after a prediction | 300 |
 
 Please note that default values are reasonnably suitable for random data. For real EEG data, the threshold should probably be raised.
 
+#### _Steady_ decision engine
+
+Based on the _Pearson_ engine, this method uses a different decision process
+
+| Setting | Description  | Default |
+|---------|--------------|---------|
+| min_frames_pred | Minimum number of times the current candidate must have been detected to emit a prediction | 50 |
+| max_frames_pred | Maximum number of frames after which the best performing candidate is chosen | 200 |
+
 ## Running
 
 Run the following:

graphs/classification.yaml

@@ -52,20 +52,30 @@ graphs:
   - id: predict
     module: nodes.predict
     class: Accumulate
+    # params:
+    #   method: AccumulateRandom
+    #   n_targets: 5
+    #   min_buffer_size: 50
+    # params:
+    #   method: AccumulatePearson
+    #   codes:
+    #   {% for CODE in TASK_CODES.split() %}
+    #     - "{{CODE}}"
+    #   {% endfor %}
+    #   threshold: .2
+    #   delta: .5
+    #   min_buffer_size: 20
+    #   max_buffer_size: 80
     params:
-      method: AccumulatePearson
+      method: AccumulateSteady
       codes:
       {% for CODE in TASK_CODES.split() %}
         - "{{CODE}}"
       {% endfor %}
-      threshold: .2
-      delta: .5
-      min_buffer_size: 20
+      min_buffer_size: 50
       max_buffer_size: 80
-    # params:
-    #   method: AccumulateRandom
-    #   n_targets: 5
-    #   min_buffer_size: 50
+      min_frames_pred: 50
+      max_frames_pred: 200
   - id: pub
     module: timeflux.nodes.zmq
     class: Pub

nodes/predict.py

@@ -147,11 +147,39 @@ def decide(self):
         return False
 
 
+class AccumulateRandom(AccumulateAbstract):
+    """ Random decision
+
+    This node accumulates the probabilities of single-trial classifications from a ML node.
+    When the buffer size reaches `min_buffer_size`, a random target between 0 and `n_targets` is predicted.
+    This node has no practical use except for demonstrating how to extend the base `AccumulateAbstract` class.
+
+    Args:
+        n_targets (int): The number of targets.
+        min_buffer_size (int): Minimum number of predictions to accumulate before emitting a prediction (default: 30).
+        max_buffer_size (int): Maximum number of predictions to accumulate for each class (default: 200).
+        recovery (int): Minimum duration in ms required between two consecutive epochs after a prediction (default: 300).
+
+    Attributes:
+        i (Port): Default input, expects DataFrame.
+        o (Port): Default output, provides DataFrame
+    """
+
+    def __init__(self, n_targets, min_buffer_size=30, max_buffer_size=200, recovery=300):
+        self.n_targets = n_targets
+        super().__init__(min_buffer_size, max_buffer_size, recovery)
+
+    def decide(self):
+        return {"target": random.randint(0, self.n_targets - 1), "score": 42}
+
+
 class AccumulatePearson(AccumulateAbstract):
     """ Accumulation of probabilities
 
-    This node accumulates the probabilities of single-trial classifications from a ML node.
+    This node accumulates the probabilities of single-trial classifications from a ML node,
+    and computes the Pearson correlation for each code.
     When enough confidence is reached for a specific class, a final prediction is made.
+    The decision is based on the `threshold` and `delta` parameters.
 
     Args:
         codes (list): The list of burst codes, one for each target.
@@ -208,28 +236,76 @@ def decide(self):
         return {"target": target, "score": correlation}
 
 
-class AccumulateRandom(AccumulateAbstract):
-    """ Random decision
+class AccumulateSteady(AccumulateAbstract):
+    """ Accumulation of probabilities
 
     This node accumulates the probabilities of single-trial classifications from a ML node.
-    When the buffer size reaches `min_buffer_size`, a random target between 0 and `n_targets` is predicted.
-    This node has no practical use except for demonstrating how to extend the base `AccumulateAbstract` class.
+    Based on the Pearson correlation method above, it uses a different decision process.
 
     Args:
-        n_targets (int): The number of targets.
+        codes (list): The list of burst codes, one for each target.
         min_buffer_size (int): Minimum number of predictions to accumulate before emitting a prediction (default: 30).
         max_buffer_size (int): Maximum number of predictions to accumulate for each class (default: 200).
+        min_frames_pred (int): Minimum number of times the current candidate must have been detected to emit a prediction (default: 50).
+        max_frames_pred (int): Maximum number of frames after which the best performing candidate is chosen (default: 200).
         recovery (int): Minimum duration in ms required between two consecutive epochs after a prediction (default: 300).
 
     Attributes:
         i (Port): Default input, expects DataFrame.
         o (Port): Default output, provides DataFrame
     """
 
-    def __init__(self, n_targets, min_buffer_size=30, max_buffer_size=200, recovery=300):
-        self.n_targets = n_targets
-        super().__init__(min_buffer_size, max_buffer_size, recovery)
+    def __init__(self, codes, min_buffer_size=30, max_buffer_size=200, min_frames_pred=50, max_frames_pred=200, recovery=300):
+        self.codes = [[int(bit) for bit in code] for code in codes]
+        self.min_buffer_size = min_buffer_size
+        self.max_buffer_size = max_buffer_size
+        self.recovery = recovery
+        self.min_frames_pred = min_frames_pred
+        self.max_frames_pred = max_frames_pred
+        self.reset()
 
     def decide(self):
-        return {"target": random.randint(0, self.n_targets - 1), "score": 42}
 
+        # Compute the Pearson correlation coefficient
+        correlations = []
+        pvalues = []
+        x = self._probas
+        for code in self.codes:
+            y = [code[i] for i in self._indices]
+            try:
+                correlation, pvalue = pearsonr(x, y)
+            except:
+                # If one input is constant, the standard deviation will be 0, the correlation will not be computed,
+                # and NaN will be returned. In this case, we force the correlation value to 0.
+                correlation = 0
+                pvalue = 1e-8
+            correlations.append(correlation)
+            pvalues.append(pvalue)
+
+        # Make a decision
+        indices = np.flip(np.argsort(correlations))
+        target = int(indices[0])
+        diff_corr = correlations[indices[0]] - correlations[indices[1]]
+        if target == self._current_target and correlations[indices[0]] > 0.0 and diff_corr > 0.0:
+            self._target_acc += 1
+        else:
+            self._current_target = target
+            self._target_acc = 1
+
+        self._preds.update({self._current_target: self._preds[self._current_target] + 1})
+
+        if self._target_acc > self.min_frames_pred:
+            target = self._current_target
+        elif self._frames >= self.max_frames_pred:
+            target = max(self._preds, key=self._preds.get)
+        else:
+            return False
+
+        # Return target and score
+        return {"target": target, "score": self._target_acc}
+
+    def reset(self):
+        super().reset()
+        self._preds = {c:0 for c in range(len(self.codes))}
+        self._current_target = -1
+        self._target_acc = 0

www/assets/js/schema.js

@@ -33,13 +33,17 @@ const schema = {
             "labelPosition": "left-left",
             "widget": "html5",
             "placeholder": " ",
-            "defaultValue": "AccumulatePearson",
+            "defaultValue": "AccumulateSteady",
             "data": {
                 "values": [
                     {
                         "label": "Pearson",
                         "value": "AccumulatePearson"
                     },
+                    {
+                        "label": "Steady",
+                        "value": "AccumulateSteady"
+                    },
                     {
                         "label": "Random",
                         "value": "AccumulateRandom"
@@ -91,6 +95,44 @@ const schema = {
                 },
             ]
         },
+        {
+            "label": "Steady",
+            "conditional": {
+                "show": true,
+                "when": "method",
+                "eq": "AccumulateSteady"
+            },
+            "type": "well",
+            "input": false,
+            "components": [
+                {
+                    "label": "Minimum prediction score",
+                    "labelPosition": "left-left",
+                    "defaultValue": 50,
+                    "validate": {
+                        "required": true,
+                        "min": 1,
+                        "max": 1e9
+                    },
+                    "clearOnHide": false,
+                    "key": "steady.min_frames_pred",
+                    "type": "number"
+                },
+                {
+                    "label": "Maximum predictions",
+                    "labelPosition": "left-left",
+                    "defaultValue": 200,
+                    "validate": {
+                        "required": true,
+                        "min": 1,
+                        "max": 1e9
+                    },
+                    "clearOnHide": false,
+                    "key": "steady.max_frames_pred",
+                    "type": "number",
+                },
+            ]
+        },
         {
             "label": "Random",
             "conditional": {