psychopy 2025.1.1__py3-none-any.whl → 2025.2.1__py3-none-any.whl

psychopy/demos/coder/hardware/hdf5_extract.py

@@ -0,0 +1,133 @@
+"""
+This script reads an HDF5 eye-tracking data file, identifies trials based on specified 
+start and end markers in the experiment messages, extracts gaze data for each trial,
+and animates gaze movement over time in a 2D space.
+
+The user can customize:
+    - The path to the HDF5 file
+    - The marker text used to indicate the start and end of trials
+
+⚠️ If you get an error saying a package (like h5py, numpy, matplotlib) is missing:
+In PsychoPy, go to:
+    Tools > Plugins/Packages Manager > Packages
+Then search for and install the missing package (e.g., "h5py", "matplotlib", "numpy").
+"""
+
+"""
+This script reads an HDF5 eye-tracking data file, identifies trials based on specified 
+start and end markers in the experiment messages, extracts gaze data for each trial,
+and animates gaze movement over time in a 2D space.
+
+The user can customize:
+    - The path to the HDF5 file
+    - The marker text used to indicate the start and end of trials
+"""
+
+# ==== USER INPUTS ====
+HDF5_FILE = '823238_eyetracking_youtube_2025-05-01_10h34.25.036.hdf5'  # Path to HDF5 file
+TRIAL_START_MARKER = 'BEGIN_SEQUENCE 3'#'trial_start'  # Marker text for start of trial
+TRIAL_END_MARKER = 'DONE_SEQUENCE 3'#'trial_end'      # Marker text for end of trial
+# ======================
+
+import h5py
+import numpy as np
+import matplotlib.pyplot as plt
+import matplotlib.animation as animation
+
+def extract_eye_data_in_trials(hdf5_path, start_marker, end_marker):
+    """
+    Extract gaze data for each trial based on custom trial start/end markers.
+
+    Parameters:
+        hdf5_path (str): Path to HDF5 file.
+        start_marker (str): String identifying trial start in the message events.
+        end_marker (str): String identifying trial end in the message events.
+
+    Returns:
+        List of dicts: Each dict contains time, gaze_x, and gaze_y arrays for one trial.
+    """
+    with h5py.File(hdf5_path, 'r') as f:
+        # Dataset paths
+        msg_path = 'data_collection/events/experiment/MessageEvent'
+        eye_path = 'data_collection/events/eyetracker/MonocularEyeSampleEvent'
+
+        # Load message times and text
+        messages = f[msg_path]
+        msg_times = messages['time'][:]
+        msg_texts = messages['text'][:].astype(str)
+
+        # Find trial start/end times using the provided marker strings
+        trial_starts = msg_times[np.char.find(msg_texts, start_marker) != -1]
+        trial_ends = msg_times[np.char.find(msg_texts, end_marker) != -1]
+
+        if len(trial_starts) != len(trial_ends):
+            raise ValueError("Mismatched number of trial start and end events")
+
+        # Load eye tracking data
+        eye_data = f[eye_path]
+        eye_times = eye_data['time'][:]
+        gaze_x = eye_data['gaze_x'][:]
+        gaze_y = eye_data['gaze_y'][:]
+
+        # Extract data between trial start and end times
+        trials_gaze = []
+        for start, end in zip(trial_starts, trial_ends):
+            mask = (eye_times >= start) & (eye_times <= end)
+            trial_gaze = {
+                'start_time': start,
+                'end_time': end,
+                'time': eye_times[mask],
+                'gaze_x': gaze_x[mask],
+                'gaze_y': gaze_y[mask]
+            }
+            trials_gaze.append(trial_gaze)
+
+        return trials_gaze
+
+def animate_gaze(trial_data, trial_num, save_to_file=False):
+    """
+    Animate gaze positions over time for a single trial.
+
+    Parameters:
+        trial_data (dict): Dictionary with 'time', 'gaze_x', and 'gaze_y' keys.
+        trial_num (int): Index of the trial (for labeling).
+        save_to_file (bool): Whether to save the animation as an .mp4 video file.
+    """
+    x = trial_data['gaze_x']
+    y = trial_data['gaze_y']
+    t = trial_data['time']
+
+    fig, ax = plt.subplots(figsize=(8, 6))
+    ax.set_xlim(-1, 1)
+    ax.set_ylim(-0.5, 0.5)
+    ax.set_title(f"Gaze Animation - Trial {trial_num}")
+    ax.set_xlabel("Gaze X")
+    ax.set_ylabel("Gaze Y")
+
+    point, = ax.plot([], [], 'ro', markersize=5)  # Red dot to show gaze
+
+    def init():
+        point.set_data([], [])
+        return point,
+
+    def update(frame):
+        point.set_data(x[frame], y[frame])
+        return point,
+
+    ani = animation.FuncAnimation(
+        fig, update, frames=len(x),
+        init_func=init, blit=True, interval=10
+    )
+
+    if save_to_file:
+        ani.save(f'gaze_trial_{trial_num}.mp4', fps=60, extra_args=['-vcodec', 'libx264'])
+
+    plt.show()
+
+# ====== MAIN EXECUTION ======
+if __name__ == '__main__':
+    result = extract_eye_data_in_trials(HDF5_FILE, TRIAL_START_MARKER, TRIAL_END_MARKER)
+    if not result:
+        print("No valid trials found.")
+    else:
+        animate_gaze(result[0], trial_num=1, save_to_file=False)

