psychopy 2024.1.1__py3-none-any.whl → 2024.1.3__py3-none-any.whl

psychopy/demos/coder/timing/timeByFrames.py

@@ -15,8 +15,14 @@ from psychopy import visual, logging, core, event
 visual.useFBO = True  # if available (try without for comparison)
 
 import matplotlib
-matplotlib.use('QtAgg')  # change this to control the plotting 'back end'
 import pylab
+import sys
+if sys.platform == "darwin":
+    # on Mac...
+    matplotlib.use('QtAgg')
+else:
+    # on any other OS...
+    matplotlib.use('Qt4Agg')
 
 nIntervals = 500
 win = visual.Window([1280, 1024], fullscr=True, allowGUI=False, waitBlanking=True)

psychopy/experiment/components/_base.py

@@ -7,6 +7,7 @@ Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2024 Open Science Tools Ltd.
 Distributed under the terms of the GNU General Public License (GPL).
 """
 import copy
+import textwrap
 from pathlib import Path
 from xml.etree.ElementTree import Element
 
@@ -35,6 +36,8 @@ class BaseComponent:
     tooltip = ""
     # what version was this Component added in?
     version = "0.0.0"
+    # is it still in beta?
+    beta = False
 
     def __init__(self, exp, parentName, name='',
                  startType='time (s)', startVal='',
@@ -1035,6 +1038,125 @@ class BaseComponent:
         # if validation code indented the buffer, dedent
         buff.setIndentLevel(-indent, relative=True)
 
+    def getFullDocumentation(self, fmt="rst"):
+        """
+        Automatically generate documentation for this Component. We recommend using this as a
+        starting point, but checking the documentation yourself afterwards and adding any more
+        detail you'd like to include (e.g. usage examples)
+
+        Parameters
+        ----------
+        fmt : str
+            Format to write documentation in. One of:
+            - "rst": Restructured text (numpy style)
+            -"md": Markdown (mkdocs style)
+        """
+
+        # make sure format is correct
+        assert fmt in ("md", "rst"), (
+            f"Unrecognised format {fmt}, allowed formats are 'md' and 'rst'."
+        )
+        # define templates for md and rst
+        h1 = {
+            'md': "# %s",
+            'rst': (
+                "-------------------------------\n"
+                "%s\n"
+                "-------------------------------"
+            )
+        }[fmt]
+        h2 = {
+            'md': "## %s",
+            'rst': (
+                "%s\n"
+                "-------------------------------"
+            )
+        }[fmt]
+        h3 = {
+            'md': "### %s",
+            'rst': (
+                "%s\n"
+                "==============================="
+            )
+        }[fmt]
+        h4 = {
+            'md': "#### `%s`",
+            'rst': "%s"
+        }[fmt]
+
+        # start off with nothing
+        content = ""
+        # header and class docstring
+        content += (
+            f"{h1 % type(self).__name__}\n"
+            f"{textwrap.dedent(self.__doc__ or '')}\n"
+            f"\n"
+        )
+        # attributes
+        content += (
+            f"{h4 % 'Categories:'}\n"
+            f"    {', '.join(self.categories)}\n"
+            f"{h4 % 'Works in:'}\n"
+            f"    {', '.join(self.targets)}\n"
+            f"\n"
+        )
+        # beta warning
+        if self.beta:
+            content += (
+                f"**Note: Since this is still in beta, keep an eye out for bug fixes.**\n"
+                f"\n"
+            )
+        # params heading
+        content += (
+            f"{h2 % 'Parameters'}\n"
+            f"\n"
+        )
+        # sort params by category
+        byCateg = {}
+        for param in self.params.values():
+            if param.categ not in byCateg:
+                byCateg[param.categ] = []
+            byCateg[param.categ].append(param)
+        # iterate through categs
+        for categ, params in byCateg.items():
+            # write a heading for each categ
+            content += (
+                f"{h3 % categ}\n"
+                f"\n"
+            )
+            # add each param...
+            for param in params:
+                # write basics (heading and description)
+                content += (
+                    f"{h4 % param.label}\n"
+                    f"    {param.hint}\n"
+                )
+                # if there are options, display them
+                if bool(param.allowedVals) or bool(param.allowedLabels):
+                    # if no allowed labels, use allowed vals
+                    options = param.allowedLabels or param.allowedVals
+                    # handle callable methods
+                    if callable(options):
+                        content += (
+                            f"\n"
+                            f"    Options are generated live, so will vary according to your setup.\n"
+                        )
+                    else:
+                        # write heading
+                        content += (
+                            f"    \n"
+                            f"    Options:\n"
+                        )
+                        # add list item for each option
+                        for opt in options:
+                            content += (
+                                f"    - {opt}\n"
+                            )
+                # add newline at the end
+                content += "\n"
+
+        return content
+
     @property
     def name(self):
         return self.params['name'].val

psychopy/experiment/components/aperture/__init__.py

@@ -17,8 +17,12 @@ __author__ = 'Jeremy Gray, Jon Peirce'
 
 
 class ApertureComponent(PolygonComponent):
-    """An event class for using GL stencil to restrict the viewing area to a
-    circle or square of a given size and position"""
+    """
+    This component can be used to filter the visual display, as if the subject is looking at it
+    through an opening (i.e. add an image component, as the background image, then add an aperture
+    to show part of the image). Only one aperture is enabled at a time; you can't "double up": a
+    second aperture takes precedence.
+    """
 
     categories = ['Stimuli']
     targets = ['PsychoPy']

psychopy/experiment/components/brush/__init__.py

@@ -10,7 +10,9 @@ from psychopy.experiment.components import BaseVisualComponent, Param, getInitVa
 
 
 class BrushComponent(BaseVisualComponent):
-    """A class for drawing freehand responses"""
+    """
+    This component is a freehand drawing tool.
+    """
 
     categories = ['Responses']
     targets = ['PsychoPy', 'PsychoJS']

psychopy/experiment/components/button/__init__.py

@@ -15,7 +15,12 @@ from psychopy.experiment.py2js_transpiler import translatePythonToJavaScript
 
 class ButtonComponent(BaseVisualComponent):
     """
