psychopy 2024.2.4__py3-none-any.whl → 2025.1.0__py3-none-any.whl

psychopy/tools/stimulustools.py

@@ -5,6 +5,15 @@ For example, lists of styles for Form/Slider, so that these static values
 can be quickly imported from here rather than importing `psychopy.visual` (which is slow)
 """
 
+import inspect
+import json
+import importlib
+import numpy as np
+from psychopy import logging
+from psychopy.tools.attributetools import attributeSetter
+from pathlib import Path
+
+
 formStyles = {
     'light': {
         'fillColor': [0.89, 0.89, 0.89],
@@ -12,7 +21,7 @@ formStyles = {
         'itemColor': 'black',
         'responseColor': 'black',
         'markerColor': [0.89, -0.35, -0.28],
-        'font': "Open Sans",
+        'font': "Noto Sans",
     },
     'dark': {
         'fillColor': [-0.19, -0.19, -0.14],
@@ -20,9 +29,170 @@ formStyles = {
         'itemColor': 'white',
         'responseColor': 'white',
         'markerColor': [0.89, -0.35, -0.28],
-        'font': "Open Sans",
+        'font': "Noto Sans",
     },
 }
 
 sliderStyles = ['slider', 'rating', 'radio', 'scrollbar', 'choice']
 sliderStyleTweaks = ['labels45', 'triangleMarker']
+
+
+class SerializationError(Exception):
+    """
+    Error raised when serialize is called on a value which is not serializable.
+    """
+    pass
+
+
+def serialize(obj, includeClass=True):
+    """
+    Get a JSON serializable dict representation of this stimulus, useful for recreating it in a 
+    different process. Will attempt to create a dict based on the object's `__init__` method, so 
+    that this can be used to create a new copy of the object. Attributes which are themselves 
+    serializable will be recursively serialized.
+
+    Parameters
+    ----------
+    obj : object
+        Object to serialize.
+    includeClass : bool
+        If True, serialized output will include a field `__class__` with the full path of the 
+        object's class.
+    
+    Raises
+    ------
+    SerializationError
+        If the object is not already serialized and cannot be serialized.
+    
+    Returns
+    -------
+    dict
+        Dict representing the, if not already serializable.
+    """
+    # handle numpy types
+    if isinstance(obj, np.integer):
+        obj = int(obj)
+    elif isinstance(obj, np.floating):
+        obj = float(obj)
+    elif isinstance(obj, np.ndarray):
+        obj = obj.tolist()
+    # convert possible file paths into Path
+    try:
+        pathVal = Path(obj)
+    except:
+        pass
+    else:
+        if pathVal.is_file() or pathVal.is_dir():
+            obj = pathVal
+    # make any Path absolute so it's not dependent on cwd
+    if isinstance(obj, Path):
+        obj = str(obj.absolute())
+    # if an array, serialize items
+    if isinstance(obj, (list, tuple)):
+        return [serialize(val) for val in obj]
+    if isinstance(obj, dict):
+        return {serialize(key): serialize(val) for key, val in obj.items()}
+    # if already json serializable, return as is
+    try:
+        json.dumps(obj)
+    except TypeError:
+        pass
+    except:
+        # if we got something other than a TypeError, substitute None
+        return None
+    else:
+        return obj
+    # if object defines its own serialization, use it
+    if hasattr(obj, "serialize"):
+        return obj.serialize()
+    
+    def _getAttr(obj, param):
+        """
+        Get serialized attribute value.
+        """
+        got = False
+        # if param looks to be stored in an attribute, add it
+        if hasattr(obj, param):
+            got = True
+            value = getattr(obj, param)
+        # if we have a get method for param, get its value
+        getParam = "get" + param[0].upper() + param[1:]
+        if hasattr(obj, getParam):
+            got = True
+            value = getattr(obj, getParam)()
+        # if we couldn't get a value, raise an error
+        if not got:
+            raise SerializationError(f"Could not get value for {type(obj).__name__}.{param}")
+
+        return serialize(value, includeClass=False)
+    
+    # start off with an empty dict
+    arr = {}
+    # get init args
+    initArgs = inspect.getargspec(obj.__init__)
+    # if there are variable args, raise an error
+    if initArgs.varargs:
+        raise SerializationError("Cannot serialize object with variable args.")
+    # how many init args are required?
+    nReq = len(initArgs.args) - len(initArgs.defaults)
+    # get required params
+    for param in initArgs.args[:nReq]:
+        # skip self
+        if param == "self":
+            continue
+        # get attribute
+        arr[param] = _getAttr(obj, param)
+    # get optional params
+    for param in initArgs.args[nReq:]:
+        # get attribute, but don't worry if it fails
+        try:
+            arr[param] = _getAttr(obj, param)
+        except SerializationError:
+            pass
+    
+    # add class
+    if includeClass:
+        arr['__class__'] = type(obj).__name__
+        arr['__module__'] = type(obj).__module__
+    
+    return arr
+
+
+class ActualizationError(Exception):
+    """
+    Error raised when attempting to actualize from a dict which doesn't have the necessary info to 
+    actualize.
+    """
+    pass
+
+
+def actualize(params):
+    """
+    Create an object from a serializable dict, the kind created by `serialize`. The dict won't be 
+    serialized, so it's okay for it to have live object handles included (for example, replacing 
+    'win' with the handle of an extant Window object).
+
+    Parameters
+    ----------
+    params : dict
+        Dict describing the init parameters of an object. Should include the keys:
+        - '__class__': The name of the object's class
+        - '__module__': Import path of the module containing the object's class
+    """
+    # shallow copy dict so we can safely pop from it
+    params = params.copy()
+    # make sure we have the necessary keys
+    for key in ("__module__", "__class__"):
+        if key not in params:
+            raise ActualizationError(
+                f"Cannot actualise from dict which does not contain '{key}', dict was: {params}"
+            )
+    # get class
+    mod = importlib.import_module(params.pop('__module__'))
+    cls = getattr(mod, params.pop('__class__'))
+    # initialise
+    obj = cls(**params)
+
+    return obj
+
+

psychopy/tools/stringtools.py

@@ -55,6 +55,26 @@ def is_file(source):
     return isFile
 
 
+class RegexSearchable(str):
+    """
+    Like a string, but uses `re.search` for `in` comparisons
+
+    Example
+    -------
+    ```
+    r".*" in RegexSearchable("any text!")
+    ```
+    is the same as 
+    ```
+    bool(re.search(r".*", "any text!"))
+    ```
+    """
+    def __contains__(self, item):
+        return bool(
+            re.search(pattern=item, string=self)
+        )
+
+
 class CaseSwitcher:
     """
     Collection of static methods for switching case in strings. Can currently convert between:
@@ -230,7 +250,7 @@ class CaseSwitcher:
         return value
 
 
-def wrap(value, chars, delim=r"\s|\-"):
+def wrap(value, chars, delim=r"\s|-"):
     """
     Wrap a string at a number of characters.
 
@@ -241,7 +261,7 @@ def wrap(value, chars, delim=r"\s|\-"):
     chars : int
         Number of characters to split at
     delim : str
-        Regex string delimeter to split words at, default is a space or a hyphen (r"\s|\-")
+        Regex string delimeter to split words at, default is a space or a hyphen (r"\\s|\-")
 
     Returns
     -------

psychopy/tools/systemtools.py

@@ -6,7 +6,7 @@
 #
 
 # Part of the PsychoPy library
-# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2024 Open Science Tools Ltd.
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2025 Open Science Tools Ltd.
 # Distributed under the terms of the GNU General Public License (GPL).
 
 __all__ = [

psychopy/tools/typetools.py

@@ -2,7 +2,7 @@
 # -*- coding: utf-8 -*-
 
 # Part of the PsychoPy library
-# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2024 Open Science Tools Ltd.
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2025 Open Science Tools Ltd.
 # Distributed under the terms of the GNU General Public License (GPL).
 
 """Functions and classes related to variable type conversion

psychopy/tools/unittools.py

@@ -2,7 +2,7 @@
 # -*- coding: utf-8 -*-
 
 # Part of the PsychoPy library
-# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2024 Open Science Tools Ltd.
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2025 Open Science Tools Ltd.
 # Distributed under the terms of the GNU General Public License (GPL).
 
 """Functions and classes related to unit conversion"""

psychopy/tools/versionchooser.py

@@ -2,7 +2,7 @@
 # -*- coding: utf-8 -*-
 
 # Part of the PsychoPy library
-# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2024 Open Science Tools Ltd.
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2025 Open Science Tools Ltd.
 # Distributed under the terms of the GNU General Public License (GPL).
 """PsychoPy Version Chooser to specify version within experiment scripts.
 """
@@ -77,6 +77,8 @@ def parseVersionSafely(version, fallback=Version("0")):
     # if version is already valid, do normal parsing
     if re.fullmatch(version, VERSION_PATTERN):
         return Version(version)
