Source code for cardioception.HBC.parameters

# Authors: Nicolas Legrand and Micah Allen, 2019-2022. Contact: micah@cfin.au.dk
# Maintained by the Embodied Computation Group, Aarhus University

import os
from typing import Any, Dict, Optional

import numpy as np
import pandas as pd
import serial
from systole import serialSim
from systole.recording import Oximeter

from .._resources import resource_filename
from .languages import english, german


[docs]def getParameters( participant: str = "Participant", session: str = "001", serialPort: str = "COM3", taskVersion: str = "Garfinkel", setup: str = "behavioral", screenNb: int = 0, fullscr: bool = True, resultPath: Optional[str] = None, systole_kw: dict = {}, language: str = "english", recorder=None, ) -> Dict: """Create Heartbeat Counting task parameters. Parameters ---------- language : str The language used for the instructions. Can be `"english"` (default) or `"german"`. participant : str Subject ID. Default is 'exteroStairCase'. recorder : object | None A recording device to use instead of the pulse oximeter `setup` would open, e.g. :class:`cardioception.devices.LSLRecorder` to read ECG from an LSL stream. `setup` still decides the window. Default is `None`, which leaves the task exactly as it was. resultPath : str or None Where to save the results. screenNb : int Screen number. Used to parametrize py:func:`psychopy.visual.Window`. Default is set to 0. serialPort: str The USB port where the pulse oximeter is plugged. Should be written as a string e.g. `"COM3"` for USB ports on Windows. session : int Session number. Default to '001'. setup : str Context of oximeter recording. `"behavioral"` will record through a Nonin pulse oximeter, `"test"` will use pre-recorded pulse time series (for testing only). systole_kw : dict Additional keyword arguments for :py:class:`systole.recorder.Oxmeter`. taskVersion : str or None Task version to run. Can be 'Garfinkel', 'Shandry', 'test' or None. Attributes ---------- conditions : 1d array-like of str The conditions. Can be 'Rest', 'Training' or 'Count'. confScale : list The range of the confidence rating scale. heartLogo : `psychopy.visual.ImageStim` Image presented during resting conditions. labelsRating : list The labels of the confidence rating scale. noteStart : psychopy.sound.Sound instance The sound that will be played when trial starts. noteStop : psychopy.sound.Sound instance The sound that will be played when trial ends. path : str The task working directory. randomize : bool If `True` (default), will randomize the order of the conditions. If taskVersion is not None, will use the default task parameter instead. rating : bool If `True` (default), will add a rating scale after the evaluation. restLength : int The length of the resting period (seconds). Default is 300 seconds. restLogo : `psychopy.visual.ImageStim` Image presented during resting conditions. restPeriod : bool If `True`, a resting period will be proposed before the task. resultPath : str The subject result directory. screenNb : int The screen number (Psychopy parameter). Default set to 0. serial : `serial.Serial` The serial port used to record the PPG activity. startKey : str The key to press to start the task and go to next steps. taskVersion : str or None Task version to run. Can be 'Garfinkel', 'Shandry', 'test' or None. texts : dict Dictionary 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` The window in which to draw objects. """ if language not in ("english", "german"): raise ValueError( f"Invalid language: {language!r}. Can be 'english' or 'german'." ) from psychopy import sound, visual parameters: Dict[str, Any] = {} parameters["restPeriod"] = True parameters["restLength"] = 30 parameters["randomize"] = True parameters["startKey"] = "space" parameters["rating"] = True parameters["confScale"] = [1, 7] parameters["taskVersion"] = taskVersion 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 # use of resting periods between trials. if parameters["taskVersion"] == "Garfinkel": parameters["times"] = np.array([25, 30, 35, 40, 45, 50]) np.random.shuffle(parameters["times"]) parameters["conditions"] = [ "Count", "Count", "Count", "Count", "Count", "Count", ] elif parameters["taskVersion"] == "Schandry": parameters["times"] = np.array([60, 25, 30, 35, 30, 45]) parameters["conditions"] = ["Rest", "Count", "Rest", "Count", "Rest", "Count"] elif parameters["taskVersion"] == "test": parameters["times"] = np.array([5, 5]) parameters["conditions"] = ["Rest", "Count"] else: raise ValueError("Invalid task condition") # Set default path /Results/ 'Subject ID' / parameters["participant"] = participant parameters["session"] = session parameters["path"] = os.getcwd() if resultPath is None: parameters["resultPath"] = parameters["path"] + "/data/" + participant + session else: parameters["resultPath"] = resultPath # Create Results directory of not already exists if not os.path.exists(parameters["resultPath"]): os.makedirs(parameters["resultPath"]) # Set note played at trial start parameters["noteStart"] = sound.Sound( resource_filename("cardioception.HBC", "Sounds/start.wav") ) parameters["noteStop"] = sound.Sound( resource_filename("cardioception.HBC", "Sounds/stop.wav") ) # Open window if parameters["setup"] == "test": fullscr = False parameters["win"] = visual.Window(screen=screenNb, fullscr=fullscr, units="height") parameters["win"].mouseVisible = False parameters["restLogo"] = visual.ImageStim( win=parameters["win"], units="height", image=resource_filename("cardioception.HBC", "Images/rest.png"), pos=(0.0, -0.2), ) parameters["restLogo"].size *= 0.15 parameters["heartLogo"] = visual.ImageStim( win=parameters["win"], units="height", image=resource_filename("cardioception.HBC", "Images/heartbeat.png"), pos=(0.0, -0.2), ) parameters["heartLogo"].size *= 0.05 if recorder is not None: # Wins over `setup`, and touches no serial port. parameters["oxiTask"] = recorder parameters["oxiTask"].setup().read(duration=1) elif setup == "behavioral": # PPG recording port = serial.Serial(serialPort) parameters["oxiTask"] = Oximeter( serial=port, sfreq=75, add_channels=1, **systole_kw ) parameters["oxiTask"].setup().read(duration=1) elif setup == "test": # Use pre-recorded pulse time series for testing port = serialSim() parameters["oxiTask"] = Oximeter( serial=port, sfreq=75, add_channels=1, **systole_kw ) parameters["oxiTask"].setup().read(duration=1) ####### # Texts ####### if language == "english": texts = english() elif language == "german": texts = german() parameters["labelsRating"] = texts.pop("labelsRating") parameters["texts"] = texts parameters["textSize"] = 0.04 return parameters