-    A component for presenting a clickable textbox with a programmable callback
+    This component allows you to show a static textbox which ends the routine and/or triggers
+    a "callback" (some custom code) when pressed. The nice thing about the button component is
+    that you can allow mouse/touch responses with a single component instead of needing 3 separate
+    components i.e. a textbox component (to display as a "clickable" thing), a mouse component
+    (to click the textbox) and a code component (not essential, but for example to check if a
+    clicked response was correct or incorrect).
     """
     categories = ['Responses']
     targets = ['PsychoPy', 'PsychoJS']
@@ -365,7 +370,6 @@ class ButtonComponent(BaseVisualComponent):
         code = (
                         "// store time of first click\n"
                         "%(name)s.timesOn.push(%(name)s.clock.getTime());\n"
-                        "%(name)s.numClicks += 1;\n"
                         "// store time clicked until\n"
                         "%(name)s.timesOff.push(%(name)s.clock.getTime());\n"
         )

psychopy/experiment/components/buttonBox/__init__.py

@@ -6,12 +6,13 @@ from psychopy.localization import _translate
 
 class ButtonBoxComponent(BaseDeviceComponent, PluginDevicesMixin):
     """
-
+    Component for getting button presses from a button box device.
     """
     categories = ['Responses']  # which section(s) in the components panel
     targets = ['PsychoPy']
     iconFile = Path(__file__).parent / 'buttonBox.png'
     tooltip = _translate('Button Box: Get input from a button box')
+    beta = True
 
     def __init__(
             self, exp, parentName,

psychopy/experiment/components/camera/__init__.py

@@ -27,6 +27,19 @@ micSampleRates = {r[1]: r[0] for r in sampleRateQualityLevels.values()}
 
 
 class CameraComponent(BaseDeviceComponent):
+    """
+    This component provides a way to use the webcam to record participants during an experiment.
+
+    **Note: For online experiments, the browser will notify participants to allow use of webcam before the start of the task.**
+
+    When recording via webcam, specify the starting time relative to the start of the routine (see `start` below) and a stop time (= duration in seconds).
+    A blank duration evaluates to recording for 0.000s.
+
+    The resulting video files are saved in .mp4 format if recorded locally and saved in .webm if recorded online. There will be one file per recording. The files appear in a new folder within the data directory in a folder called data_cam_recorded. The file names include the unix (epoch) time of the onset of the recording with milliseconds, e.g., `recording_cam_2022-06-16_14h32.42.064.mp4`.
+
+    **Note: For online experiments, the recordings can only be downloaded from the "Download results" button from the study's Pavlovia page.**
+    """
+
     categories = ['Responses']
     targets = ["PsychoPy", "PsychoJS"]
     version = "2022.2.0"

psychopy/experiment/components/code/__init__.py

@@ -12,7 +12,40 @@ from psychopy.alerts import alerttools
 
 
 class CodeComponent(BaseComponent):
-    """An event class for inserting arbitrary code into Builder experiments"""
+    """
+    This Component can be used to insert short pieces of python code into your experiments. This
+    might be create a variable that you want for another :ref:`Component <components>`,
+    to manipulate images before displaying them, to interact with hardware for which there isn't
+    yet a pre-packaged component in |PsychoPy| (e.g. writing code to interact with the
+    serial/parallel ports). See `code uses`_ below.
+
+    Be aware that the code for each of the components in your :ref:`Routine <routines>` are
+    executed in the order they appear on the :ref:`Routine <routines>` display (from top to
+    bottom). If you want your `Code Component` to alter a variable to be used by another
+    component immediately, then it needs to be above that component in the view. You may want the
+    code not to take effect until next frame however, in which case put it at the bottom of the
+    :ref:`Routine <routines>`. You can move `Components` up and down the :ref:`Routine <routines>`
+    by right-clicking on their icons.
+
+    Within your code you can use other variables and modules from the script. For example, all
+    routines have a stopwatch-style :class:`~psychopy.core.Clock` associated with them, which
+    gets reset at the beginning of that repeat of the routine. So if you have a :ref:`Routine
+    <routines>` called trial, there will be a :class:`~psychopy.core.Clock` called trialClock and
+    so you can get the time (in sec) from the beginning of the trial by using::
+
+        currentT = trialClock.getTime()
+
+    To see what other variables you might want to use, and also what terms you need to avoid in
+    your chunks of code, :ref:`compile your script <compileScript>` before inserting the code
+    object and take a look at the contents of that script.
+
+    Note that this page is concerned with `Code Components` specifically, and not all cases in
+    which you might use python syntax within the Builder. It is also possible to put code into
+    a non-code input field (such as the duration or text of a `Text Component`). The syntax there
+    is slightly different (requiring a `$` to trigger the special handling, or `\\$` to avoid
+    triggering special handling). The syntax to use within a Code Component is always regular
+    python syntax.
+    """
 
     categories = ['Custom']
     targets = ['PsychoPy', 'PsychoJS']

psychopy/experiment/components/mouse/__init__.py

@@ -364,10 +364,22 @@ class MouseComponent(BaseComponent):
             buff.writeIndentedLines(code % self.params)
             buff.setIndentLevel(1, relative=True)
             dedent += 1
+            # keep track of whether something's been written
+            hasContent = False
+            # write code to check clickable stim, if there are any
             if self.params['clickable'].val:
                 self._writeClickableObjectsCode(buff)
+                hasContent = True
+            # write code to check correct stim, if there are any
             if self.params['storeCorrect']:
                 self._writeCorrectAnsCode(buff)
+                hasContent = True
+            # if current if statement has no content, add a pass
+            if not hasContent:
+                buff.writeIndentedLines(
+                    "pass"
+                )
+
             return buff, dedent
 
         # No mouse tracking, end routine on any or valid click

psychopy/experiment/components/polygon/__init__.py

@@ -279,9 +279,20 @@ class PolygonComponent(BaseVisualComponent):
         code += ("  ori: {ori}, pos: {pos},\n"
                  "  anchor: {anchor},\n"
                  "  lineWidth: {lineWidth}, \n"
-                 "  colorSpace: {colorSpace},\n"
-                 "  lineColor: new util.Color({lineColor}),\n"
-                 "  fillColor: new util.Color({fillColor}),\n"
+                 "  colorSpace: {colorSpace},\n")      
+
+        if inits['lineColor'] == 'undefined':
+            code +=  "  lineColor: {lineColor},\n"
+        else:    
+            code +=  "  lineColor: new util.Color({lineColor}),\n"
+
+        if inits['fillColor'] == 'undefined':
+            code +=  "  fillColor: {fillColor},\n"
+        else:    
+            code +=  "  fillColor: new util.Color({fillColor}),\n"
+
+
+        code += (        "  fillColor: {fillColor},\n"
                  "  opacity: {opacity}, depth: {depth}, interpolate: {interpolate},\n"
                  "}});\n\n")
 

psychopy/experiment/components/settings/__init__.py

@@ -993,12 +993,15 @@ class SettingsComponent:
             "PILOTING = core.setPilotModeFromArgs()\n"
             "# start off with values from experiment settings\n"
             "_fullScr = %(Full-screen window)s\n"
+            "_winSize = %(Window size (pixels))s\n"
             "_loggingLevel = logging.getLevel('%(logging level)s')\n"
             "# if in pilot mode, apply overrides according to preferences\n"
             "if PILOTING:\n"
             "    # force windowed mode\n"
             "    if prefs.piloting['forceWindowed']:\n"
             "        _fullScr = False\n"
+            "        # set window size\n"
+            "        _winSize = prefs.piloting['forcedWindowSize']\n"
             "    # override logging level\n"
             "    _loggingLevel = logging.getLevel(\n"
             "        prefs.piloting['pilotLoggingLevel']\n"
@@ -1796,7 +1799,7 @@ class SettingsComponent:
             "if win is None:\n"
             "    # if not given a window to setup, make one\n"
             "    win = visual.Window(\n"
-            "        size=%(size)s, fullscr=_fullScr, screen=%(screenNumber)s,\n"
+            "        size=_winSize, fullscr=_fullScr, screen=%(screenNumber)s,\n"
             "        winType=%(winType)s, allowStencil=%(allowStencil)s,\n"
             "        monitor=%(Monitor)s, color=%(color)s, colorSpace=%(colorSpace)s,\n"
             "        backgroundImage=%(backgroundImg)s, backgroundFit=%(backgroundFit)s,\n"

psychopy/experiment/components/sound/__init__.py

@@ -63,7 +63,7 @@ class SoundComponent(BaseDeviceComponent):
                          " to specify Hz (e.g. 440) or a filename")
         self.params['sound'] = Param(
             sound, valType='str', inputType="file", allowedTypes=[], updates='constant', categ='Basic',
-            allowedUpdates=['constant', 'set every repeat'],
+            allowedUpdates=['set every repeat'],
             hint=hnt,
             label=_translate("Sound"))
         _allowed = ['constant', 'set every repeat', 'set every frame']

psychopy/experiment/components/text/__init__.py

@@ -22,7 +22,7 @@ class TextComponent(BaseVisualComponent):
     def __init__(self, exp, parentName, name='text',
                  # effectively just a display-value
                  text=_translate('Any text\n\nincluding line breaks'),
-                 font='Open Sans', units='from exp settings',
+                 font='Arial', units='from exp settings',
                  color='white', colorSpace='rgb',
                  pos=(0, 0), letterHeight=0.05, ori=0,
                  startType='time (s)', startVal=0.0,

psychopy/experiment/params.py

@@ -312,6 +312,23 @@ class Param():
         # if not a clear alias, use bool method of value
         return bool(self.val)
 
+    def __deepcopy__(self, memo):
+        return Param(
+            val=self.val,
+            valType=self.valType,
+            inputType=self.inputType,
+            allowedVals=self.allowedVals,
+            allowedTypes=self.allowedTypes,
+            hint=self.hint,
+            label=self.label,
+            updates=self.updates,
+            allowedUpdates=self.allowedUpdates,
+            allowedLabels=self.allowedLabels,
+            direct=self.direct,
+            canBePath=self.canBePath,
+            categ=self.categ
+        )
+
     @property
     def _xml(self):
         # Make root element

psychopy/experiment/routines/_base.py

@@ -8,6 +8,7 @@
 """Describes the Flow of an experiment
 """
 import copy
+import textwrap
 
 from psychopy.constants import FOREVER
 from xml.etree.ElementTree import Element
@@ -27,6 +28,8 @@ class BaseStandaloneRoutine:
     limit = float('inf')
     # what version was this Routine added in?
     version = "0.0.0"
+    # is it still in beta?
+    beta = False
 
     def __init__(self, exp, name='',
                  stopType='duration (s)', stopVal='',
@@ -225,6 +228,125 @@ class BaseStandaloneRoutine:
     def getStatics(self):
         return []
 
+    def getFullDocumentation(self, fmt="rst"):
+        """
+        Automatically generate documentation for this Component. We recommend using this as a
+        starting point, but checking the documentation yourself afterwards and adding any more
+        detail you'd like to include (e.g. usage examples)
+
+        Parameters
+        ----------
+        fmt : str
+            Format to write documentation in. One of:
+            - "rst": Restructured text (numpy style)
+            -"md": Markdown (mkdocs style)
+        """
+
+        # make sure format is correct
+        assert fmt in ("md", "rst"), (
+            f"Unrecognised format {fmt}, allowed formats are 'md' and 'rst'."
+        )
+        # define templates for md and rst
+        h1 = {
+            'md': "# %s",
+            'rst': (
+                "-------------------------------\n"
+                "%s\n"
+                "-------------------------------"
+            )
+        }[fmt]
+        h2 = {
+            'md': "## %s",
+            'rst': (
+                "%s\n"
+                "-------------------------------"
+            )
+        }[fmt]
+        h3 = {
+            'md': "### %s",
+            'rst': (
+                "%s\n"
+                "==============================="
+            )
+        }[fmt]
+        h4 = {
+            'md': "#### `%s`",
+            'rst': "%s"
+        }[fmt]
+
+        # start off with nothing
+        content = ""
+        # header and class docstring
+        content += (
+            f"{h1 % type(self).__name__}\n"
+            f"{textwrap.dedent(self.__doc__ or '')}\n"
+            f"\n"
+        )
+        # attributes
+        content += (
+            f"{h4 % 'Categories:'}\n"
+            f"    {', '.join(self.categories)}\n"
+            f"{h4 % 'Works in:'}\n"
+            f"    {', '.join(self.targets)}\n"
+            f"\n"
+        )
+        # beta warning
+        if self.beta:
+            content += (
+                f"**Note: Since this is still in beta, keep an eye out for bug fixes.**\n"
+                f"\n"
+            )
+        # params heading
+        content += (
+            f"{h2 % 'Parameters'}\n"
+            f"\n"
+        )
+        # sort params by category
+        byCateg = {}
+        for param in self.params.values():
+            if param.categ not in byCateg:
+                byCateg[param.categ] = []
+            byCateg[param.categ].append(param)
+        # iterate through categs
+        for categ, params in byCateg.items():
+            # write a heading for each categ
+            content += (
+                f"{h3 % categ}\n"
+                f"\n"
+            )
+            # add each param...
+            for param in params:
+                # write basics (heading and description)
+                content += (
+                    f"{h4 % param.label}\n"
+                    f"    {param.hint}\n"
+                )
+                # if there are options, display them
+                if bool(param.allowedVals) or bool(param.allowedLabels):
+                    # if no allowed labels, use allowed vals
+                    options = param.allowedLabels or param.allowedVals
+                    # handle callable methods
+                    if callable(options):
+                        content += (
+                            f"\n"
+                            f"    Options are generated live, so will vary according to your setup.\n"
+                        )
+                    else:
+                        # write heading
+                        content += (
+                            f"    \n"
+                            f"    Options:\n"
+                        )
+                        # add list item for each option
+                        for opt in options:
+                            content += (
+                                f"    - {opt}\n"
+                            )
+                # add newline at the end
+                content += "\n"
+
+        return content
+
     @property
     def name(self):
         if hasattr(self, 'params'):

psychopy/experiment/routines/counterbalance/__init__.py

@@ -43,7 +43,7 @@ class CounterbalanceRoutine(BaseStandaloneRoutine):
         self.params['specMode'] = Param(
             specMode, valType="str", inputType="choice", categ="Basic",
             allowedVals=["uniform", "file"],
-            allowedLabels=[_translate("Num. groups"), _translate("Conditions file")],
+            allowedLabels=[_translate("Num. groups"), _translate("Conditions file (local only)")],
             label=_translate("Groups from..."),
             hint=_translate(
                 "Specify groups using an Excel file (for fine tuned control), specify as a variable name, or specify a "

psychopy/hardware/button.py

@@ -177,10 +177,11 @@ class ButtonBox:
             if device in DeviceManager.devices:
                 self.device = DeviceManager.getDevice(device)
             else:
+                # don't use formatted string literals in _translate()
                 raise ValueError(_translate(
-                    f"Could not find device named '{device}', make sure it has been set up "
-                    f"in DeviceManager."
-                ))
+                    "Could not find device named '{device}', make sure it has been set up "
+                    "in DeviceManager."
+                ).format(device))
 
         # starting value for status (Builder)
         self.status = constants.NOT_STARTED

psychopy/hardware/camera/__init__.py

@@ -2196,6 +2196,9 @@ class Camera:
     def stop(self):
         """Stop recording frames and audio (if available).
         """
+        if self._captureThread is None:  # do nothing if not open
+            return
+
         if not self._captureThread.isOpen():
             raise RuntimeError("Cannot stop recording, stream is not open.")
 
@@ -2217,6 +2220,9 @@ class Camera:
         to save the frames to disk.
 
         """