psychopy/event.py

@@ -297,7 +297,7 @@ def _onPygletMouseRelease(x, y, button, modifiers, emulated=False):
 
 def _onPygletMouseWheel(x, y, scroll_x, scroll_y):
     global mouseWheelRel
-    mouseWheelRel = mouseWheelRel + numpy.array([scroll_x, scroll_y])
+    mouseWheelRel +=  numpy.array([scroll_x, scroll_y])
     msg = "Mouse: wheel shift=(%i,%i), pos=(%i,%i)"
     logging.data(msg % (scroll_x, scroll_y, x, y))
 
@@ -874,23 +874,28 @@ class Mouse:
 
         """
         global mouseButtons, mouseTimes
-        if usePygame:
-            return mouse.get_pressed()
-        else:
+
+        if self.win is None:  # no backend specified
+            return None
+
+        if havePyglet and self.win.winType == 'pyglet':
             # for each (pyglet) window, dispatch its events before checking
             # event buffer
-            if havePyglet:
-                for win in pyglet.app.windows:
-                    win.dispatch_events()  # pump events on pyglet windows
-
-            if haveGLFW:
-                glfw.poll_events()
+            for win in pyglet.app.windows:
+                win.dispatch_events()  # pump events on pyglet windows
+        elif haveGLFW and self.win.winType == 'glfw':
+            glfw.poll_events()
+        elif havePygame and self.win.winType == 'pygame':
+            return mouse.get_pressed()
+        else:
+            raise RuntimeError(
+                "Mouse.getPressed() is only supported for the pyglet, "
+                                      "pygame and glfw backends.")  
 
-            # else:
-            if not getTime:
-                return copy.copy(mouseButtons)
-            else:
-                return copy.copy(mouseButtons), copy.copy(mouseTimes)
+        if not getTime:
+            return copy.copy(mouseButtons)
+        else:
+            return copy.copy(mouseButtons), copy.copy(mouseTimes)
 
     def isPressedIn(self, shape, buttons=(0, 1, 2)):
         """Returns `True` if the mouse is currently inside the shape and

psychopy/experiment/_experiment.py

