Add support for triggers (HBC and HRD)

Author: LegrandNico

.coverage

@@ -12,7 +12,7 @@ The Cardioception Python Package - Measuring Interoception with Psychopy - imple
 
 These tasks can run using minimal experimental settings: a computer and a recording device to monitor the heart rate of the participant. The default version of the task use the [Nonin 3012LP Xpod USB pulse oximeter](https://www.nonin.com/products/xpod/) together with [Nonin 8000SM 'soft-clip' fingertip sensors](https://www.nonin.com/products/8000s/). This sensor can be plugged directly into the stim PC via USB and will work with Cardioception without any additional coding required. 
 
-The tasks can also integrate easily with other recording devices and experimental settings (ECG, M/EEG, fMRI...). See the *Send triggers* session for details.
+The tasks can also integrate easily with other recording devices and experimental settings (ECG, M/EEG, fMRI...). See *Sending triggers* below for details.
 
 ##How to cite?
 
@@ -26,19 +26,21 @@ If you are using [systole](https://systole-docs.github.io/) to interact with you
 
 
 # Installation
-## Using the Python Package Index
+**Using the Python Package Index**
 * The most recent version can be installed uing:
     `pip install cardioception`
 * The current development branch can be installed using 
   `pip install git+https://github.com/embodied-computation-group/Cardioception.git`
 
-## Downloading the ZIP file
+**Downloading the ZIP file**
 
 <img src="/images/downloadZIP.png" align="left" alt="metadPy" height="200" HSPACE=30>
+
 You can also download the most recent version by downloading the repository as a .zip file.
 
 After extracting the content of the file, the package can be installed via the command line by running `pip install .`. Note that this command should be executed when your terminal run inside the extracted folder. You can navigate through your local folder using the command `cd [path to your folder]`.
 
+<br clear="left"/>
 
 ## Dependencies
 
@@ -70,6 +72,7 @@ The version provided here are the ones used when testing and runing cardioceptio
 
 Cardioception will automatically copy the images and sound files necessary to run the task correctly (~ 160 Mo). These files will be removed if you uninstall the package using `pip uninstall cardioception`.
 
+# Package modularity
 ## Physiological recording
 
 Both the Heartbeat counting task (HBC) and the heart rate discrimination task (HRD) require access to physiological recording device during the task to estimate the heart rate or count the number of heartbeats in a given time window. Cardioception natively supports:
@@ -78,6 +81,45 @@ Both the Heartbeat counting task (HBC) and the heart rate discrimination task (H
 
 The package can easily be extended and integrate other recording devices by providing another recording class that will interface with your own devices (ECG, pulse oximeters, or any king of recording that will offer precise estimation of the cardiac frequency).
 
+## Sending triggers
+
+The package includes function calls at the beginning and the end of each meaningful trial phase (trial start/end, listening start/end, decision start/end, and confidence rating start/end). These function calls are embedded in the `"triggers"` parameter dictionary.
+
+```python
+from cardioception.HRD.parameters import getParameters
+
+parameters = getParameters()
+parameters["triggers"]
+```
+`
+{'trialStart': None,
+ 'trialStop': None,
+ 'listeningStart': None,
+ 'listeningStop': None,
+ 'decisionStart': None,
+ 'decisionStop': None,
+ 'confidenceStart': None,
+ 'confidenceStop': None}
+ `
+
+By default, keys are initialized with `None` (no triggers sent). But these values can be overwritten with callable implementing the proper trigger message fitting your setup. This can be done by creating a new function and applying it to the relevant dictionary key.
+
+```python
+def sendTrigger(x):
+  # Function connecting to your device and sending the
+  # required value. For illustration, we are using a simple print call.
+  print(f'Send a trigger with value {x}')
+
+
+# Here we use this function to send triggers with value 1 
+# at the begining of the listening phase
+# and with value 2 at the end of the listening phase
+parameters["triggers"]["listeningStart"] = sendTrigger("1")
+parameters["triggers"]["listeningStop"] = sendTrigger("2")
+```
+
+Note that we are using the function call (`sendTrigger("1")`) and not the function itself (`sendTrigger`) here.
+
 # Run the tasks
 
 Each task contains a `parameters` and a `task` submodule describing the experimental parameters and the Psychopy script respectively. Several changes and adaptation can be parametrized just by passing arguments to the parameters functions. Please refer to the API documentation for details.
@@ -90,7 +132,8 @@ Each task contains a `parameters` and a `task` submodule describing the experime
 Once the package has been installed, you can run the task (e.g. here the Heart rate Discrimination task) using the following code snippet:
 
 ```python
-from cardioception.HRD import parameters, task
+from cardioception.HRD.parameters import getParameters
+from cardioception.HRD import task
 
 # Set global task parameters
 parameters = parameters.getParameters(

README.md

@@ -92,11 +92,22 @@ def getParameters(
         Dictionnary containing the texts to be presented.
     textSize : float
         Text size.
+    triggers : dict
+        Dictionary {str, callable or None}. The function will be executed
+        before the corresponding trial sequence. The default values are
+        `None` (no trigger sent).
+            * `"trialStart"`
+            * `"trialStop"`
+            * `"listeningStart"`
+            * `"listeningStop"`
+            * `"decisionStart"`
+            * `"decisionStop"`
+            * `"confidenceStart"`
+            * `"confidenceStop"`
     times : 1d array-like of int
         Length of trials, in seconds.
-    win : `psychopy.visual.Window`
-        Window where to present stimuli.
-
+    win : `psychopy.visual.window`
+        The window in which to draw objects.
     """
     parameters: Dict[str, Any] = {}
     parameters["restPeriod"] = True
@@ -110,6 +121,20 @@ def getParameters(
     parameters["results_df"] = pd.DataFrame({})
     parameters["setup"] = setup
 
+    # Initialize triggers dictionary with None
+    # Some or all can later be overwrited with callable
+    # sending the information needed.
+    parameters["triggers"] = {
+        "trialStart": None,
+        "trialStop": None,
+        "listeningStart": None,
+        "listeningStop": None,
+        "decisionStart": None,
+        "decisionStop": None,
+        "confidenceStart": None,
+        "confidenceStop": None,
+    }
+
     # Experimental design - can choose between a version based on recent
     # papers from Sarah Garfinkel's group, or the classic Schandry approach.
     # The primary difference ebtween the two is the order of trials and the

cardioception/HBC/parameters.py

@@ -9,7 +9,6 @@
 
 def run(
     parameters: dict,
-    confidenceRating: bool = True,
     runTutorial: bool = True,
     win: Optional[visual.Window] = None,
 ):
@@ -19,13 +18,11 @@ def run(
     ----------
     parameters : dict
         Task parameters.
-    confidenceRating : bool
-        Whether the trial show include a confidence rating scale.
     tutorial : bool
-        If *True*, will present a tutorial with 10 training trial with feedback
+        If `True`, will present a tutorial with 10 training trial with feedback
         and 5 trials with confidence rating.
-    win : `psychopy.visual.Window`
-        Window where to present stimuli.
+    win : `psychopy.visual.window` or None
+        The window in which to draw objects.
     """
     if win is None:
         win = parameters["win"]
@@ -44,10 +41,14 @@ def run(
         range(0, len(parameters["conditions"])),
     ):
 
+        parameters["triggers"]["trialStart"]  # Send trigger or None
+
         nCount, confidence, confidenceRT = trial(
             condition, duration, nTrial, parameters, win
         )
 
+        parameters["triggers"]["trialStop"]  # Send trigger or None
+
         # Store results in a DataFrame
         parameters["results_df"] = parameters["results_df"].append(
             pd.DataFrame(
@@ -114,8 +115,8 @@ def trial(
         Trial number.
     parameters : dict
         Task parameters.
-    win : `psychopy.visual.Window`
-        Window where to present stimuli.
+    win : `psychopy.visual.window` or None
+        The window in which to draw objects.
 
     Returns
     -------
@@ -177,6 +178,7 @@ def trial(
         # Add event marker
         parameters["oxiTask"].channels["Channel_0"][-1] = 1
         parameters["noteStart"].play()
+        parameters["triggers"]["listeningStart"]
         core.wait(1)
 
     # Record for a desired time length
@@ -188,6 +190,7 @@ def trial(
         parameters["oxiTask"].readInWaiting()
         parameters["oxiTask"].channels["Channel_0"][-1] = 2
         parameters["noteStop"].play()
+        parameters["triggers"]["listeningStop"]
         core.wait(3)
         parameters["oxiTask"].readInWaiting()
 
@@ -218,6 +221,8 @@ def trial(
         messageCount.draw()
         win.flip()
 
+        parameters["triggers"]["decisionStart"]  # Send trigger or None
+
         nCounts = ""
         while True:
 
@@ -295,6 +300,8 @@ def trial(
             messageCount.draw()
             win.flip()
 
+        parameters["triggers"]["decisionStop"]  # Send trigger or None
+
         ##############
         # Rating scale
         ##############
@@ -316,12 +323,14 @@ def trial(
                 text=parameters["texts"]["confidence"],
                 height=parameters["textSize"],
             )
+            parameters["triggers"]["confidenceStart"]
             while ratingScale.noResponse:
                 message.draw()
                 ratingScale.draw()
                 win.flip()
             confidence = ratingScale.getRating()
             confidenceRT = ratingScale.getRT()
+            parameters["triggers"]["confidenceStop"]
 
     finalCount = int(nCounts) if nCounts else None
 
@@ -335,8 +344,8 @@ def tutorial(parameters: dict, win: Optional[visual.Window] = None):
     ----------
     parameters : dict
         Task parameters.
-    win : `psychopy.visual.Window`
-        Window where to present stimuli.
+    win : `psychopy.visual.window` or None
+        The window in which to draw objects.
     """
     if win is None:
         win = parameters["win"]
@@ -500,8 +509,10 @@ def rest(
     ----------
     parameters : dict
         Task parameters.
-    win : `psychopy.visual.Window`
-        Window where to present stimuli.
+    duration : float
+        Duration or the recording (seconds).
+    win : `psychopy.visual.window` or None
+        The window in which to draw objects.
     """
     if win is None:
         win = parameters["win"]

cardioception/HBC/task.py

@@ -133,9 +133,9 @@ def getParameters(
         The task working directory.
     referenceTone : callable
         Function selecting the reference tones for the exteroceptive condition.
-        The output should be a single float matching the name of the `.wav` files
-        (ending with `.0` or `.5`). Default is uniform between 40.0 and 100.0 BPM
-        (`np.random.choice(np.arange(40, 100, 0.5))`).
+        The output should be a single float matching the name of the `.wav`
+        files (ending with `.0` or `.5`). Default is uniform between 40.0 and
+        100.0 BPM (`np.random.choice(np.arange(40, 100, 0.5))`).
     resultPath : str or None
         Where to save the results.
     serial : PySerial instance
@@ -164,8 +164,20 @@ def getParameters(
         Long text elements.
     textSize : float
         Scalling parameter for text size.
-    win : Psychopy window instance
-        The window where to run the task.
+    triggers : dict
+        Dictionary {str, callable or None}. The function will be executed
+        before the corresponding trial sequence. The default values are
+        `None` (no trigger sent).
+            * `"trialStart"`
+            * `"trialStop"`
+            * `"listeningStart"`
+            * `"listeningStop"`
+            * `"decisionStart"`
+            * `"decisionStop"`
+            * `"confidenceStart"`
+            * `"confidenceStop"`
+    win : `psychopy.visual.window`
+        The window in which to draw objects.
     """
     parameters: Dict[str, Any] = {}
     parameters["ExteroCondition"] = exteroception
@@ -191,6 +203,20 @@ def getParameters(
     parameters["signal_df"] = pd.DataFrame([])  # Physiological recording
     parameters["results_df"] = pd.DataFrame([])  # Behavioral results
 
+    # Initialize triggers dictionary with None
+    # Some or all can later be overwrited with callable
+    # sending the information needed.
+    parameters["triggers"] = {
+        "trialStart": None,
+        "trialStop": None,
+        "listeningStart": None,
+        "listeningStop": None,
+        "decisionStart": None,
+        "decisionStop": None,
+        "confidenceStart": None,
+        "confidenceStop": None,
+    }
+
     # Set default path /Results/ 'Subject ID' /
     parameters["participant"] = participant
     parameters["session"] = session