+    # if dev number, use value up to it
+    version = version[:version.find("dev")]
     # try stripping all but numbers, dots and keywords
     version = "".join(
         re.findall(r"\d|\.|a|b|c|rc|alpha|beta|pre|preview|post|rev|r|dev", version)

psychopy/tools/viewtools.py

@@ -5,7 +5,7 @@
 """
 
 # Part of the PsychoPy library
-# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2024 Open Science Tools Ltd.
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2025 Open Science Tools Ltd.
 # Distributed under the terms of the GNU General Public License (GPL).
 
 __all__ = ['Frustum',
@@ -17,6 +17,7 @@ __all__ = ['Frustum',
            'generalizedPerspectiveProjection',
            'orthoProjectionMatrix',
            'perspectiveProjectionMatrix',
+           'viewMatrix',
            'lookAt',
            'pointToNdc',
            'cursorToRay',
@@ -92,6 +93,9 @@ def visualAngle(size, distance, degrees=True, out=None, dtype=None):
         if degrees:
             toReturn[:] = np.degrees(toReturn, dtype=dtype)
 
+    if toReturn.size == 1:
+        return toReturn.item()  # return scalar
+
     return toReturn
 
 
@@ -487,7 +491,13 @@ def generalizedPerspectiveProjection(posBottomLeft,
 
     # projection matrix to return
     projMat = perspectiveProjectionMatrix(
-        left, right, bottom, top, nearClip, farClip, dtype=dtype)
+        left.item(), 
+        right.item(), 
+        bottom.item(), 
+        top.item(), 
+        nearClip.item(), 
+        farClip.item(), 
+        dtype=dtype)
 
     # view matrix to return, first compute the rotation component
     rotMat = np.zeros((4, 4), dtype=dtype)
@@ -630,74 +640,6 @@ def perspectiveProjectionMatrix(left, right, bottom, top, nearClip=0.01,
     return projMat
 
 
-def lookAt(eyePos, centerPos, upVec=(0.0, 1.0, 0.0), out=None, dtype=None):
-    """Create a transformation matrix to orient a view towards some point. Based
-    on the same algorithm as 'gluLookAt'. This does not generate a projection
-    matrix, but rather the matrix to transform the observer's view in the scene.
-
-    For more information see:
-    https://www.khronos.org/registry/OpenGL-Refpages/gl2.1/xhtml/gluLookAt.xml
-
-    Parameters
-    ----------
-    eyePos : list of float or ndarray
-        Eye position in the scene.
-    centerPos : list of float or ndarray
-        Position of the object center in the scene.
-    upVec : list of float or ndarray, optional
-        Vector defining the up vector. Default is +Y is up.
-    out : ndarray, optional
-        Optional output array. Must be same `shape` and `dtype` as the expected
-        output if `out` was not specified.
-    dtype : dtype or str, optional
-        Data type for arrays, can either be 'float32' or 'float64'. If `None` is
-        specified, the data type is inferred by `out`. If `out` is not provided,
-        the default is 'float64'.
-
-    Returns
-    -------
-    ndarray
-        4x4 view matrix
-
-    Notes
-    -----
-
-    * The returned matrix is row-major. Values are floats with 32-bits of
-      precision stored as a contiguous (C-order) array.
-
-    """
-    if out is None:
-        dtype = np.float64 if dtype is None else np.dtype(dtype).type
-    else:
-        dtype = np.dtype(out.dtype).type
-
-    toReturn = np.zeros((4, 4,), dtype=dtype) if out is None else out
-    if out is not None:
-        toReturn.fill(0.0)
-
-    eyePos = np.asarray(eyePos, dtype=dtype)
-    centerPos = np.asarray(centerPos, dtype=dtype)
-    upVec = np.asarray(upVec, dtype=dtype)
-
-    f = centerPos - eyePos
-    f /= np.linalg.norm(f)
-    upVec /= np.linalg.norm(upVec)
-
-    s = np.cross(f, upVec)
-    u = np.cross(s / np.linalg.norm(s), f)
-
-    rotMat = np.zeros((4, 4), dtype=dtype)
-    rotMat[0, :3] = s
-    rotMat[1, :3] = u
-    rotMat[2, :3] = -f
-    rotMat[3, 3] = 1.0
-
-    transMat = np.identity(4, dtype=dtype)
-    transMat[:3, 3] = -eyePos
-
-    return np.matmul(rotMat, transMat, out=toReturn)
-
-
 def viewMatrix(pos, ori=(0., 0., 0., -1.), out=None, dtype=None):
     """Get a view matrix from a pose.
 
@@ -931,6 +873,48 @@ def cursorToRay(cursorX, cursorY, winSize, viewport, projectionMatrix,
     return toReturn
 
 
+def lookAt(eyePos, centerPos, upVec=(0.0, 1.0, 0.0), out=None, dtype=None):
+    """Create a transformation matrix to orient a view towards some point. 
+    
+    Based on the same algorithm as 'gluLookAt'. This does not generate a 
+    projection matrix, but rather the matrix to transform the observer's view in 
+    the scene.
+
+    For more information see:
+    https://www.khronos.org/registry/OpenGL-Refpages/gl2.1/xhtml/gluLookAt.xml
+
+    Parameters
+    ----------
+    eyePos : list of float or ndarray
+        Eye position in the scene.
+    centerPos : list of float or ndarray
+        Position of the object center in the scene.
+    upVec : list of float or ndarray, optional
+        Vector defining the up vector. Default is +Y is up.
+    out : ndarray, optional
+        Optional output array. Must be same `shape` and `dtype` as the expected
+        output if `out` was not specified.
+    dtype : dtype or str, optional
+        Data type for arrays, can either be 'float32' or 'float64'. If `None` is
+        specified, the data type is inferred by `out`. If `out` is not provided,
+        the default is 'float64'.
+
+    Returns
+    -------
+    ndarray
+        4x4 view matrix
+
+    Notes
+    -----
+    * This function is an alias of `mathtools.lookAt`, it is not imported when
+      importing all.
+    * The returned matrix is row-major. Values are floats with 32-bits of
+      precision stored as a contiguous (C-order) array.
+
+    """
+    return mt.lookAt(eyePos, centerPos, upVec, out=out, dtype=dtype)
+
+
 def visibleBBox(extents, mvp, dtype=None):
     """Check if a bounding box is visible.
 

psychopy/tools/wizard.py

@@ -5,7 +5,7 @@
 """
 
 # Part of the PsychoPy library
-# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2024 Open Science Tools Ltd.
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2025 Open Science Tools Ltd.
 # Distributed under the terms of the GNU General Public License (GPL).
 
 # Author: Jeremy Gray, Oct 2012; localization 2014
@@ -349,7 +349,7 @@ class BaseWizard():
         """
 
         imgfile = os.path.join(self.prefs.paths['resources'],
-                               'psychopySplash.png')
+                               'splash.png')
         _head = (u'<html><head><meta http-equiv="Content-Type" '
                  'content="text/html; charset=utf-8"></head><body>' +
                  '<a href="https://www.psychopy.org"><img src="%s" '

psychopy/validation/__init__.py

@@ -0,0 +1,6 @@
+"""
+This module contains classes for validating stimulus presentation times using a variety of methods.
+"""
+
+from .audio import AudioValidator, AudioValidationError
+from .visual import VisualValidator, VisualValidationError

psychopy/validation/audio.py

@@ -0,0 +1,74 @@
+from psychopy import logging
+
+
+class AudioValidationError(BaseException):
+    pass
+
+
+class AudioValidator:
+
+    def __init__(
+            self, 
+            sensor, channel=None,
+            autoLog=False):
+        # set autolog
+        self.autoLog = autoLog
+        # store voicekey handle
+        self.sensor = sensor
+        self.channel = channel
+        # initial values (written during experiment)
+        self.tStart = self.tStartRefresh = self.tStartDelay = None
+        self.tStop = self.tStopRefresh = self.tStopDelay = None
+
+    def connectStimulus(self, stim):
+        # store mapping of stimulus to self in window
+        stim.validator = self
+
+    def validate(self, state, t=None, adjustment=0):
+        """
+        Confirm that stimulus was shown/hidden at the correct time, to within an acceptable margin of variability.
+
+        Parameters
+        ----------
+        state : bool
+            State which the voicekey is expected to have been in
+        t : clock.Timestamp, visual.Window or None
+            Time at which the voicekey should have read the given state.
+        adjustment : float
+            Adjustment to apply to the received timestamp - in order to account for silent periods 
+            at the start/end of a particular sound. These should be positive for silence at the 
+            start and negative for silence at the end.
+
+        Returns
+        -------
+        float
+            Start/stop time according to the voicekey
+        float
+            Delay between requested start/stop time and measured start/stop time
+        """
+        # if there's no time to validate, return empty handed
+        if t is None:
+            return None, None
+
+        # get and clear responses
+        messages = self.sensor.getResponses(state=state, channel=self.channel, clear=True)
+        # if there have been no responses yet, return empty handed
+        if not messages:
+            return None, None
+
+        # if there are responses, get most recent timestamp
+        lastTime = messages[-1].t
+        # if there's no time on the last message, return empty handed
+        if lastTime is None:
+            return None, None
+        # validate
+        delay = lastTime - adjustment - t
+
+        # return timestamp and validity
+        return lastTime, delay
+
+    def resetTimer(self, clock=logging.defaultClock):
+        self.sensor.resetTimer(clock=clock)
+
+    def getSensorState(self):
+        return self.sensor.getState()

psychopy/validation/visual.py

@@ -0,0 +1,115 @@
+from psychopy import layout, logging
+
+
+class VisualValidationError(BaseException):
+    pass
+
+
+class VisualValidator:
+
+    def __init__(
+            self, win, sensor, channel=None,
+            autoLog=False):
+        # set autolog
+        self.autoLog = autoLog
+        # store window handle
+        self.win = win
+        # store sensor handle
+        self.sensor = sensor
+        self.channel = channel
+        # initial values (written during experiment)
+        self.tStart = self.tStartRefresh = self.tStartDelay = None
+        self.tStop = self.tStopRefresh = self.tStopDelay = None
+
+        from psychopy import visual
+        # black rect which is always drawn on win flip
+        self.offRect = visual.Rect(
+            win,
+            fillColor="black",
+            depth=1, autoDraw=True,
+            autoLog=False
+        )
+        # white rect which is only drawn when target stim is, and covers black rect
+        self.onRect = visual.Rect(
+            win,
+            fillColor="white",
+            depth=0, autoDraw=False,
+            autoLog=False
+        )
+        # update rects to match sensor
+        self.updateRects()
+
+    def connectStimulus(self, stim):
+        # store mapping of stimulus to self in window
+        self.win.validators[stim] = self
+        stim.validator = self
+
+    def draw(self):
+        self.onRect.draw()
+
+    def updateRects(self):
+        """
+        Update the size and position of this validator's rectangles to match the size and position of the associated
+        sensor.
+        """
+        for rect in (self.onRect, self.offRect):
+            # set units from sensor
+            rect.units = self.sensor.units
+            # set pos from sensor, or choose default if None
+            if self.sensor.pos is not None:
+                rect.pos = self.sensor.pos
+            else:
+                rect.pos = layout.Position((0.95, -0.95), units="norm", win=self.win)
+            # set size from sensor, or choose default if None
+            if self.sensor.size is not None:
+                rect.size = self.sensor.size
+            else:
+                rect.size = layout.Size((0.05, 0.05), units="norm", win=self.win)
+
+    def validate(self, state, t=None, adjustment=0):
+        """
+        Confirm that stimulus was shown/hidden at the correct time, to within an acceptable margin of variability.
+
+        Parameters
+        ----------
+        state : bool
+            State which the light sensor is expected to have been in
+        t : clock.Timestamp, visual.Window or None
+            Time at which the light sensor should have read the given state.
+        adjustment : float
+            Adjustment to apply to the received timestamp - in order to account for e.g. an 
+            expected flip time
+
+        Returns
+        -------
+        float
+            Start/stop time according to the light sensor
+        float
+            Delay between requested start/stop time and measured start/stop time
+        """
+        # if there's no time to validate, return empty handed
+        if t is None:
+            return None, None
+
+        # get and clear responses
+        messages = self.sensor.getResponses(state=state, channel=self.channel, clear=True)
+        # if there have been no responses yet, return empty handed
+        if not messages:
+            return None, None
+
+        # if there are responses, get most recent timestamp
+        lastTime = messages[-1].t
+        # if there's no time on the last message, return empty handed
+        if lastTime is None:
+            return None, None
+        # validate
+        delay = lastTime - adjustment - t
+
+        # return timestamp and validity
+        return lastTime, delay
+
+    def resetTimer(self, clock=logging.defaultClock):
+        self.sensor.resetTimer(clock=clock)
+
+    def getSensorState(self):
+        return self.sensor.getState()

psychopy/visual/__init__.py

@@ -2,7 +2,7 @@
 # -*- coding: utf-8 -*-
 
 # Part of the PsychoPy library
-# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2024 Open Science Tools Ltd.
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2025 Open Science Tools Ltd.
 # Distributed under the terms of the GNU General Public License (GPL).
 
 """Container for all visual-related functions and classes
@@ -70,9 +70,6 @@ from psychopy.visual.dot import DotStim
 from psychopy.visual.grating import GratingStim
 from psychopy.visual.secondorder import EnvelopeGrating
 from psychopy.visual.movies import MovieStim
-from psychopy.visual.movie2 import MovieStim2
-from psychopy.visual.movie3 import MovieStim3
-from psychopy.visual.vlcmoviestim import VlcMovieStim
 from psychopy.visual.shape import BaseShapeStim
 
 # stimuli derived from GratingStim