@@ -117,6 +117,7 @@ class Experiment:
     Routine. The Flow controls how Routines are organised
     e.g. the nature of repeats and branching of an experiment.
     """
+    
 
     def __init__(self, prefs=None):
         super(Experiment, self).__init__()
@@ -165,6 +166,11 @@ class Experiment:
         self._expHandler = TrialHandler(exp=self, name='thisExp')
         self._expHandler.type = 'ExperimentHandler'  # true at run-time
 
+        # get a local reference of all Components and Routines (refreshed on loading a new file)
+        self.allCompons = getAllComponents(
+            self.prefsBuilder['componentsFolders'], fetchIcons=False)
+        self.allRoutines = getAllStandaloneRoutines(fetchIcons=False)
+
     def __eq__(self, other):
         if isinstance(other, Experiment):
             # if another experiment, compare filenames
@@ -577,6 +583,14 @@ class Experiment:
         name = paramNode.get('name')
         valType = paramNode.get('valType')
         val = paramNode.get('val')
+        # 
+        # get knowwn legacy params for the current Component
+        componentLegacyParams = []
+        if componentNode is not None:
+            if componentNode.tag in self.allCompons:
+                componentLegacyParams = self.allCompons[componentNode.tag].legacyParams
+            if componentNode.tag in self.allRoutines:
+                componentLegacyParams = self.allRoutines[componentNode.tag].legacyParams
         # many components need web char newline replacement
         if not name == 'advancedParams':
             val = val.replace("
", "\n")
@@ -727,6 +741,10 @@ class Experiment:
             else:
                 if name in params:
                     params[name].val = val
+                elif name in legacyParams + componentLegacyParams:
+                    # don't warn people if we know it's OK (e.g. for params
+                    # that have been removed
+                    return recognised
                 else:
                     # we found an unknown parameter (probably from the future)
                     params[name] = Param(
@@ -740,11 +758,7 @@ class Experiment:
                     params[name].allowedTypes = paramNode.get('allowedTypes')
                     if params[name].allowedTypes is None:
                         params[name].allowedTypes = []
-                    if name in legacyParams + ['JS libs', 'OSF Project ID']:
-                        # don't warn people if we know it's OK (e.g. for params
-                        # that have been removed
-                        pass
-                    elif componentNode is not None and componentNode.get("plugin", False) not in (False, "", "None", None):
+                    if componentNode is not None and componentNode.get("plugin", False) not in (False, "", "None", None):
                         # is param unrecognised because it's from a plugin?
                         params[name].categ = "Plugin"
                         params[name].plugin = componentNode.get("plugin", False)
@@ -757,17 +771,24 @@ class Experiment:
 
         # get the value type and update rate
         if 'valType' in list(paramNode.keys()):
-            params[name].valType = paramNode.get('valType')
+            valType = paramNode.get('valType')
+            setValType = True
             # compatibility checks:
             if name in ['allowedKeys'] and paramNode.get('valType') == 'str':
                 # these components were changed in v1.70.00
-                params[name].valType = 'code'
+                valType = 'code'
             elif name == 'Selected rows':
                 # changed in 1.81.00 from 'code' to 'str': allow string or var
-                params[name].valType = 'str'
+                valType = 'str'
             # conversions based on valType
             if params[name].valType == 'bool':
                 params[name].val = eval("%s" % params[name].val)
+            # "device" valType was introduced in 2025.2.0 and should always override saved valType
+            if params[name].valType == "device":
+                setValType = False
+            # do actual setting
+            if setValType:
+                params[name].valType = valType
         if 'updates' in list(paramNode.keys()):
             params[name].updates = paramNode.get('updates')
 
@@ -873,9 +894,9 @@ class Experiment:
             self.setExpName(shortName)
         # fetch routines
         routinesNode = root.find('Routines')
-        allCompons = getAllComponents(
+        self.allCompons = allCompons = getAllComponents(
             self.prefsBuilder['componentsFolders'], fetchIcons=False)
-        allRoutines = getAllStandaloneRoutines(fetchIcons=False)
+        self.allRoutines = allRoutines = getAllStandaloneRoutines(fetchIcons=False)
         # get each routine node from the list of routines
         for routineNode in routinesNode:
             if routineNode.tag == "Routine":
@@ -959,6 +980,9 @@ class Experiment:
                     if paramNode.tag == "Param":
                         for key, val in paramNode.items():
                             name = paramNode.get("name")
+                            # "device" valType was introduced in 2025.2.0 and should always override saved valType
+                            if key == "valType" and routine.params[name].valType == "device":
+                                continue
                             if name in routine.params:
                                 setattr(routine.params[name], key, val)
                 # Add routine to experiment
@@ -1134,6 +1158,58 @@ class Experiment:
     def htmlFolder(self):
         return self.settings.params['HTML path'].val
 
+    def getRequiredDeviceNames(self):
+        """
+        Get the device names which need to be defined for this experiment to run, along with a list 
+        of possible types for each one.
+
+        Returns
+        -------
+        dict[str: list[str]]
+            Device names and a list of possible types for each one
+        """
+        # dict in which to store usages
+        usages = {}
+
+        def _process(emt):
+            """
+            Process an element (Component or Routine) for device names and append them to the
+            usages dict.
+
+            Parameters
+            ----------
+            emt : Component or Routine
+                Element to process
+            """
+            # iterate through param's inita values
+            for param in getInitVals(emt.params).values():
+                # if it's a device...
+                if param.valType == "device":
+                    # get value
+                    deviceName = param.val
+                    # make sure device name is in usages dict
+                    if deviceName not in usages:
+                        usages[deviceName] = []
+                    # add any new usages
+                    for cls in getattr(emt, "deviceClasses", []):
+                        if cls not in usages[deviceName]:
+                            usages[deviceName].append(cls) 
+        
+        # iterate through routines
+        for rt in self.routines.values():
+            if isinstance(rt, BaseStandaloneRoutine):
+                # for standalone routines, get device names from params
+                _process(rt)
+            else:
+                # for regular routines, get device names from each component
+                for comp in rt:
+                    _process(comp)
+        # process settings
+        _process(self.settings)
+        
+        return usages
+
+
     def getComponentFromName(self, name):
         """Searches all the Routines in the Experiment for a matching Comp name
 

