Form
¶
Attributes¶
|
A class to add Forms to a psychopy.visual.Window |
The |
|
This determines the coordinates of the vertices for the current stimulus in pixels, accounting for size, ori, pos and units |
|
Placeholder method to update colours when set externally, for example updating the pallette attribute of a textbox. |
|
Placeholder method to update colours when set externally, for example updating the pallette attribute of a textbox |
|
The size (width, height) of the stimulus in the stimulus units |
|
|
Usually you can use 'stim.attribute = value' syntax instead, but use this method if you need to suppress the log message |
|
Set scroll speed of Form. |
|
DEPRECATED: Legacy setter for foreground RGB, instead set obj._foreColor.rgb |
|
Usually you can use 'stim.attribute = value' syntax instead, but use this method if you need to suppress the log message. |
|
Usually you can use 'stim.attribute = value' syntax instead, but use this method if you need to suppress the log message |
|
Hard setter for opacity, allows the suppression of log messages and calls the update method |
|
|
|
DEPRECATED since v1.60.05: Please use the color attribute |
|
Hard setter for foreColor, allows suppression of the log message, simultaneous colorSpace setting and calls update methods. |
|
Hard setter for fillColor, allows suppression of the log message, simultaneous colorSpace setting and calls update methods. |
|
Usually you can use 'stim.attribute = value' syntax instead, but use this method if you need to suppress the log message |
|
DEPRECATED since v1.60.05: Please use the color attribute |
|
Usually you can use 'stim.attribute = value' syntax instead, but use this method if you need to suppress the log message |
|
|
|
Hard setter for fillColor, allows suppression of the log message, simultaneous colorSpace setting and calls update methods. |
|
|
|
Usually you can use 'stim.attribute = value' syntax instead, but use this method if you need to suppress the log message. |
|
Sets autoDraw for Form and any responseCtrl contained within |
The position of the center of the stimulus in the stimulus units |
|
|
Returns True if this stimulus intersects another one. |
The orientation of the stimulus (in degrees). |
|
Determines how visible the stimulus is relative to background. |
|
The name (str) of the object to be using during logged messages about this stim. |
|
Alternative way of setting borderColor. |
|
|
Import items from csv or excel sheet and convert to list of dicts. |
Extracts form questions, response ratings and response times from Form items |
|
Deprecated in version 2020.2. |
|
Sets both itemColor and responseColor to the same value |
|
Color of the form's background |
|
Draw all form elements |
|
DEPRECATED, depth is now controlled simply by drawing order. |
|
A value that is simply multiplied by the color. |
|
|
Returns True if a point x,y is inside the stimulus' border. |
A read-only property to determine if the current form is complete |
|
The name of the color space currently being used |
|
Alternative way of setting foreColor. |
|
Color of the line around the form |
|
Alternative way of setting fillColor |
|
Whether every change in this stimulus should be auto logged. |
|
Determines whether the stimulus should be automatically drawn on every frame flip. |
|
|
Gets the current Form data and inserts into an |
Details¶
- class psychopy.visual.form.Form(win, name='default', colorSpace='rgb', fillColor=None, borderColor=None, itemColor='white', responseColor='white', markerColor='red', items=None, font=None, textHeight=0.02, size=(0.5, 0.5), pos=(0, 0), style=None, itemPadding=0.05, units='height', randomize=False, autoLog=True, depth=0, color=undefined, foreColor=undefined)[source]¶
A class to add Forms to a psychopy.visual.Window
The Form allows Psychopy to be used as a questionnaire tool, where participants can be presented with a series of questions requiring responses. Form items, defined as questions and response pairs, are presented simultaneously onscreen with a scrollable viewing window.
Example
survey = Form(win, items=[{}], size=(1.0, 0.7), pos=(0.0, 0.0))
- Parameters:
win (psychopy.visual.Window) – The window object to present the form.
items (List of dicts or csv or xlsx file) –
- a list of dicts or csv file should have the following key, value pairs / column headers:
”index”: The item index as a number “itemText”: item question string, “itemWidth”: fraction of the form width 0:1 “type”: type of rating e.g., ‘radio’, ‘rating’, ‘slider’ “responseWidth”: fraction of the form width 0:1, “options”: list of tick labels for options, “layout”: Response object layout e.g., ‘horiz’ or ‘vert’
textHeight (float) – Text height.
itemPadding (float) – Space or padding between form items.
units (str) – units for stimuli - Currently, Form class only operates with ‘height’ units.
randomize (bool) – Randomize order of Form elements
- property RGB¶
Legacy property for setting the foreground color of a stimulus in RGB, instead use obj._foreColor.rgb
- Type:
DEPRECATED
- _calcPosRendered()¶
DEPRECATED in 1.80.00. This functionality is now handled by _updateVertices() and verticesPix.
- _calcSizeRendered()¶
DEPRECATED in 1.80.00. This functionality is now handled by _updateVertices() and verticesPix
- _createItemCtrls()[source]¶
Define layout of form
- _drawCtrls()[source]¶
Draw elements on form within border range.
- Parameters:
items (List) – List of TextStim or Slider item from survey
- _drawDecorations()[source]¶
Draw decorations on form.
- _drawExternalDecorations()[source]¶
Draw decorations outside the aperture
- _getDesiredRGB(rgb, colorSpace, contrast)¶
Convert color to RGB while adding contrast. Requires self.rgb, self.colorSpace and self.contrast
- _getItemHeight(item, ctrl=None)[source]¶
Returns the full height of the item to be inserted in the form
- _getItemRenderedWidth(size)[source]¶
Returns text width for item text based on itemWidth and Form width.
- _getPolyAsRendered()¶
DEPRECATED. Return a list of vertices as rendered.
- _getScrollOffset()[source]¶
Calculate offset position of items in relation to markerPos. Offset is a proportion of vheight - height, meaning the max offset (when scrollbar.markerPos is 1) is enough to take the bottom element to the bottom of the border.
- Returns:
Offset position of items proportionate to scroll bar
- Return type:
- _inRange(item)[source]¶
Check whether item position falls within border area
- _layoutY()[source]¶
This needs to be done when editable textboxes change their size because everything below them needs to move too
- _makeSlider(item)[source]¶
Creates Slider object for Form class
- _makeTextBox(item)[source]¶
Creates TextBox object for Form class
NOTE: The TextBox 2 in work in progress, and has not been added to Form class yet. :param item: The dict entry for a single item :type item: dict :param pos: position of response object :type pos: tuple
- Returns:
psychopy.visual.TextBox – The TextBox object for response
respHeight – The height of the response object as type float
- _selectWindow(win)¶
Switch drawing to the specified window. Calls the window’s _setCurrent() method which handles the switch.
- _set(attrib, val, op='', log=None)¶
DEPRECATED since 1.80.04 + 1. Use setAttribute() and val2array() instead.
- _setAperture()[source]¶
Blocks text beyond border using Aperture
- Returns:
The aperture setting viewable area for forms
- Return type:
- _setBorder()[source]¶
Creates border using Rect
- Returns:
The border for the survey
- Return type:
psychopy.visual.Rect
- _setDecorations()[source]¶
Sets Form decorations i.e., Border and scrollbar
- _setQuestion(item)[source]¶
Creates TextStim object containing question
- Parameters:
item (dict) – The dict entry for a single item
- Returns:
psychopy.visual.text.TextStim – The textstim object with the question string
questionHeight – The height of the question bounding box as type float
questionWidth – The width of the question bounding box as type float
- _setResponse(item)[source]¶
Makes calls to methods which make Slider or TextBox response objects for Form
- _setScrollBar()[source]¶
Creates Slider object for scrollbar
- Returns:
The Slider object for scroll bar
- Return type:
- _updateList()¶
The user shouldn’t need this method since it gets called after every call to .set() Chooses between using and not using shaders each call.
- _updateVertices()¶
Sets Stim.verticesPix and ._borderPix from pos, size, ori, flipVert, flipHoriz
- addDataToExp(exp, itemsAs='rows')[source]¶
Gets the current Form data and inserts into an
ExperimentHandler
object either as rows or as columns- Parameters:
exp (
ExperimentHandler
)itemsAs ('rows','cols' (or 'columns'))
- alphaThreshold¶
Threshold for alpha values.
If the alpha value of a pixel is below this threshold, the pixel will be rejected (not drawn). This can be useful for creating a mask from an image with an alpha channel. The default value is 0.0, which means that no thresholding will be applied.
- property anchor¶
- autoDraw¶
Determines whether the stimulus should be automatically drawn on every frame flip.
Value should be: True or False. You do NOT need to set this on every frame flip!
- autoLog¶
Whether every change in this stimulus should be auto logged.
Value should be: True or False. Set to False if your stimulus is updating frequently (e.g. updating its position every frame) and you want to avoid swamping the log file with messages that aren’t likely to be useful.
- property backColor¶
Alternative way of setting fillColor
- property backColorSpace¶
Deprecated, please use colorSpace to set color space for the entire object.
- property backRGB¶
Legacy property for setting the fill color of a stimulus in RGB, instead use obj._fillColor.rgb
- Type:
DEPRECATED
- property backgroundColor¶
Alternative way of setting fillColor
- property borderColor¶
Color of the line around the form
- property borderColorSpace¶
Deprecated, please use colorSpace to set color space for the entire object
- property borderRGB¶
Legacy property for setting the border color of a stimulus in RGB, instead use obj._borderColor.rgb
- Type:
DEPRECATED
- borderWidth¶
- property color¶
Alternative way of setting foreColor.
- property colorSpace¶
The name of the color space currently being used
Value should be: a string or None
For strings and hex values this is not needed. If None the default colorSpace for the stimulus is used (defined during initialisation).
Please note that changing colorSpace does not change stimulus parameters. Thus you usually want to specify colorSpace before setting the color. Example:
# A light green text stim = visual.TextStim(win, 'Color me!', color=(0, 1, 0), colorSpace='rgb') # An almost-black text stim.colorSpace = 'rgb255' # Make it light green again stim.color = (128, 255, 128)
- property complete¶
A read-only property to determine if the current form is complete
- contains(x, y=None, units=None)¶
Returns True if a point x,y is inside the stimulus’ border.
- Can accept variety of input options:
two separate args, x and y
one arg (list, tuple or array) containing two vals (x,y)
- an object with a getPos() method that returns x,y, such
as a
Mouse
.
Returns True if the point is within the area defined either by its border attribute (if one defined), or its vertices attribute if there is no .border. This method handles complex shapes, including concavities and self-crossings.
Note that, if your stimulus uses a mask (such as a Gaussian) then this is not accounted for by the contains method; the extent of the stimulus is determined purely by the size, position (pos), and orientation (ori) settings (and by the vertices for shape stimuli).
See Coder demos: shapeContains.py See Coder demos: shapeContains.py
- property contrast¶
A value that is simply multiplied by the color.
- Value should be: a float between -1 (negative) and 1 (unchanged).
Operations supported.
Set the contrast of the stimulus, i.e. scales how far the stimulus deviates from the middle grey. You can also use the stimulus opacity to control contrast, but that cannot be negative.
Examples:
stim.contrast = 1.0 # unchanged contrast stim.contrast = 0.5 # decrease contrast stim.contrast = 0.0 # uniform, no contrast stim.contrast = -0.5 # slightly inverted stim.contrast = -1.0 # totally inverted
Setting contrast outside range -1 to 1 is permitted, but may produce strange results if color values exceeds the monitor limits.:
stim.contrast = 1.2 # increases contrast stim.contrast = -1.2 # inverts with increased contrast
- depth¶
DEPRECATED, depth is now controlled simply by drawing order.
- draw()[source]¶
Draw all form elements
- property fillColor¶
Color of the form’s background
- property fillColorSpace¶
Deprecated, please use colorSpace to set color space for the entire object.
- property fillRGB¶
Legacy property for setting the fill color of a stimulus in RGB, instead use obj._fillColor.rgb
- Type:
DEPRECATED
- property flip¶
1x2 array for flipping vertices along each axis; set as True to flip or False to not flip. If set as a single value, will duplicate across both axes. Accessing the protected attribute (._flip) will give an array of 1s and -1s with which to multiply vertices.
- property flipHoriz¶
- property flipVert¶
- property fontColor¶
Alternative way of setting foreColor.
- property foreColor¶
Sets both itemColor and responseColor to the same value
- property foreColorSpace¶
Deprecated, please use colorSpace to set color space for the entire object.
- property foreRGB¶
Legacy property for setting the foreground color of a stimulus in RGB, instead use obj._foreColor.rgb
- Type:
DEPRECATED
- formComplete()[source]¶
Deprecated in version 2020.2. Please use the Form.complete property
- getAlphaThreshold()¶
- getAnchor()¶
- getAutoDraw()¶
- getAutoLog()¶
- getBackColor()¶
- getBackColorSpace()¶
- getBackRGB()¶
- getBackgroundColor()¶
- getBorderColor()¶
- getBorderColorSpace()¶
- getBorderRGB()¶
- getBorderWidth()¶
- getColor()¶
- getColorSpace()¶
- getComplete()¶
- getContrast()¶
- getData()[source]¶
Extracts form questions, response ratings and response times from Form items
- Returns:
A copy of the data as a list of dicts
- Return type:
- getDepth()¶
- getFillColor()¶
- getFillColorSpace()¶
- getFillRGB()¶
- getFlip()¶
- getFlipHoriz()¶
- getFlipVert()¶
- getFontColor()¶
- getForeColor()¶
- getForeColorSpace()¶
- getForeRGB()¶
- getHeight()¶
- getItemColor()¶
- getLineColor()¶
- getLineColorSpace()¶
- getLineRGB()¶
- getLineWidth()¶
- getMarkerColor()¶
- getName()¶
- getOpacity()¶
- getOri()¶
- getPos()¶
- getRGB()¶
- getResponseColor()¶
- getScrollbarWidth()¶
- getSize()¶
- getStyle()¶
- getUnits()¶
- getValues()¶
- getVertices()¶
- getVerticesPix()¶
- getWidth()¶
- getWin()¶
- get_borderPix()¶
- property height¶
- importItems(items)[source]¶
Import items from csv or excel sheet and convert to list of dicts. Will also accept a list of dicts.
Note, for csv and excel files, ‘options’ must contain comma separated values, e.g., one, two, three. No parenthesis, or quotation marks required.
- Parameters:
items (Excel or CSV file, list of dicts) – Items used to populate the Form
- Returns:
A list of dicts, where each list entry is a dict containing all fields for a single Form item
- Return type:
List of dicts
- property itemColor¶
Color of the text on form items
- knownStyles = {'dark': {'borderColor': None, 'fillColor': [-0.19, -0.19, -0.14], 'font': 'Noto Sans', 'itemColor': 'white', 'markerColor': [0.89, -0.35, -0.28], 'responseColor': 'white'}, 'light': {'borderColor': None, 'fillColor': [0.89, 0.89, 0.89], 'font': 'Noto Sans', 'itemColor': 'black', 'markerColor': [0.89, -0.35, -0.28], 'responseColor': 'black'}}¶
- property lineColor¶
Alternative way of setting borderColor.
- property lineColorSpace¶
Deprecated, please use colorSpace to set color space for the entire object
- property lineRGB¶
Legacy property for setting the border color of a stimulus in RGB, instead use obj._borderColor.rgb
- Type:
DEPRECATED
- lineWidth¶
- property markerColor¶
Color of the marker on any sliders in this form
- name¶
The name (str) of the object to be using during logged messages about this stim. If you have multiple stimuli in your experiment this really helps to make sense of log files!
If name = None your stimulus will be called “unnamed <type>”, e.g. visual.TextStim(win) will be called “unnamed TextStim” in the logs.
- property opacity¶
Determines how visible the stimulus is relative to background.
The value should be a single float ranging 1.0 (opaque) to 0.0 (transparent). Operations are supported. Precisely how this is used depends on the Blend Mode.
- ori¶
The orientation of the stimulus (in degrees).
Should be a single value (scalar). Operations are supported.
Orientation convention is like a clock: 0 is vertical, and positive values rotate clockwise. Beyond 360 and below zero values wrap appropriately.
- overlaps(polygon)¶
Returns True if this stimulus intersects another one.
If polygon is another stimulus instance, then the vertices and location of that stimulus will be used as the polygon. Overlap detection is typically very good, but it can fail with very pointy shapes in a crossed-swords configuration.
Note that, if your stimulus uses a mask (such as a Gaussian blob) then this is not accounted for by the overlaps method; the extent of the stimulus is determined purely by the size, pos, and orientation settings (and by the vertices for shape stimuli).
See coder demo, shapeContains.py
- property pos¶
The position of the center of the stimulus in the stimulus units
value should be an x,y-pair. Operations are also supported.
Example:
stim.pos = (0.5, 0) # Set slightly to the right of center stim.pos += (0.5, -1) # Increment pos rightwards and upwards. Is now (1.0, -1.0) stim.pos *= 0.2 # Move stim towards the center. Is now (0.2, -0.2)
Tip: If you need the position of stim in pixels, you can obtain it like this:
from psychopy.tools.monitorunittools import posToPix posPix = posToPix(stim)
- reset()[source]¶
Clear all responses and set all items to their initial values.
- property responseColor¶
Color of the lines and text on form responses
- property scrollbarWidth¶
Width of the scrollbar for this Form, in the spatial units of this Form. Can also be set as a layout.Vector object.
- setAlphaThreshold(value, log=None)¶
Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message.
- setAnchor(value, log=None)¶
- setAutoDraw(value, log=None)[source]¶
Sets autoDraw for Form and any responseCtrl contained within
- setAutoLog(value=True, log=None)¶
Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message.
- setBackColor(color, colorSpace=None, operation='', log=None)¶
- setBackColorSpace(value, log=None, operation=False, stealth=False)¶
- setBackRGB(color, operation='', log=None)¶
DEPRECATED: Legacy setter for fill RGB, instead set obj._fillColor.rgb
- setBackgroundColor(color, colorSpace=None, operation='', log=None)¶
- setBorderColor(color, colorSpace=None, operation='', log=None)¶
Hard setter for fillColor, allows suppression of the log message, simultaneous colorSpace setting and calls update methods.
- setBorderColorSpace(value, log=None, operation=False, stealth=False)¶
- setBorderRGB(color, operation='', log=None)¶
DEPRECATED: Legacy setter for border RGB, instead set obj._borderColor.rgb
- setBorderWidth(newWidth, operation='', log=None)¶
- setColor(color, colorSpace=None, operation='', log=None)¶
- setColorSpace(value, log=None, operation=False, stealth=False)¶
- setContrast(newContrast, operation='', log=None)¶
Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message
- setDKL(color, operation='')¶
DEPRECATED since v1.60.05: Please use the color attribute
- setDepth(newDepth, operation='', log=None)¶
Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message
- setFillColor(color, colorSpace=None, operation='', log=None)¶
Hard setter for fillColor, allows suppression of the log message, simultaneous colorSpace setting and calls update methods.
- setFillColorSpace(value, log=None, operation=False, stealth=False)¶
- setFillRGB(color, operation='', log=None)¶
DEPRECATED: Legacy setter for fill RGB, instead set obj._fillColor.rgb
- setFlip(value, log=None, operation=False, stealth=False)¶
- setFlipHoriz(value, log=None, operation=False, stealth=False)¶
- setFlipVert(value, log=None, operation=False, stealth=False)¶
- setFontColor(color, colorSpace=None, operation='', log=None)¶
- setForeColor(color, colorSpace=None, operation='', log=None)¶
Hard setter for foreColor, allows suppression of the log message, simultaneous colorSpace setting and calls update methods.
- setForeColorSpace(value, log=None, operation=False, stealth=False)¶
- setForeRGB(color, operation='', log=None)¶
DEPRECATED: Legacy setter for foreground RGB, instead set obj._foreColor.rgb
- setHeight(value, log=None, operation=False, stealth=False)¶
- setItemColor(value, log=None, operation=False, stealth=False)¶
- setLMS(color, operation='')¶
DEPRECATED since v1.60.05: Please use the color attribute
- setLineColor(color, colorSpace=None, operation='', log=None)¶
- setLineColorSpace(value, log=None, operation=False, stealth=False)¶
- setLineRGB(color, operation='', log=None)¶
DEPRECATED: Legacy setter for border RGB, instead set obj._borderColor.rgb
- setLineWidth(newWidth, operation='', log=None)¶
- setMarkerColor(value, log=None, operation=False, stealth=False)¶
- setName(value, log=None, operation=False, stealth=False)¶
- setOpacity(newOpacity, operation='', log=None)¶
Hard setter for opacity, allows the suppression of log messages and calls the update method
- setOri(newOri, operation='', log=None)¶
Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message
- setPos(newPos, operation='', log=None)¶
Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message.
- setRGB(color, operation='', log=None)¶
DEPRECATED: Legacy setter for foreground RGB, instead set obj._foreColor.rgb
- setResponseColor(value, log=None, operation=False, stealth=False)¶
- setScrollSpeed(items, multiplier=2)[source]¶
Set scroll speed of Form. Higher multiplier gives smoother, but slower scroll.
- setScrollbarWidth(value, log=None, operation=False, stealth=False)¶
- setSize(newSize, operation='', units=None, log=None)¶
Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message
- setStyle(value, log=None, operation=False, stealth=False)¶
- setUnits(value, log=None, operation=False, stealth=False)¶
- setValues(value, log=None, operation=False, stealth=False)¶
- setVertices(value, log=None, operation=False, stealth=False)¶
- setWidth(value, log=None, operation=False, stealth=False)¶
- setWin(value, log=None, operation=False, stealth=False)¶
- property size¶
The size (width, height) of the stimulus in the stimulus units
Value should be x,y-pair, scalar (applies to both dimensions) or None (resets to default). Operations are supported.
Sizes can be negative (causing a mirror-image reversal) and can extend beyond the window.
Example:
stim.size = 0.8 # Set size to (xsize, ysize) = (0.8, 0.8) print(stim.size) # Outputs array([0.8, 0.8]) stim.size += (0.5, -0.5) # make wider and flatter: (1.3, 0.3)
Tip: if you can see the actual pixel range this corresponds to by looking at stim._sizeRendered
- property style¶
- property units¶
- updateColors()¶
Placeholder method to update colours when set externally, for example updating the pallette attribute of a textbox
- updateOpacity()¶
Placeholder method to update colours when set externally, for example updating the pallette attribute of a textbox.
- property values¶
- property vertices¶
- property verticesPix¶
This determines the coordinates of the vertices for the current stimulus in pixels, accounting for size, ori, pos and units
- property width¶
- property win¶
The
Window
object in which the stimulus will be rendered by default. (required)Example, drawing same stimulus in two different windows and display simultaneously. Assuming that you have two windows and a stimulus (win1, win2 and stim):
stim.win = win1 # stimulus will be drawn in win1 stim.draw() # stimulus is now drawn to win1 stim.win = win2 # stimulus will be drawn in win2 stim.draw() # it is now drawn in win2 win1.flip(waitBlanking=False) # do not wait for next # monitor update win2.flip() # wait for vertical blanking.
Note that this just changes default window for stimulus.
You could also specify window-to-draw-to when drawing:
stim.draw(win1) stim.draw(win2)