psychopy.visual.RatingScale

Class RatingScale

A class for getting numeric subjective ratings, e.g., on a 1-to-7 scale. Returns a re-usable rating-scale object having a .draw() method, with a customizable visual appearance. The .draw() method displays the rating scale only (not the item to be rated), handles the subject's response, and updates the display. When the subject responds, .noResponse goes False (i.e., there is a response). You can then call .getRating() to obtain the rating, .getRT() to get the decision time, or .reset() to restore the scale (for re-use). The experimenter has to handle the item to be rated, i.e., draw() it in the same window each frame. A RatingScale instance has no idea what else is on the screen. The subject can use the arrow keys (left, right) to move the marker in small increments (e.g., 1/100th of a tick-mark if precision = 100). Auto-rescaling happens if the low-anchor is 0 and high-anchor is a multiple of 10, just to reduce visual clutter. **Example 1.**:: myItem = <create your text, image, movie, ...> myRatingScale = visual.RatingScale(myWin) while myRatingScale.noResponse: myItem.draw() myRatingScale.draw() myWin.flip() rating = myRatingScale.getRating() decisionTime = myRatingScale.getRT() **Example 2.**:: The default settings should be good much of the time, but considerable customization is possible using the options. E.g., for fMRI, if your in-scanner response box sends keys 1-5, you could use custom left, right, and accept keys to allow key-1 = move left, key-2 = move right, and key-4 = accept the current rating: myRatingScale = visual.RatingScale(myWin, markerStart=4, leftKeys='1', rightKeys = '2', acceptKeys='4') See 'ratingScale.py' for a demo. :Author: - 2010 Jeremy Gray

Instance Methods

__init__(self, win, scale=None, low=1, high=7, precision=1, showValue=True, showScale=True, showAnchors=True, showAccept=True, acceptKeys=['return'], acceptPreText='key, click', acceptText='accept?', leftKeys=['left'], rightKeys=['right'], markerStyle='triangle', markerColor=None, markerStart=False, markerExpansion=1, customMarker=None, allowSkip=True, escapeKeys=['escape'], mouseOnly=False, displaySizeFactor=1.0, stretchHoriz=1.0, offsetVert=-0.4, offsetHoriz=0.0, minTime=1.0)
:Parameters: win : A :class:`~psychopy.visual.Window` object (required) scale : string, explanation of the numbers to display to the subject; default = None will result in a default scale: <low>=not at all, <high>=extremely low : lowest rating / low anchor (integer, default = 1) high : highest rating / high anchor (integer, default = 7; at least low+1) precision : portions of a tick to accept as input [1,10,100], default = 1 tick (no fractional parts) source code

draw(self)
update visual display, check for subject response (key, mouse, skip), set self.noResponse as appropriate.

source code

reset(self)
restores to post-init state; does not restore scaleDescription text, which would be needed between items when rating multiple items.

source code

getRating(self)
Returns the numerical rating; None if the subject skipped this item; False if not available.

source code

getRT(self)
Returns the seconds taken to make the rating (or to indicate skip).

source code

Method Details

init(self, win, scale=None, low=1, high=7, precision=1, showValue=True, showScale=True, showAnchors=True, showAccept=True, acceptKeys=`['return']`, acceptPreText=`'key, click'`, acceptText=`'accept?'`, leftKeys=`['left']`, rightKeys=`['right']`, markerStyle=`'triangle'`, markerColor=None, markerStart=False, markerExpansion=1, customMarker=None, allowSkip=True, escapeKeys=`['escape']`, mouseOnly=False, displaySizeFactor=1.0, stretchHoriz=1.0, offsetVert=-0.4, offsetHoriz=0.0, minTime=1.0)
(Constructor)

source code


:Parameters:
    win :
        A :class:`~psychopy.visual.Window` object (required)
    scale :
        string, explanation of the numbers to display to the subject;
        default = None will result in a default scale: <low>=not at all, <high>=extremely
    low :
        lowest rating / low anchor (integer, default = 1)
    high :
        highest rating / high anchor (integer, default = 7; at least low+1)
    precision :
        portions of a tick to accept as input [1,10,100], default = 1 tick (no fractional parts)
        
        .. note:: left/right arrow keys will move the marker by one portion of a tick.
    showValue :
        show the subject their currently selected number, default = True
    showScale :
        show the scale text, default = True
    showAnchors :
        show the two end points of the scale (low, high), default = True
    showAccept :
        show the button to click to accept the current value by using the mouse, default = True
                       
        .. note:: 
            If showAccept is False and acceptKeys is empty, acceptKeys is reset to ['return']
            to give the subject a way to respond. Better to avoid this situation.
    acceptKeys :
        list of keys that mean "accept the current response", default = ['return']
    acceptPreText :
        text to display before any value has been selected
    acceptText :
        text to display in the 'accept' button after a value has been selected
    leftKeys :
        list of keys that mean "move leftwards", default = ['left']
    rightKeys :
        list of keys that mean "move rightwards", default = ['right']
    markerStyle :
        *'triangle'* (DarkBlue), 'circle' (DarkRed), or 'glow' (White)
    markerColor :
        *None* = use defaults; or any legal RGB colorname, e.g., '#123456', 'DarkRed'
    markerStart :
        *False*, or the value in [low..high] to be pre-selected upon initial display
    markerExpansion :
        how much the glow marker expands when moving to the right; 0=none, negative shrinks; try 10 or -10
    allowSkip :
        if True, the subject can skip an item by pressing a key in escapeKeys, or <esc> if escapeKeys == []
    escapeKeys :
        list of keys the subject can use to skip a response, default = ['escape']
        
        .. note:: to require a response to every item, use allowSkip=False rather than an empty escapeKeys list
    mouseOnly :
        require the subject use the mouse only (no keyboard), default = False. can be used to avoid competing 
        with other objects for keyboard input.
        
        .. note::
        mouseOnly=True and showAccept=False is a bad combination, so showAccept wins (mouseOnly reset to False);
        similarly, mouseOnly and allowSkip can conflict, because skipping an item is done via key press (mouseOnly wins)
        mouseOnly=True is helpful if there will be something else on the screen expecting keyboard input
    displaySizeFactor :
        how much to expand or contract the overall rating scale display (not just the line length)
    offsetVert :
        how much to shift the rating line up or down on the screen, norm units; default -0.4 (lower than center)
    offsetHoriz:
        how much to shift right - left, norm units; default = 0.0 (centered)
    stretchHoriz:
        multiplicative factor for stretching (or compressing) the scale horizontally; 3 -> use the whole window
    minTime :
        number of seconds that must elapse before a reponse can be accepted, default = 1.0s
        
        .. note:: to enforce a max response time (upper limit), just present the ratingScale for that long

draw(self)

source code

update visual display, check for subject response (key, mouse, skip), set self.noResponse as appropriate. draw() only draws the rating scale, not the item to be rated

getRT(self)

source code

Returns the seconds taken to make the rating (or to indicate skip). Returns None if no rating available.