psychopy/experiment/components/__init__.py

@@ -25,7 +25,6 @@ excludeComponents = [
     'BaseComponent',
     'BaseVisualComponent',
     'BaseDeviceComponent',
-    'BaseStandaloneRoutine'  # templates only
 ]  # this one isn't ready yet
 
 # Plugin components are added dynamically at runtime, usually from plugin
@@ -288,14 +287,6 @@ def getInitVals(params, target="PsychoPy"):
                                        .format(inits[name]))
                     inits[name].valType = 'code'
 
-        if name == "deviceLabel":
-            if "name" in inits and not params[name]:
-                # if deviceName exists but is blank, use component name
-                inits[name].val = inits['name'].val
-            # make a code version of device name
-            inits['deviceLabelCode'] = copy.copy(inits[name])
-            inits['deviceLabelCode'].valType = "code"
-
         if not hasattr(inits[name], 'updates'):  # might be settings parameter instead
             continue
 
@@ -305,7 +296,7 @@ def getInitVals(params, target="PsychoPy"):
                 inits[name].val = None
                 inits[name].valType = 'extendedStr'
             else:
-                inits[name].val = 'None'
+                inits[name].val = None
                 inits[name].valType = 'code'
 
         # is constant so don't touch the parameter value
@@ -393,6 +384,8 @@ def getInitVals(params, target="PsychoPy"):
         elif name == 'allowedKeys':
             inits[name].val = "[]"
             inits[name].valType = 'code'
+        elif name == "deviceLabel":
+            inits[name].valType = "device"
         else:
             # if not explicitly handled, default to None
             inits[name].val = "None"

psychopy/experiment/components/_base.py

@@ -13,6 +13,7 @@ from xml.etree.ElementTree import Element
 
 from psychopy import prefs
 from psychopy.constants import FOREVER
+from psychopy.experiment.devices import DeviceMixin
 from ..params import Param
 from psychopy.experiment.utils import canBeNumeric
 from psychopy.experiment.utils import CodeGenerationException
@@ -42,6 +43,9 @@ class BaseComponent:
     validatorClasses = []
     # hide this Component in Builder view?
     hidden = False