+        if self._captureThread is None:  # nop
+            return
+
         if not self._captureThread.isOpen():
             raise RuntimeError("Cannot close stream, stream is not open.")
         

psychopy/hardware/keyboard.py

@@ -206,8 +206,13 @@ class Keyboard(AttributeGetSetMixin):
         self.rt = []  # response time(s)
         self.time = []  # Epoch
 
-        # get clock from device
-        self.clock = self.device.clock
+    @property
+    def clock(self):
+        return self.device.clock
+
+    @clock.setter
+    def clock(self, value):
+        self.device.clock = value
 
     def getBackend(self):
         return self.device.getBackend()
@@ -568,7 +573,7 @@ class KeyboardDevice(BaseResponseDevice, aliases=["keyboard"]):
             if message.type == "KEYBOARD_PRESS":
                 # if message is from a key down event, make a new response
                 response = KeyPress(code=message.char, tDown=message.time, name=message.key)
-                response.rt = response.tDown
+                response.rt = response.tDown - self.clock.getLastResetTime()
                 self._keysStillDown.append(response)
             else:
                 # if message is from a key up event, alter existing response

psychopy/iohub/devices/eyetracker/hw/gazepoint/__init__.py

@@ -6,7 +6,7 @@
 import psychopy.logging as logging
 
 try:
-    from psychopy_eyetracker_gazepoint import gp3
+    from psychopy_eyetracker_gazepoint.gazepoint import gp3
 except (ModuleNotFoundError, ImportError, NameError):
     logging.error(
         "The Gazepoint eyetracker requires package " 

psychopy/iohub/devices/eyetracker/hw/gazepoint/gp3/__init__.py

@@ -6,7 +6,7 @@
 import psychopy.logging as logging
 
 try:
-    from psychopy_eyetracker_gazepoint.gp3 import (
+    from psychopy_eyetracker_gazepoint.gazepoint.gp3 import (
         __file__,
         EyeTracker, 
         MonocularEyeSampleEvent,

psychopy/iohub/devices/eyetracker/hw/gazepoint/gp3/calibration.py

@@ -6,7 +6,7 @@
 import psychopy.logging as logging
 
 try:
-    from psychopy_eyetracker_gazepoint.gp3.calibration import (
+    from psychopy_eyetracker_gazepoint.gazepoint.gp3.calibration import (
         GazepointCalibrationProcedure)
 except (ModuleNotFoundError, ImportError, NameError):
     logging.error(