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

psychopy/visual/ratingscale.py

@@ -7,1418 +7,11 @@
 # 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 sys
-import numpy
-
-from psychopy import core, logging, event
-from psychopy.visual.circle import Circle
-from psychopy.visual.patch import PatchStim
-from psychopy.visual.shape import ShapeStim
-from psychopy.visual.text import TextStim
-from psychopy.visual.basevisual import MinimalStim
-from psychopy.visual.helpers import pointInPolygon, groupFlipVert
-from psychopy.tools.attributetools import logAttrib
-from psychopy.constants import FINISHED, STARTED, NOT_STARTED
-
-
-class RatingScale(MinimalStim):
-    """A class for obtaining ratings, e.g., on a 1-to-7 or categorical scale.
-    This is a lazy-imported class, therefore import using full path 
-    `from psychopy.visual.ratingscale import RatingScale` when inheriting
-    from it.
-
-    A RatingScale instance is a re-usable visual object having a ``draw()``
-    method, with customizable appearance and response options. ``draw()``
-    displays the rating scale, handles the subject's mouse or key responses,
-    and updates the display. When the subject accepts a selection,
-    ``.noResponse`` goes ``False`` (i.e., there is a response).
-
-    You can call the ``getRating()`` method anytime to get a rating,
-    ``getRT()`` to get the decision time, or ``getHistory()`` to obtain
-    the entire set of (rating, RT) pairs.
-
-    There are five main elements of a rating scale: the `scale`
-    (text above the line intended to be a reminder of how to use the scale),
-    the `line` (with tick marks), the `marker` (a moveable visual indicator
-    on the line), the `labels` (text below the line that label specific
-    points), and the `accept` button. The appearance and function of
-    elements can be customized by the experimenter; it is not possible
-    to orient a rating scale to be vertical. Multiple scales can be
-    displayed at the same time, and continuous real-time ratings can be
-    obtained from the history.
-
-    The Builder RatingScale component gives a restricted set of options,
-    but also allows full control over a RatingScale via the
-    'customize_everything' field.
-
-    A RatingScale instance has no idea what else is on the screen.
-    The experimenter has to draw the item to be rated, and handle `escape`
-    to break or quit, if desired. The subject can use the mouse or keys to
-    respond. Direction keys (left, right) will move the marker in the
-    smallest available increment (e.g., 1/10th of a tick-mark if
-    precision = 10).
-
-    **Example 1**:
-
-        A basic 7-point scale::
-
-            ratingScale = visual.RatingScale(win)
-            item = <statement, question, image, movie, ...>
-            while ratingScale.noResponse:
-                item.draw()
-                ratingScale.draw()
-                win.flip()
-            rating = ratingScale.getRating()
-            decisionTime = ratingScale.getRT()
-            choiceHistory = ratingScale.getHistory()
-
-    **Example 2**:
-
-        For fMRI, sometimes only a keyboard can be used. If your response
-        box sends keys 1-4, you could specify left, right, and accept keys,
-        and not need a mouse::
-
-            ratingScale = visual.RatingScale(
-                win, low=1, high=5, markerStart=4,
-                leftKeys='1', rightKeys = '2', acceptKeys='4')
-
-    **Example 3**:
-
-        Categorical ratings can be obtained using choices::
-
-            ratingScale = visual.RatingScale(
-                win, choices=['agree', 'disagree'],
-                markerStart=0.5, singleClick=True)
-
-    For other examples see Coder Demos -> stimuli -> ratingScale.py.
-
-    :Authors:
-        - 2010 Jeremy Gray: original code and on-going updates
-        - 2012 Henrik Singmann: tickMarks, labels, ticksAboveLine
-        - 2014 Jeremy Gray: multiple API changes (v1.80.00)
-    """
-
-    def __init__(self,
-                 win,
-                 scale='<default>',
-                 choices=None,
-                 low=1,
-                 high=7,
-                 precision=1,
-                 labels=(),
-                 tickMarks=None,
-                 tickHeight=1.0,
-                 marker='triangle',
-                 markerStart=None,
-                 markerColor=None,
-                 markerExpansion=1,
-                 singleClick=False,
-                 disappear=False,
-                 textSize=1.0,
-                 textColor='LightGray',
-                 textFont='Helvetica Bold',
-                 showValue=True,
-                 showAccept=True,
-                 acceptKeys='return',
-                 acceptPreText='key, click',
-                 acceptText='accept?',
-                 acceptSize=1.0,
-                 leftKeys='left',
-                 rightKeys='right',
-                 respKeys=(),
-                 lineColor='White',
-                 colorSpace='rgb',
-                 skipKeys='tab',
-                 mouseOnly=False,
-                 noMouse=False,
-                 size=1.0,
-                 stretch=1.0,
-                 pos=None,
-                 minTime=0.4,
-                 maxTime=0.0,
-                 flipVert=False,
-                 depth=0,
-                 name=None,
-                 autoLog=True,
-                 **kwargs):  # catch obsolete args
-        """
-    :Parameters:
-
-        win :
-            A :class:`~psychopy.visual.Window` object (required).
-        choices :
-            A list of items which the subject can choose among.
-            ``choices`` takes precedence over ``low``, ``high``,
-            ``precision``, ``scale``, ``labels``, and ``tickMarks``.
-        low :
-            Lowest numeric rating (integer), default = 1.
-        high :
-            Highest numeric rating (integer), default = 7.
-        precision :
-            Portions of a tick to accept as input [1, 10, 60, 100];
-            default = 1 (a whole tick).
-            Pressing a key in `leftKeys` or `rightKeys` will move the
-            marker by one portion of a tick. precision=60 is intended to
-            support ratings of time-based quantities, with seconds being
-            fractional minutes (or minutes being fractional hours).
-            The display uses a colon (min:sec, or hours:min)
-            to signal this to participants. The value returned by getRating()
-            will be a proportion of a minute (e.g., 1:30 -> 1.5, or 59 seconds
-            -> 59/60 = 0.98333). hours:min:sec is not supported.
-        scale :
-            Optional reminder message about how to respond or rate an item,
-            displayed above the line; default =
-            '<low>=not at all, <high>=extremely'.
-            To suppress the scale, set ``scale=None``.
-        labels :
-            Text to be placed at specific tick marks to indicate their value.
-            Can be just the ends (if given 2 labels), ends + middle
-            (if given 3 labels),
-            or all points (if given the same number of labels as points).
-        tickMarks :
-            List of positions at which tick marks should be placed from low
-            to high.
-            The default is to space tick marks equally, one per integer value.
-        tickHeight :
-            The vertical height of tick marks: 1.0 is the default height
-            (above line), -1.0 is below the line, and 0.0 suppresses the
-            display of tickmarks. ``tickHeight`` is purely cosmetic, and can
-            be fractional, e.g., 1.2.
-        marker :
-            The moveable visual indicator of the current selection. The
-            predefined styles are 'triangle', 'circle', 'glow', 'slider',
-            and 'hover'. A slider moves smoothly when there are enough
-            screen positions to move through, e.g., low=0, high=100.
-            Hovering requires a set of choices, and allows clicking directly
-            on individual choices; dwell-time is not recorded.
-            Can also be set to a custom marker stimulus: any object with
-            a .draw() method and .pos will work, e.g.,
-            ``visual.TextStim(win, text='[]', units='norm')``.
-        markerStart :
-            The location or value to be pre-selected upon initial display,
-            either numeric or one of the choices. Can be fractional,
-            e.g., midway between two options.
-        markerColor :
-            Color to use for a predefined marker style, e.g., 'DarkRed'.
-        markerExpansion :
-            Only affects the `glow` marker: How much to expand or
-            contract when moving rightward; 0=none, negative shrinks.
-        singleClick :
-            Enable a mouse click to both select and accept the rating,
-            default = ``False``.
-            A legal key press will also count as a singleClick.
-            The 'accept' box is visible, but clicking it has no effect.
-        pos : tuple (x, y)
-            Position of the rating scale on the screen. The midpoint of
-            the line will be positioned at ``(x, y)``;
-            default = ``(0.0, -0.4)`` in norm units
-        size :
-            How much to expand or contract the overall rating scale display.
-            Default size = 1.0. For larger than the default, set
-            ``size`` > 1; for smaller, set < 1.
-        stretch:
-            Like ``size``, but only affects the horizontal direction.
-        textSize :
-            The size of text elements, relative to the default size
-            (i.e., a scaling factor, not points).
-        textColor :
-            Color to use for labels and scale text; default = 'LightGray'.
-        textFont :
-            Name of the font to use; default = 'Helvetica Bold'.
-        showValue :
-            Show the subject their current selection default = ``True``.
-            Ignored if singleClick is ``True``.
-        showAccept :
-            Show the button to click to accept the current value by using
-            the mouse; default = ``True``.
-        acceptPreText :
-            The text to display before any value has been selected.
-        acceptText :
-            The text to display in the 'accept' button after a value has
-            been selected.
-        acceptSize :
-            The width of the accept box relative to the default
-            (e.g., 2 is twice as wide).
-        acceptKeys :
-            A list of keys that are used to accept the current response;
-            default = 'return'.
-        leftKeys :
-            A list of keys that each mean "move leftwards";
-            default = 'left'.
-        rightKeys :
-            A list of keys that each mean "move rightwards";
-            default = 'right'.
-        respKeys :
-            A list of keys to use for selecting choices, in the desired order.
-            The first item will be the left-most choice, the second
-            item will be the next choice, and so on.
-        skipKeys :
-            List of keys the subject can use to skip a response,
-            default = 'tab'.
-            To require a response to every item, set ``skipKeys=None``.
-        lineColor :
-            The RGB color to use for the scale line, default = 'White'.
-        mouseOnly :
-            Require the subject to use the mouse (any keyboard input is
-            ignored), default = ``False``. Can be used to avoid competing
-            with other objects for keyboard input.
-        noMouse:
-            Require the subject to use keys to respond; disable and
-            hide the mouse.
-            `markerStart` will default to the left end.
-        minTime :
-            Seconds that must elapse before a response can be accepted,
-            default = `0.4`.
-        maxTime :
-            Seconds after which a response cannot be accepted.
-            If ``maxTime`` <= ``minTime``, there's no time limit.
-            Default = `0.0` (no time limit).
-        disappear :
-            Whether the rating scale should vanish after a value is accepted.
-            Can be useful when showing multiple scales.
-        flipVert :
-            Whether to mirror-reverse the rating scale in the vertical
-            direction.
-    """
-        # what local vars are defined (these are the init params) for use by
-        # __repr__
-        self._initParams = dir()
-        super(RatingScale, self).__init__(name=name, autoLog=False)
-
-        # warn about obsolete arguments; Jan 2014, for v1.80:
-        obsoleted = {'showScale', 'ticksAboveLine', 'displaySizeFactor',
-                     'markerStyle', 'customMarker', 'allowSkip',
-                     'stretchHoriz', 'escapeKeys', 'textSizeFactor',
-                     'showScale', 'showAnchors',
-                     'lowAnchorText', 'highAnchorText'}
-        obsArgs = set(kwargs.keys()).intersection(obsoleted)
-        if obsArgs:
-            msg = ('RatingScale obsolete args: %s; see changelog v1.80.00'
-                   ' for notes on how to migrate')
-            logging.error(msg % list(obsArgs))
-            core.quit()
-        # kwargs will absorb everything, including typos, so warn about bad
-        # args
-        unknownArgs = set(kwargs.keys()).difference(obsoleted)
-        if unknownArgs:
-            msg = "RatingScale unknown kwargs: %s"
-            logging.error(msg % list(unknownArgs))
-            core.quit()
-
-        self.autoLog = False  # needs to start off False
-        self.win = win
-        self.disappear = disappear
-
-        # internally work in norm units, restore to orig units at the end of
-        # __init__:
-        self.savedWinUnits = self.win.units
-        self.win.setUnits(u'norm', log=False)
-        self.depth = depth
-
-        # 'hover' style = like hyperlink with hover over choices:
-        if marker == 'hover':
-            showAccept = False
-            singleClick = True
-            textSize *= 1.5
-            mouseOnly = True
-            noMouse = False
-
-        self.colorSpace = colorSpace
-
-        # make things well-behaved if the requested value(s) would be trouble:
-        self._initFirst(showAccept, mouseOnly, noMouse, singleClick,
-                        acceptKeys, marker, markerStart, low, high, precision,
-                        choices, scale, tickMarks, labels, tickHeight)
-        self._initMisc(minTime, maxTime)
-
-        # Set scale & position, key-bindings:
-        self._initPosScale(pos, size, stretch)
-        self._initKeys(self.acceptKeys, skipKeys,
-                       leftKeys, rightKeys, respKeys)
-
-        # Construct the visual elements:
-        self._initLine(tickMarkValues=tickMarks,
-                       lineColor=lineColor, marker=marker)
-        self._initMarker(marker, markerColor, markerExpansion)
-        self._initTextElements(win, self.scale, textColor, textFont, textSize,
-                               showValue, tickMarks)
-        self._initAcceptBox(self.showAccept, acceptPreText, acceptText,
-                            acceptSize, self.markerColor, self.textSizeSmall,
-                            textSize, self.textFont)
-
-        # List-ify the visual elements; self.marker is handled separately
-        self.visualDisplayElements = []
-        if self.showScale:
-            self.visualDisplayElements += [self.scaleDescription]
-        if self.showAccept:
-            self.visualDisplayElements += [self.acceptBox, self.accept]
-        if self.labels:
-            for item in self.labels:
-                if not item.text == '':  # skip any empty placeholders
-                    self.visualDisplayElements.append(item)
-        if marker != 'hover':
-            self.visualDisplayElements += [self.line]
-
-        # Mirror (flip) vertically if requested
-        self.flipVert = False
-        self.setFlipVert(flipVert)
-
-        # Final touches:
-        self.origScaleDescription = self.scaleDescription.text
-        self.reset()  # sets .status, among other things
-        self.win.setUnits(self.savedWinUnits, log=False)
-
-        self.timedOut = False
-        self.beyondMinTime = False
-
-        # set autoLog (now that params have been initialised)
-        self.autoLog = autoLog
-        if autoLog:
-            logging.exp("Created %s = %s" % (self.name, repr(self)))
-
-    def __repr__(self, complete=False):
-        return self.__str__(complete=complete)  # from MinimalStim
-
-    def _initFirst(self, showAccept, mouseOnly, noMouse, singleClick,
-                   acceptKeys, marker, markerStart, low, high, precision,
-                   choices, scale, tickMarks, labels, tickHeight):
-        """some sanity checking; various things are set, especially those
-        that are used later; choices, anchors, markerStart settings are
-        handled here
-        """
-        self.showAccept = bool(showAccept)
-        self.mouseOnly = bool(mouseOnly)
-        self.noMouse = bool(noMouse) and not self.mouseOnly  # mouseOnly wins
-        self.singleClick = bool(singleClick)
-        self.acceptKeys = acceptKeys
-        self.precision = precision
-        self.labelTexts = None
-        self.tickHeight = tickHeight
-
-        if not self.showAccept:
-            # the accept button is the mouse-based way to accept the current
-            # response
-            if len(list(self.acceptKeys)) == 0:
-                # make sure there is in fact a way to respond using a
-                # key-press:
-                self.acceptKeys = ['return']
-            if self.mouseOnly and not self.singleClick:
-                # then there's no way to respond, so deny mouseOnly / enable
-                # using keys:
-                self.mouseOnly = False
-                msg = ("RatingScale %s: ignoring mouseOnly (because "
-                       "showAccept and singleClick are False)")
-                logging.warning(msg % self.name)
-
-        # 'choices' is a list of non-numeric (unordered) alternatives:
-        if choices and len(list(choices)) < 2:
-            msg = "RatingScale %s: choices requires 2 or more items"
-            logging.error(msg % self.name)
-        if choices and len(list(choices)) >= 2:
-            low = 0
-            high = len(list(choices)) - 1
-            self.precision = 1  # a fractional choice makes no sense
-            self.choices = choices
-            self.labelTexts = choices
-        else:
-            self.choices = False
-        if marker == 'hover' and not self.choices:
-            logging.error("RatingScale: marker='hover' requires "
-                          "a set of choices.")
-            core.quit()
-
-        # Anchors need to be well-behaved [do after choices]:
-        try:
-            self.low = int(low)
-        except Exception:
-            self.low = 1
-        try:
-            self.high = int(high)
-        except Exception:
-            self.high = self.low + 1
-        if self.high <= self.low:
-            self.high = self.low + 1
-            self.precision = 100
-
-        if not self.choices:
-            diff = self.high - self.low
-            if labels and len(labels) == 2:
-                # label the endpoints
-                first, last = labels[0], labels[-1]
-                self.labelTexts = [first] + [''] * (diff - 1) + [last]
-            elif labels and len(labels) == 3 and diff > 1 and (1 + diff) % 2:
-                # label endpoints and middle tick
-                placeHolder = [''] * ((diff - 2) // 2)
-                self.labelTexts = ([labels[0]] + placeHolder +
-                                   [labels[1]] + placeHolder +
-                                   [labels[2]])
-            elif labels in [None, False]:
-                self.labelTexts = []
-            else:
-                first, last = str(self.low), str(self.high)
-                self.labelTexts = [first] + [''] * (diff - 1) + [last]
-
-        self.scale = scale
-        if tickMarks and not labels is False:
-            if labels is None:
-                self.labelTexts = tickMarks
-            else:
-                self.labelTexts = labels
-            if len(self.labelTexts) != len(tickMarks):
-                msg = "RatingScale %s: len(labels) not equal to len(tickMarks)"
-                logging.warning(msg % self.name)
-                self.labelTexts = tickMarks
-            if self.scale == "<default>":
-                self.scale = False
-
-        # Marker pre-positioned? [do after anchors]
-        try:
-            self.markerStart = float(markerStart)
-        except Exception:
-            if (isinstance(markerStart, str) and
-                    type(self.choices) == list and
-                    markerStart in self.choices):
-                self.markerStart = self.choices.index(markerStart)
-                self.markerPlacedAt = self.markerStart
-                self.markerPlaced = True
-            else:
-                self.markerStart = None
-                self.markerPlaced = False
-        else:  # float(markerStart) succeeded
-            self.markerPlacedAt = self.markerStart
-            self.markerPlaced = True
-        # default markerStart = 0 if needed but otherwise unspecified:
-        if self.noMouse and self.markerStart is None:
-            self.markerPlacedAt = self.markerStart = 0
-            self.markerPlaced = True
-
-    def _initMisc(self, minTime, maxTime):
-        # precision is the fractional parts of a tick mark to be sensitive to,
-        # in [1,10,100]:
-        if type(self.precision) != int or self.precision < 10:
-            self.precision = 1
-            self.fmtStr = "%.0f"  # decimal places, purely for display
-        elif self.precision == 60:
-            self.fmtStr = "%d:%s"  # minutes:seconds.zfill(2)
-        elif self.precision < 100:
-            self.precision = 10
-            self.fmtStr = "%.1f"
-        else:
-            self.precision = 100
-            self.fmtStr = "%.2f"
-
-        self.clock = core.Clock()  # for decision time
-        try:
-            self.minTime = float(minTime)
-        except ValueError:
-            self.minTime = 1.0
-        self.minTime = max(self.minTime, 0.)
-        try:
-            self.maxTime = float(maxTime)
-        except ValueError:
-            self.maxTime = 0.0
-        self.allowTimeOut = bool(self.minTime < self.maxTime)
-
-        self.myMouse = event.Mouse(
-            win=self.win, visible=bool(not self.noMouse))
-        # Mouse-click-able 'accept' button pulsates (cycles its brightness
-        # over frames):
-        framesPerCycle = 100
-        self.pulseColor = [0.6 + 0.22 * numpy.cos(i/15.65)
-                           for i in range(framesPerCycle)]
-
-    def _initPosScale(self, pos, size, stretch, log=True):
-        """position (x,y) and size (magnification) of the rating scale
-        """
-        # Screen position (translation) of the rating scale as a whole:
-        if pos:
-            if len(list(pos)) == 2:
-                offsetHoriz, offsetVert = pos
-            elif log and self.autoLog:
-                msg = "RatingScale %s: pos expects a tuple (x,y)"
-                logging.warning(msg % self.name)
-        try:
-            self.offsetHoriz = float(offsetHoriz)
-        except Exception:
-            if self.savedWinUnits == 'pix':
-                self.offsetHoriz = 0
-            else:  # default x in norm units:
-                self.offsetHoriz = 0.0
-        try:
-            self.offsetVert = float(offsetVert)
-        except Exception:
-            if self.savedWinUnits == 'pix':
-                self.offsetVert = int(self.win.size[1]/-5.0)
-            else:  # default y in norm units:
-                self.offsetVert = -0.4
-        # pos=(x,y) will consider x,y to be in win units, but want norm
-        # internally
-        if self.savedWinUnits == 'pix':
-            self.offsetHoriz = float(self.offsetHoriz) / self.win.size[0] / 0.5
-            self.offsetVert = float(self.offsetVert) / self.win.size[1] / 0.5
-        # just expose; not used elsewhere yet
-        self.pos = [self.offsetHoriz, self.offsetVert]
-
-        # Scale size (magnification) of the rating scale as a whole:
-        try:
-            self.stretch = float(stretch)
-        except ValueError:
-            self.stretch = 1.
-        try:
-            self.size = float(size) * 0.6
-        except ValueError:
-            self.size = 0.6
-
-    def _initKeys(self, acceptKeys, skipKeys, leftKeys, rightKeys, respKeys):
-        # keys for accepting the currently selected response:
-        if self.mouseOnly:
-            self.acceptKeys = []  # no valid keys, so must use mouse
-        else:
-            if type(acceptKeys) not in [list, tuple, set]:
-                acceptKeys = [acceptKeys]
-            self.acceptKeys = acceptKeys
-        self.skipKeys = []
-        if skipKeys and not self.mouseOnly:
-            if type(skipKeys) not in [list, tuple, set]:
-                skipKeys = [skipKeys]
-            self.skipKeys = list(skipKeys)
-        if type(leftKeys) not in [list, tuple, set]:
-            leftKeys = [leftKeys]
-        self.leftKeys = leftKeys
-        if type(rightKeys) not in [list, tuple, set]:
-            rightKeys = [rightKeys]
-        self.rightKeys = rightKeys
-
-        # allow responding via arbitrary keys if given as a param:
-        nonRespKeys = (self.leftKeys + self.rightKeys + self.acceptKeys +
-                       self.skipKeys)
-        if respKeys and hasattr(respKeys, '__iter__'):
-            self.respKeys = respKeys
-            self.enableRespKeys = True
-            if set(self.respKeys).intersection(nonRespKeys):
-                msg = 'RatingScale %s: respKeys may conflict with other keys'
-                logging.warning(msg % self.name)
-        else:
-            # allow resp via numeric keys if the response range is in 0-9
-            self.respKeys = []
-            if not self.mouseOnly and self.low > -1 and self.high < 10:
-                self.respKeys = [str(i)
-                                 for i in range(self.low, self.high + 1)]
-            # but if any digit is used as an action key, that should
-            # take precedence so disable using numeric keys:
-            if set(self.respKeys).intersection(nonRespKeys) == set([]):
-                self.enableRespKeys = True
-            else:
-                self.enableRespKeys = False
-        if self.enableRespKeys:
-            self.tickFromKeyPress = {}
-            for i, key in enumerate(self.respKeys):
-                self.tickFromKeyPress[key] = i + self.low
-
-        # if self.noMouse:
-        #     could check that there are appropriate response keys
-
-        self.allKeys = nonRespKeys + self.respKeys
-
-    def _initLine(self, tickMarkValues=None, lineColor='White', marker=None):
-        """define a ShapeStim to be a graphical line, with tick marks.
-
-        ### Notes (JRG Aug 2010)
-        Conceptually, the response line is always -0.5 to +0.5
-        ("internal" units). This line, of unit length, is scaled and
-        translated for display. The line is effectively "center justified",
-        expanding both left and right with scaling, with pos[] specifying
-        the screen coordinate (in window units, norm or pix) of the
-        mid-point of the response line. Tick marks are in integer units,
-        internally 0 to (high-low), with 0 being the left end and (high-low)
-        being the right end. (Subjects see low to high on the screen.)
-        Non-numeric (categorical) choices are selected using tick-marks
-        interpreted as an index, choice[tick]. Tick units get mapped to
-        "internal" units based on their proportion of the total ticks
-        (--> 0. to 1.). The unit-length internal line is expanded or
-        contracted by stretch and size, and then is translated to
-        position pos (offsetHoriz=pos[0], offsetVert=pos[1]).
-        pos is the name of the arg, and its values appear in the code as
-        offsetHoriz and offsetVert only for historical reasons (could be
-        refactored for clarity).
-
-        Auto-rescaling reduces the number of tick marks shown on the
-        screen by a factor of 10, just for nicer appearance, without
-        affecting the internal representation.
-
-        Thus, the horizontal screen position of the i-th tick mark,
-        where i in [0,n], for n total ticks (n = high-low),
-        in screen units ('norm') will be:
-          tick-i             == offsetHoriz + (-0.5 + i/n ) * stretch * size
-        So two special cases are:
-          tick-0 (left end)  == offsetHoriz - 0.5 * stretch * size
-          tick-n (right end) == offsetHoriz + 0.5 * stretch * size
-        The vertical screen position is just offsetVert (in screen norm units).
-        To elaborate: tick-0 is the left-most tick, or "low anchor";
-        here 0 is internal, the subject sees <low>.
-        tick-n is the right-most tick, or "high anchor", or
-        internal-tick-(high-low), and the subject sees <high>.
-        Intermediate ticks, i, are located proportionally
-        between -0.5 to + 0.5, based on their proportion
-        of the total number of ticks, float(i)/n.
-        The "proportion of total" is used because it's a line of unit length,
-        i.e., the same length as used to internally represent the
-        scale (-0.5 to +0.5).
-        If precision > 1, the user / experimenter is asking for
-        fractional ticks. These map correctly
-        onto [0, 1] as well without requiring special handling
-        (just do ensure float() ).
-
-        Another note: -0.5 to +0.5 looked too big to be the default
-        size of the rating line in screen norm units,
-        so I set the internal size = 0.6 to compensate (i.e., making
-        everything smaller). The user can adjust the scaling around
-        the default by setting size, stretch, or both.
-        This means that the user / experimenter can just think of > 1
-        being expansion (and < 1 == contraction) relative to the default
-        (internal) scaling, and not worry about the internal scaling.
-
-        ### Notes (HS November 2012)
-        To allow for labels at the ticks, the positions of the tick marks
-        are saved in self.tickPositions. If tickMarks, those positions
-        are used instead of the automatic positions.
-        """
-
-        self.lineColor = lineColor
-        # vertical height of each tick, norm units; used for markers too:
-        self.baseSize = 0.04
-        # num tick marks to display, can get autorescaled
-        self.tickMarks = float(self.high - self.low)
-        self.autoRescaleFactor = 1
-
-        if tickMarkValues:
-            tickTmp = numpy.asarray(tickMarkValues, dtype=numpy.float32)
-            tickMarkPositions = (tickTmp - self.low)/self.tickMarks
-        else:
-            # visually remap 10 ticks onto 1 tick in some conditions (=
-            # cosmetic):
-            if (self.low == 0 and
-                    self.tickMarks > 20 and
-                    int(self.tickMarks) % 10 == 0):
-                self.autoRescaleFactor = 10
-                self.tickMarks /= self.autoRescaleFactor
-            tickMarkPositions = numpy.linspace(0, 1, int(self.tickMarks) + 1)
-        self.scaledPrecision = float(self.precision * self.autoRescaleFactor)
-
-        # how far a left or right key will move the marker, in tick units:
-        self.keyIncrement = 1. / self.autoRescaleFactor / self.precision
-        self.hStretchTotal = self.stretch * self.size
-
-        # ends of the rating line, in norm units:
-        self.lineLeftEnd = self.offsetHoriz - 0.5 * self.hStretchTotal
-        self.lineRightEnd = self.offsetHoriz + 0.5 * self.hStretchTotal
-
-        # space around the line within which to accept mouse input:
-        # not needed if self.noMouse, but not a problem either
-        pad = 0.06 * self.size
-        if marker == 'hover':
-            padText = ((1.0/(3 * (self.high - self.low))) *
-                       (self.lineRightEnd - self.lineLeftEnd))
-        else:
-            padText = 0
-        self.nearLine = [
-            [self.lineLeftEnd - pad - padText, -2 * pad + self.offsetVert],
-            [self.lineLeftEnd - pad - padText, 2 * pad + self.offsetVert],
-            [self.lineRightEnd + pad + padText, 2 * pad + self.offsetVert],
-            [self.lineRightEnd + pad + padText, -2 * pad + self.offsetVert]]
-
-        # vertices for ShapeStim:
-        self.tickPositions = []  # list to hold horizontal positions
-        vertices = [[self.lineLeftEnd, self.offsetVert]]  # first vertex
-        # vertical height of ticks (purely cosmetic):
-        if self.tickHeight is False:
-            self.tickHeight = -1.  # backwards compatibility for boolean
-        # numeric -> scale tick height;  float(True) == 1.
-        tickSize = self.baseSize * self.size * float(self.tickHeight)
-        lineLength = self.lineRightEnd - self.lineLeftEnd
-        for count, tick in enumerate(tickMarkPositions):
-            horizTmp = self.lineLeftEnd + lineLength * tick
-            vertices += [[horizTmp, self.offsetVert + tickSize],
-                         [horizTmp, self.offsetVert]]
-            if count < len(tickMarkPositions) - 1:
-                tickRelPos = lineLength * tickMarkPositions[count + 1]
-                nextHorizTmp = self.lineLeftEnd + tickRelPos
-                vertices.append([nextHorizTmp, self.offsetVert])
-            self.tickPositions.append(horizTmp)
-        vertices += [[self.lineRightEnd, self.offsetVert],
-                     [self.lineLeftEnd, self.offsetVert]]
-
-        # create the line:
-        self.line = ShapeStim(win=self.win, units='norm', vertices=vertices,
-                              lineWidth=4, lineColor=self.lineColor,
-                              name=self.name + '.line', autoLog=False)
-
-    def _initMarker(self, marker, markerColor, expansion):
-        """define a visual Stim to be used as the indicator.
-
-        marker can be either a string, or a visual object (custom marker).
-        """
-        # preparatory stuff:
-        self.markerOffsetVert = 0.
-        if isinstance(marker, str):
-            self.markerStyle = marker
-        elif not hasattr(marker, 'draw'):
-            logging.error("RatingScale: custom marker has no draw() method")
-            self.markerStyle = 'triangle'
-        else:
-            self.markerStyle = 'custom'
-            if hasattr(marker, 'pos'):
-                self.markerOffsetVert = marker.pos[1]
-            else:
-                logging.error(
-                    "RatingScale: custom marker has no pos attribute")
-
-        self.markerSize = 8. * self.size
-        if isinstance(markerColor, str):
-            markerColor = markerColor.replace(' ', '')
-
-        # define or create self.marker:
-        if self.markerStyle == 'hover':
-            self.marker = TextStim(win=self.win, text=' ', units='norm',
-                                   autoLog=False)  # placeholder
-            self.markerOffsetVert = .02
-            if not markerColor:
-                markerColor = 'darkorange'
-        elif self.markerStyle == 'triangle':
-            scaledTickSize = self.baseSize * self.size
-            vert = [[-1 * scaledTickSize * 1.8, scaledTickSize * 3],
-                    [scaledTickSize * 1.8, scaledTickSize * 3], [0, -0.005]]
-            if markerColor is None:
-                markerColor = 'DarkBlue'
-            self.marker = ShapeStim(win=self.win, units='norm', vertices=vert,
-                                    lineWidth=0.1, lineColor=markerColor,
-                                    fillColor=markerColor,
-                                    name=self.name + '.markerTri',
-                                    autoLog=False)
-        elif self.markerStyle == 'slider':
-            scaledTickSize = self.baseSize * self.size
-            vert = [[-1 * scaledTickSize * 1.8, scaledTickSize],
-                    [scaledTickSize * 1.8, scaledTickSize],
-                    [scaledTickSize * 1.8, -1 * scaledTickSize],
-                    [-1 * scaledTickSize * 1.8, -1 * scaledTickSize]]
-            if markerColor is None:
-                markerColor = 'black'
-            self.marker = ShapeStim(win=self.win, units='norm', vertices=vert,
-                                    lineWidth=0.1, lineColor=markerColor,
-                                    fillColor=markerColor,
-                                    name=self.name + '.markerSlider',
-                                    opacity=0.7, autoLog=False)
-        elif self.markerStyle == 'glow':
-            if markerColor is None:
-                markerColor = 'White'
-            self.marker = PatchStim(win=self.win, units='norm',
-                                    tex=None, mask='gauss',
-                                    color=markerColor, opacity=0.85,
-                                    autoLog=False,
-                                    name=self.name + '.markerGlow')
-            self.markerBaseSize = self.baseSize * self.markerSize
-            self.markerOffsetVert = .02
-            self.markerExpansion = float(expansion) * 0.6
-            if self.markerExpansion == 0:
-                self.markerBaseSize *= self.markerSize * 0.7
-                if self.markerSize > 1.2:
-                    self.markerBaseSize *= .7
-                self.marker.setSize(self.markerBaseSize/2.0, log=False)
-        elif self.markerStyle == 'custom':
-            if markerColor is None:
-                if hasattr(marker, 'color'):
-                    try:
-                        # marker.color 0 causes problems elsewhere too
-                        if not marker.color:
-                            marker.color = 'DarkBlue'
-                    except ValueError:  # testing truth value of list
-                        marker.color = 'DarkBlue'
-                elif hasattr(marker, 'fillColor'):
-                    marker.color = marker.fillColor
-                else:
-                    marker.color = 'DarkBlue'
-                markerColor = marker.color
-            if not hasattr(marker, 'name') or not marker.name:
-                marker.name = 'customMarker'
-            self.marker = marker
-        else:  # 'circle':
-            if markerColor is None:
-                markerColor = 'DarkRed'
-            x, y = self.win.size
-            windowRatio = y/x
-            self.markerSizeVert = 3.2 * self.baseSize * self.size
-            circleSize = [self.markerSizeVert *
-                          windowRatio, self.markerSizeVert]
-            self.markerOffsetVert = self.markerSizeVert/2.0
-            self.marker = Circle(self.win, size=circleSize, units='norm',
-                                 lineColor=markerColor, fillColor=markerColor,
-                                 name=self.name + '.markerCir', autoLog=False)
-            self.markerBaseSize = self.baseSize
-        self.markerColor = markerColor
-        self.markerYpos = self.offsetVert + self.markerOffsetVert
-        # save initial state, restore on reset
-        self.markerColorOriginal = markerColor
-
-    def _initTextElements(self, win, scale, textColor,
-                          textFont, textSize, showValue, tickMarks):
-        """creates TextStim for self.scaleDescription and self.labels
-        """
-        # text appearance (size, color, font, visibility):
-        self.showValue = bool(showValue)  # hide if False
-        self.textColor = textColor  # rgb
-        self.textFont = textFont
-        self.textSize = 0.2 * textSize * self.size
-        self.textSizeSmall = self.textSize * 0.6
-
-        # set the description text if not already set by user:
-        if scale == '<default>':
-            if self.choices:
-                scale = ''
-            else:
-                msg = u' = not at all . . . extremely = '
-                scale = str(self.low) + msg + str(self.high)
-
-        # create the TextStim:
-        self.scaleDescription = TextStim(
-            win=self.win, height=self.textSizeSmall,
-            pos=[self.offsetHoriz, 0.22 * self.size + self.offsetVert],
-            color=self.textColor, wrapWidth=2 * self.hStretchTotal,
-            font=textFont, autoLog=False)
-        self.scaleDescription.font = textFont
-        self.labels = []
-        if self.labelTexts:
-            if self.markerStyle == 'hover':
-                vertPosTmp = self.offsetVert  # on the line = clickable labels
-            else:
-                vertPosTmp = -2 * self.textSizeSmall * self.size + self.offsetVert
-            for i, label in enumerate(self.labelTexts):
-                # need all labels for tick position, i
-                if label or label is not None: # 'is not None' allows creation of '0' (zero or false) labels
-                    txtStim = TextStim(
-                        win=self.win, text=str(label), font=textFont,
-                        pos=[self.tickPositions[i // self.autoRescaleFactor],
-                             vertPosTmp],
-                        height=self.textSizeSmall, color=self.textColor,
-                        autoLog=False)
-                    self.labels.append(txtStim)
-        self.origScaleDescription = scale
-        self.setDescription(scale)  # do last
-
-    def _setMarkerColor(self, color):
-        """Set the fill color or color of the marker"""
-        try:
-            self.marker.setFillColor(color, colorSpace=self.colorSpace, log=False)
-        except AttributeError:
-            try:
-                self.marker.setColor(color, colorSpace=self.colorSpace, log=False)
-            except Exception:
-                pass
-
-    def setDescription(self, scale=None, log=True):
-        """Method to set the brief description (scale).
-
-        Useful when using the same RatingScale object to rate several
-        dimensions. `setDescription(None)` will reset the description
-        to its initial state. Set to a space character (' ') to make
-        the description invisible.
-        """
-        if scale is None:
-            scale = self.origScaleDescription
-        self.scaleDescription.setText(scale)
-        self.showScale = bool(scale)  # not in [None, False, '']
-        if log and self.autoLog:
-            logging.exp('RatingScale %s: setDescription="%s"' %
-                        (self.name, self.scaleDescription.text))
-
-    def _initAcceptBox(self, showAccept, acceptPreText, acceptText,
-                       acceptSize, markerColor,
-                       textSizeSmall, textSize, textFont):
-        """creates a ShapeStim for self.acceptBox (mouse-click-able
-        'accept'  button) and a TextStim for self.accept (container for
-        the text shown inside the box)
-        """
-        if not showAccept:  # no point creating things that won't be used
-            return
-
-        self.acceptLineColor = [-.2, -.2, -.2]
-        self.acceptFillColor = [.2, .2, .2]
-
-        if self.labelTexts:
-            boxVert = [0.3, 0.47]
-        else:
-            boxVert = [0.2, 0.37]
-
-        # define self.acceptBox:
-        sizeFactor = self.size * textSize
-        leftRightAdjust = 0.04 + 0.2 * max(0.1, acceptSize) * sizeFactor
-        acceptBoxtop = self.offsetVert - boxVert[0] * sizeFactor
-        self.acceptBoxtop = acceptBoxtop
-        acceptBoxbot = self.offsetVert - boxVert[1] * sizeFactor
-        self.acceptBoxbot = acceptBoxbot
-        acceptBoxleft = self.offsetHoriz - leftRightAdjust
-        self.acceptBoxleft = acceptBoxleft
-        acceptBoxright = self.offsetHoriz + leftRightAdjust
-        self.acceptBoxright = acceptBoxright
-
-        # define a rectangle with rounded corners; for square corners, set
-        # delta2 to 0
-        delta = 0.025 * self.size
-        delta2 = delta/7
-        acceptBoxVertices = [
-            [acceptBoxleft, acceptBoxtop - delta],
-            [acceptBoxleft + delta2, acceptBoxtop - 3 * delta2],
-            [acceptBoxleft + 3 * delta2, acceptBoxtop - delta2],
-            [acceptBoxleft + delta, acceptBoxtop],
-            [acceptBoxright - delta, acceptBoxtop],
-            [acceptBoxright - 3 * delta2, acceptBoxtop - delta2],
-            [acceptBoxright - delta2, acceptBoxtop - 3 * delta2],
-            [acceptBoxright, acceptBoxtop - delta],
-            [acceptBoxright, acceptBoxbot + delta],
-            [acceptBoxright - delta2, acceptBoxbot + 3 * delta2],
-            [acceptBoxright - 3 * delta2, acceptBoxbot + delta2],
-            [acceptBoxright - delta, acceptBoxbot],
-            [acceptBoxleft + delta, acceptBoxbot],
-            [acceptBoxleft + 3 * delta2, acceptBoxbot + delta2],
-            [acceptBoxleft + delta2, acceptBoxbot + 3 * delta2],
-            [acceptBoxleft, acceptBoxbot + delta]]
-        # interpolation looks bad on linux, as of Aug 2010
-        interpolate = bool(not sys.platform.startswith('linux'))
-        self.acceptBox = ShapeStim(
-            win=self.win, vertices=acceptBoxVertices,
-            fillColor=self.acceptFillColor, lineColor=self.acceptLineColor,
-            interpolate=interpolate, autoLog=False)
-
-        # text to display inside accept button before a marker is placed:
-        if self.low > 0 and self.high < 10 and not self.mouseOnly:
-            self.keyClick = 'key, click'
-        else:
-            self.keyClick = 'click line'
-        if acceptPreText != 'key, click':  # non-default
-            self.keyClick = str(acceptPreText)
-        self.acceptText = str(acceptText)
-
-        # create the TextStim:
-        self.accept = TextStim(
-            win=self.win, text=self.keyClick, font=self.textFont,
-            pos=[self.offsetHoriz, (acceptBoxtop + acceptBoxbot)/2.0],
-            italic=True, height=textSizeSmall, color=self.textColor,
-            autoLog=False)
-        self.accept.font = textFont
-
-        self.acceptTextColor = markerColor
-        if isinstance(markerColor, str):
-            # warning raised if color not specified as a string
-            if markerColor in ['White']:
-                self.acceptTextColor = 'Black'
-
-    def _getMarkerFromPos(self, mouseX):
-        """Convert mouseX into units of tick marks, 0 .. high-low.
-
-        Will be fractional if precision > 1
-        """
-        value = min(max(mouseX, self.lineLeftEnd), self.lineRightEnd)
-        # map mouseX==0 -> mid-point of tick scale:
-        _tickStretch = self.tickMarks/self.hStretchTotal
-        adjValue = value - self.offsetHoriz
-        markerPos = adjValue * _tickStretch + self.tickMarks/2.0
-        # We need float value in getRating(), but round() returns
-        # numpy.float64 if argument is numpy.float64 in Python3.
-        # So we have to convert return value of round() to float.
-        rounded = float(round(markerPos * self.scaledPrecision))
-        return rounded/self.scaledPrecision
-
-    def _getMarkerFromTick(self, tick):
-        """Convert a requested tick value into a position on internal scale.
-
-        Accounts for non-zero low end, autoRescale, and precision.
-        """
-        # ensure its on the line:
-        value = max(min(self.high, tick), self.low)
-        # set requested precision:
-        value = round(value * self.scaledPrecision)//self.scaledPrecision
-        return (value - self.low) * self.autoRescaleFactor
-
-    def setMarkerPos(self, tick):
-        """Method to allow the experimenter to set the marker's position
-        on the scale (in units of tick marks). This method can also set
-        the index within a list of choices (which start at 0).
-        No range checking is done.
-
-        Assuming you have defined rs = RatingScale(...), you can specify
-        a tick position directly::
-
-            rs.setMarkerPos(2)
-
-        or do range checking, precision management, and auto-rescaling::
-
-            rs.setMarkerPos(rs._getMarkerFromTick(2))
-
-        To work from a screen coordinate, such as the X position of a
-        mouse click::
-
-            rs.setMarkerPos(rs._getMarkerFromPos(mouseX))
-
-        """
-        self.markerPlacedAt = tick
-        self.markerPlaced = True  # only needed first time
-
-    def setFlipVert(self, newVal=True, log=True):
-        """Sets current vertical mirroring to ``newVal``.
-        """
-        if self.flipVert != newVal:
-            self.flipVert = not self.flipVert
-            self.markerYpos *= -1
-            groupFlipVert([self.nearLine, self.marker] +
-                          self.visualDisplayElements)
-        logAttrib(self, log, 'flipVert')
-
-    # autoDraw and setAutoDraw are inherited from basevisual.MinimalStim
-
-    def acceptResponse(self, triggeringAction, log=True):
-        """Commit and optionally log a response and the action.
-        """
-        self.noResponse = False
-        self.history.append((self.getRating(), self.getRT()))
-        if log and self.autoLog:
-            vals = (self.name, triggeringAction, str(self.getRating()))
-            logging.data('RatingScale %s: (%s) rating=%s' % vals)
-
-    def setYPos(self, newPos = None):
-        """
-        This function can be called by the user to change the Y-positioning of the rating scale.
-        X location remains unchanged.
-        """
-        oldXPos, oldYPos = self.offsetHoriz, self.offsetVert
-        if not newPos is None:
-            if len(list(newPos)) == 2:
-                offsetHoriz, offsetVert = newPos
-        self.offsetHoriz = float(offsetHoriz)
-        self.offsetVert = float(offsetVert)
-        for positions in self.visualDisplayElements: # change location of elements based on position arg
-            if not positions.pos is None:
-                if 'ShapeStim' in str(type(positions)):
-                    offsetY = abs(oldYPos - positions.pos[1])
-                    positions.setPos([positions.pos[0], self.offsetVert + offsetY])
-                    if '.line' in positions.name:# then change Y location of marker and mouse click box
-                        self.markerYpos = self.offsetVert
-                        self.nearLine[0][1],self.nearLine[3][1] = offsetVert-.072, offsetVert-.072
-                        self.nearLine[1][1], self.nearLine[2][1] = offsetVert +.072, offsetVert + .072
-                if 'TextStim' in str(type(positions)):
-                    offsetY = abs(oldYPos-positions.pos[1])
-                    positions.setPos([positions.pos[0], self.offsetVert - offsetY])
-
-
-    def draw(self, log=True):
-        """Update the visual display, check for response (key, mouse, skip).
-
-        Sets response flags: `self.noResponse`, `self.timedOut`.
-        `draw()` only draws the rating scale, not the item to be rated.
-        """
-        self.win.setUnits(u'norm', log=False)  # get restored
-        if self.firstDraw:
-            self.firstDraw = False
-            self.clock.reset()
-            self.status = STARTED
-            if self.markerStart:
-                # has been converted in index if given as str
-                if (self.markerStart % 1 or self.markerStart < 0 or
-                        self.markerStart > self.high or
-                        self.choices is False):
-                    first = self.markerStart
-                else:
-                    # back to str for history
-                    first = self.choices[int(self.markerStart)]
-            else:
-                first = None
-            self.history = [(first, 0.0)]  # this will grow
-            self.beyondMinTime = False  # has minTime elapsed?
-            self.timedOut = False
-
-        if not self.beyondMinTime:
-            self.beyondMinTime = bool(self.clock.getTime() > self.minTime)
-        # beyond maxTime = timed out? max < min means never allow time-out
-        if (self.allowTimeOut and
-                not self.timedOut and
-                self.maxTime < self.clock.getTime()):
-            # only do this stuff once
-            self.timedOut = True
-            self.acceptResponse('timed out: %.3fs' % self.maxTime, log=log)
-
-        # 'disappear' == draw nothing if subj is done:
-        if self.noResponse == False and self.disappear:
-            self.win.setUnits(self.savedWinUnits, log=False)
-            return
-
-        # draw everything except the marker:
-        for visualElement in self.visualDisplayElements:
-            visualElement.draw()
-
-        # draw a fixed marker if the scale is being drawn after a response:
-        if self.noResponse == False:
-            # fix the marker position on the line
-            if not self.markerPosFixed:
-                self._setMarkerColor('DarkGray')
-
-                # drop it onto the line
-                self.marker.setPos((0, -.012), ('+', '-')[self.flipVert],
-                                   log=False)
-                self.markerPosFixed = True  # flag to park it there
-            self.marker.draw()
-            if self.showAccept:
-                self.acceptBox.draw()  # hides the text
-            self.win.setUnits(self.savedWinUnits, log=False)
-            return  # makes the marker unresponsive
-
-        if self.noMouse:
-            mouseNearLine = False
-        else:
-            mouseX, mouseY = self.myMouse.getPos()  # norm units
-            mouseNearLine = pointInPolygon(mouseX, mouseY, self.nearLine)
-
-        # draw a dynamic marker:
-        if self.markerPlaced or self.singleClick:
-            # update position:
-            if self.singleClick and mouseNearLine:
-                self.setMarkerPos(self._getMarkerFromPos(mouseX))
-            proportion = self.markerPlacedAt/self.tickMarks
-            # expansion for 'glow', based on proportion of total line
-            if self.markerStyle == 'glow' and self.markerExpansion != 0:
-                if self.markerExpansion > 0:
-                    newSize = 0.1 * self.markerExpansion * proportion
-                    newOpacity = 0.2 + proportion
-                else:  # self.markerExpansion < 0:
-                    newSize = - 0.1 * self.markerExpansion * (1 - proportion)
-                    newOpacity = 1.2 - proportion
-                self.marker.setSize(self.markerBaseSize + newSize, log=False)
-                self.marker.setOpacity(min(1, max(0, newOpacity)), log=False)
-            # set the marker's screen position based on tick (==
-            # markerPlacedAt)
-            if self.markerPlacedAt is not False:
-                x = self.offsetHoriz + self.hStretchTotal * (-0.5 + proportion)
-                self.marker.setPos((x, self.markerYpos), log=False)
-                self.marker.draw()
-            if self.showAccept and self.markerPlacedBySubject:
-                self.frame = (self.frame + 1) % 100
-                self.acceptBox.setFillColor(
-                    self.pulseColor[self.frame], colorSpace=self.colorSpace, log=False)
-                self.acceptBox.setLineColor(
-                    self.pulseColor[self.frame], colorSpace=self.colorSpace, log=False)
-                self.accept.setColor(self.acceptTextColor, colorSpace=self.colorSpace, log=False)
-                if self.showValue and self.markerPlacedAt is not False:
-                    if self.choices:
-                        val = str(self.choices[int(self.markerPlacedAt)])
-                    elif self.precision == 60:
-                        valTmp = self.markerPlacedAt + self.low
-                        minutes = int(valTmp)  # also works for hours:minutes
-                        seconds = int(60. * (valTmp - minutes))
-                        val = self.fmtStr % (minutes, str(seconds).zfill(2))
-                    else:
-                        valTmp = self.markerPlacedAt + self.low
-                        val = self.fmtStr % (valTmp * self.autoRescaleFactor)
-                    self.accept.setText(val)
-                elif self.markerPlacedAt is not False:
-                    self.accept.setText(self.acceptText)
-
-        # handle key responses:
-        if not self.mouseOnly:
-            for key in event.getKeys(self.allKeys):
-                if key in self.skipKeys:
-                    self.markerPlacedAt = None
-                    self.noResponse = False
-                    self.history.append((None, self.getRT()))
-                elif key in self.respKeys and self.enableRespKeys:
-                    # place the marker at the corresponding tick (from key)
-                    self.markerPlaced = True
-                    self.markerPlacedBySubject = True
-                    resp = self.tickFromKeyPress[key]
-                    self.markerPlacedAt = self._getMarkerFromTick(resp)
-                    proportion = self.markerPlacedAt/self.tickMarks
-                    self.marker.setPos(
-                        [self.size * (-0.5 + proportion), 0], log=False)
-                if self.markerPlaced and self.beyondMinTime:
-                    # placed by experimenter (as markerStart) or by subject
-                    if (self.markerPlacedBySubject or
-                            self.markerStart is None or
-                            not self.markerStart % self.keyIncrement):
-                        # inefficient to do every frame...
-                        leftIncr = rightIncr = self.keyIncrement
-                    else:
-                        # markerStart is fractional; arrow keys move to next
-                        # location
-                        leftIncr = self.markerStart % self.keyIncrement
-                        rightIncr = self.keyIncrement - leftIncr
-                    if key in self.leftKeys:
-                        self.markerPlacedAt = self.markerPlacedAt - leftIncr
-                        self.markerPlacedBySubject = True
-                    elif key in self.rightKeys:
-                        self.markerPlacedAt = self.markerPlacedAt + rightIncr
-                        self.markerPlacedBySubject = True
-                    elif key in self.acceptKeys:
-                        self.acceptResponse('key response', log=log)
-                    # off the end?
-                    self.markerPlacedAt = max(0, self.markerPlacedAt)
-                    self.markerPlacedAt = min(
-                        self.tickMarks, self.markerPlacedAt)
-
-                if (self.markerPlacedBySubject and self.singleClick
-                        and self.beyondMinTime):
-                    self.marker.setPos((0, self.offsetVert), '+', log=False)
-                    self.acceptResponse('key single-click', log=log)
-
-        # handle mouse left-click:
-        if not self.noMouse and self.myMouse.getPressed()[0]:
-            # mouseX, mouseY = self.myMouse.getPos() # done above
-            # if click near the line, place the marker there:
-            if mouseNearLine:
-                self.markerPlaced = True
-                self.markerPlacedBySubject = True
-                self.markerPlacedAt = self._getMarkerFromPos(mouseX)
-                if self.singleClick and self.beyondMinTime:
-                    self.acceptResponse('mouse single-click', log=log)
-            # if click in accept box and conditions are met, accept the
-            # response:
-            elif (self.showAccept and
-                    self.markerPlaced and
-                    self.beyondMinTime and
-                    self.acceptBox.contains(mouseX, mouseY)):
-                self.acceptResponse('mouse response', log=log)
-
-        if self.markerStyle == 'hover' and self.markerPlaced:
-            # 'hover' --> noMouse = False during init
-            if (mouseNearLine or
-                    self.markerPlacedAt != self.markerPlacedAtLast):
-                if hasattr(self, 'targetWord'):
-                    self.targetWord.setColor(self.textColor, colorSpace=self.colorSpace, log=False)
-                    # self.targetWord.setHeight(self.textSizeSmall, log=False)
-                    # # avoid TextStim memory leak
-                self.targetWord = self.labels[int(self.markerPlacedAt)]
-                self.targetWord.setColor(self.markerColor, colorSpace=self.colorSpace, log=False)
-                # skip size change to reduce mem leakage from pyglet text
-                # self.targetWord.setHeight(1.05*self.textSizeSmall,log=False)
-                self.markerPlacedAtLast = self.markerPlacedAt
-            elif not mouseNearLine and self.wasNearLine:
-                self.targetWord.setColor(self.textColor, colorSpace=self.colorSpace, log=False)
-                # self.targetWord.setHeight(self.textSizeSmall, log=False)
-            self.wasNearLine = mouseNearLine
-
-        # decision time = sec from first .draw() to when first 'accept' value:
-        if not self.noResponse and self.decisionTime == 0:
-            self.decisionTime = self.clock.getTime()
-            if log and self.autoLog:
-                logging.data('RatingScale %s: rating RT=%.3f' %
-                             (self.name, self.decisionTime))
-                logging.data('RatingScale %s: history=%s' %
-                             (self.name, self.getHistory()))
-            # minimum time is enforced during key and mouse handling
-            self.status = FINISHED
-            if self.showAccept:
-                self.acceptBox.setFillColor(self.acceptFillColor, colorSpace=self.colorSpace, log=False)
-                self.acceptBox.setLineColor(self.acceptLineColor, colorSpace=self.colorSpace, log=False)
-        else:
-            # build up response history if no decision or skip yet:
-            tmpRating = self.getRating()
-            if (self.history[-1][0] != tmpRating and
-                    self.markerPlacedBySubject):
-                self.history.append((tmpRating, self.getRT()))  # tuple
-
-        # restore user's units:
-        self.win.setUnits(self.savedWinUnits, log=False)
-
-    def reset(self, log=True):
-        """Restores the rating-scale to its post-creation state.
-
-        The history is cleared, and the status is set to NOT_STARTED. Does
-        not restore the scale text description (such reset is needed between
-        items when rating multiple items)
-        """
-        # only resets things that are likely to have changed when the
-        # ratingScale instance is used by a subject
-        # reset label color if using hover
-        if self.markerStyle == 'hover':
-            for labels in self.labels:
-                labels.setColor(self.textColor, colorSpace=self.colorSpace, log=False)
-        self.noResponse = True
-        # restore in case it turned gray, etc
-        self.markerColor = self.markerColorOriginal
-        self._setMarkerColor(self.markerColor)
-        # placed by subject or markerStart: show on screen
-        self.markerPlaced = False
-        # placed by subject is actionable: show value, singleClick
-        self.markerPlacedBySubject = False
-        self.markerPlacedAt = False
-        # NB markerStart could be 0; during __init__, its forced to be numeric
-        # and valid, or None (not boolean)
-        if self.markerStart != None:
-            self.markerPlaced = True
-            # __init__ assures this is valid:
-            self.markerPlacedAt = self.markerStart - self.low
-        self.markerPlacedAtLast = -1  # unplaced
-        self.wasNearLine = False
-        self.firstDraw = True  # -> self.clock.reset() at start of draw()
-        self.decisionTime = 0
-        self.markerPosFixed = False
-        self.frame = 0  # a counter used only to 'pulse' the 'accept' box
-
-        if self.showAccept:
-            self.acceptBox.setFillColor(self.acceptFillColor, colorSpace=self.colorSpace, log=False)
-            self.acceptBox.setLineColor(self.acceptLineColor, colorSpace=self.colorSpace, log=False)
-            self.accept.setColor('#444444', colorSpace='hex', log=False)  # greyed out
-            self.accept.setText(self.keyClick, log=False)
-        if log and self.autoLog:
-            logging.exp('RatingScale %s: reset()' % self.name)
-        self.status = NOT_STARTED
-        self.history = None
-
-    def getRating(self):
-        """Returns the final, accepted rating, or the current value.
-
-        The rating is None if the subject skipped this item, took longer
-        than ``maxTime``, or no rating is
-        available yet. Returns the currently indicated rating even if it has
-        not been accepted yet (and so might change until accept is pressed).
-        The first rating in the list will have the value of
-        markerStart (whether None, a numeric value, or a choice value).
-        """
-        if self.noResponse and self.status == FINISHED:
-            return None
-        if not type(self.markerPlacedAt) in [float, int]:
-            return None  # eg, if skipped a response
-
-        # set type for the response, based on what was wanted
-        val = self.markerPlacedAt * self.autoRescaleFactor
-        if self.precision == 1:
-            response = int(val) + self.low
-        else:
-            response = float(val) + self.low
-        if self.choices:
-            try:
-                response = self.choices[response]
-            except Exception:
-                pass
-                # == we have a numeric fractional choice from markerStart and
-                # want to save the numeric value as first item in the history
-        return response
-
-    def getRT(self):
-        """Returns the seconds taken to make the rating (or to indicate skip).
-
-        Returns None if no rating available, or maxTime if the response
-        timed out. Returns the time elapsed so far if no rating has been
-        accepted yet (e.g., for continuous usage).
-        """
-        if self.status != FINISHED:
-            return round(self.clock.getTime(), 3)
-        if self.noResponse:
-            if self.timedOut:
-                return round(self.maxTime, 3)
-            return None
-        return round(self.decisionTime, 3)
-
-    def getHistory(self):
-        """Return a list of the subject's history as (rating, time) tuples.
-
-        The history can be retrieved at any time, allowing for continuous
-        ratings to be obtained in real-time. Both numerical and categorical
-        choices are stored automatically in the history.
-        """
-        return self.history
+from psychopy.tools.pkgtools import PluginStub
+
+class RatingScale(
+    PluginStub,
+    plugin="psychopy-legacy",
+    doclink="https://psychopy.github.io/psychopy-legacy/coder/visual/RatingScale"
+):
+    pass