+    # are there any known legacy params for this Component?
+    # these will be removed & warnings ignored on experiment load
+    legacyParams = []
 
     def __init__(self, exp, parentName, name='',
                  startType='time (s)', startVal='',
@@ -67,7 +71,7 @@ class BaseComponent:
         msg = _translate(
             "Name of this Component (alphanumeric or _, no spaces)")
         self.params['name'] = Param(name,
-            valType='code', inputType="single", categ='Basic',
+            valType='code', inputType="name", categ='Basic',
             hint=msg,
             label=_translate("Name"))
 
@@ -1373,12 +1377,10 @@ class BaseComponent:
             return "thisExp"
 
 
-class BaseDeviceComponent(BaseComponent):
+class BaseDeviceComponent(BaseComponent, DeviceMixin):
     """
     Base class for most components which interface with a hardware device.
     """
-    # list of class strings (readable by DeviceManager) which this component's device could be
-    deviceClasses = []
 
     def __init__(
             self, exp, parentName,
@@ -1404,22 +1406,9 @@ class BaseDeviceComponent(BaseComponent):
             saveStartStop=saveStartStop, syncScreenRefresh=syncScreenRefresh,
             disabled=disabled
         )
-        # require hardware
-        self.exp.requirePsychopyLibs(
-            ['hardware']
-        )
-        # --- Device params ---
-        self.order += [
-            "deviceLabel"
-        ]
-        # label to refer to device by
-        self.params['deviceLabel'] = Param(
-            deviceLabel, valType="str", inputType="single", categ="Device",
-            label=_translate("Device label"),
-            hint=_translate(
-                "A label to refer to this Component's associated hardware device by. If using the "
-                "same device for multiple components, be sure to use the same label here."
-            )
+        # add device stuff
+        self.addDeviceParams(
+            defaultLabel=deviceLabel
         )
 
 

psychopy/experiment/components/button/__init__.py

@@ -87,7 +87,7 @@ class ButtonComponent(BaseVisualComponent):
             label=_translate("Run once per click")
         )
         self.params['callback'] = Param(
-            callback, valType='extendedCode', inputType="multi", allowedTypes=[], categ='Basic',
+            callback, valType='extendedCode', inputType="code", allowedTypes=[], categ='Basic',
             updates='constant',
             hint=_translate("Code to run when button is clicked"),
             label=_translate("Callback function"))

psychopy/experiment/components/buttonBox/__init__.py

@@ -1,10 +1,10 @@
 from pathlib import Path
 from psychopy.experiment.components import BaseComponent, BaseDeviceComponent, Param, getInitVals
-from psychopy.experiment.plugins import PluginDevicesMixin, DeviceBackend
+from psychopy.experiment.devices import DeviceBackend
 from psychopy.localization import _translate
 
 
-class ButtonBoxComponent(BaseDeviceComponent, PluginDevicesMixin):
+class ButtonBoxComponent(BaseDeviceComponent):
     """
     Component for getting button presses from a button box device.
     """
@@ -13,6 +13,11 @@ class ButtonBoxComponent(BaseDeviceComponent, PluginDevicesMixin):
     iconFile = Path(__file__).parent / 'buttonBox.png'
     tooltip = _translate('Button Box: Get input from a button box')
     beta = True
+    legacyParams = [
+        # old device setup params, no longer needed as this is handled by DeviceManager
+        "deviceBackend", 
+        "kbButtonAliases"
+    ]
 
     def __init__(
             self, exp, parentName,
@@ -22,6 +27,7 @@ class ButtonBoxComponent(BaseDeviceComponent, PluginDevicesMixin):
             stopType='duration (s)', stopVal=1.0,
             startEstim='', durationEstim='',
             forceEndRoutine=True,
+            discardPrevious=True,
             # device
             deviceLabel="",
             deviceBackend="keyboard",
@@ -69,6 +75,7 @@ class ButtonBoxComponent(BaseDeviceComponent, PluginDevicesMixin):
             "allowedButtons",
             "storeCorrect",
             "correctAns",
+            "discardPrevious"
         ]
         self.params['registerOn'] = Param(
             registerOn, valType='code', inputType='choice', categ='Data',
@@ -119,26 +126,15 @@ class ButtonBoxComponent(BaseDeviceComponent, PluginDevicesMixin):
                 "$correctAns to compare to the key press. "
             ),
             label=_translate("Correct answer"), direct=False)
-
-        # --- Device params ---
-        self.order += [
-            "deviceBackend",
-        ]
-
-        self.params['deviceBackend'] = Param(
-            deviceBackend, valType="str", inputType="choice", categ="Device",
-            allowedVals=self.getBackendKeys,
-            allowedLabels=self.getBackendLabels,
-            label=_translate("Device backend"),
+        self.params['discardPrevious'] = Param(
+            discardPrevious, valType='bool', inputType="bool", categ="Data",
+            updates="constant",
             hint=_translate(
-                "What kind of button box is it? What package/plugin should be used to talk to it?"
+                "Do you want to discard all responses occurring before the onset of this Component?"
             ),
-            direct=False
+            label=_translate("Discard previous")
         )
 
-        # add params for any backends
-        self.loadBackends()
-
     def writeInitCode(self, buff):
         inits = getInitVals(self.params)
         # code to create object
@@ -180,13 +176,14 @@ class ButtonBoxComponent(BaseDeviceComponent, PluginDevicesMixin):
         # writes an if statement to determine whether to draw etc
         indented = self.writeStartTestCode(buff)
         if indented:
-            # dispatch and clear messages
-            code = (
-                "# clear any messages from before starting\n"
-                "%(name)s.responses = []\n"
-                "%(name)s.clearResponses()\n"
-            )
-            buff.writeIndentedLines(code % params)
+            if self.params['discardPrevious']:
+                # dispatch and clear messages
+                code = (
+                    "# clear any messages from before starting\n"
+                    "%(name)s.responses = []\n"
+                    "%(name)s.clearResponses()\n"
+                )
+                buff.writeIndentedLines(code % params)
             # to get out of the if statement
             buff.setIndentLevel(-indented, relative=True)
 
@@ -277,50 +274,49 @@ class ButtonBoxComponent(BaseDeviceComponent, PluginDevicesMixin):
             "thisExp.addData('%(name)s.corr', %(name)s.corr)\n"
         )
         buff.writeIndentedLines(code % params)
-        
 
-class KeyboardButtonBoxBackend(DeviceBackend):
-    """
-    Adds a basic keyboard emulation backend for ButtonBoxComponent, as well as acting as an example
-    for implementing other ButtonBoxBackends.
-    """
 
-    key = "keyboard"
-    label = _translate("Keyboard")
-    component = ButtonBoxComponent
-    deviceClasses = ['psychopy.hardware.button.KeyboardButtonBox']
+class KeyboardButtonBoxDeviceBackend(DeviceBackend):
+    backendLabel = "Keyboard Button Box"
+    deviceClass = "psychopy.hardware.button.KeyboardButtonBox"
+    icon = "light/buttonBox.png"
+
+    def __init__(self, profile):
+        # init parent class
+        DeviceBackend.__init__(self, profile)
 
-    def getParams(self: ButtonBoxComponent):
         # define order
-        order = [
+        self.order += [
             "kbButtonAliases",
         ]
         # define params
-        params = {}
-        params['kbButtonAliases'] = Param(
-            "'q', 'w', 'e'", valType="list", inputType="single", categ="Device",
+        self.params['kbButtonAliases'] = Param(
+            "'q', 'w', 'e'", valType="list", inputType="single",
             label=_translate("Buttons"),
             hint=_translate(
                 "Keys to treat as buttons (in order of what button index you want them to be). "
                 "Must be the same length as the number of buttons."
             )
         )
+    
+    def writeDeviceCode(self, buff):
+        """
+        Code to setup a device with this backend.
 
-        return params, order
-
-    def addRequirements(self):
-        # no requirements needed - so just return
-        return
-
-    def writeDeviceCode(self: ButtonBoxComponent, buff):
-        # get inits
-        inits = getInitVals(self.params)
-        # make ButtonGroup object
+        Parameters
+        ----------
+        buff : io.StringIO
+            Text buffer to write code to.
+        """
+        # write basic code
+        self.writeBaseDeviceCode(buff, close=False)
+        # add param and close
         code = (
-            "deviceManager.addDevice(\n"
-            "    deviceClass='psychopy.hardware.button.KeyboardButtonBox',\n"
-            "    deviceName=%(deviceLabel)s,\n"
             "    buttons=%(kbButtonAliases)s,\n"
             ")\n"
         )
-        buff.writeOnceIndentedLines(code % inits)
+        buff.writeIndentedLines(code % self.params)
+
+
+# register backend with Component
+ButtonBoxComponent.registerBackend(KeyboardButtonBoxDeviceBackend)