DotStim¶This stimulus class defines a field of dots with an update rule that determines how they change on every call to the .draw() method. This is a lazy-imported class, therefore import using full path from psychopy.visual.dot import DotStim when inheriting from it.
This single class can be used to generate a wide variety of dot motion types. For a review of possible types and their pros and cons see Scase, Braddick & Raymond (1996). All six possible motions they describe can be generated with appropriate choices of the signalDots (which determines whether signal dots are the ‘same’ or ‘different’ on each frame), noiseDots (which determines the locations of the noise dots on each frame) and the dotLife (which determines for how many frames the dot will continue before being regenerated).
The default settings (as of v1.70.00) is for the noise dots to have identical velocity but random direction and signal dots remain the ‘same’ (once a signal dot, always a signal dot).
For further detail about the different configurations see DotsComponent in the Builder Components section of the documentation.
If further customisation is required, then the DotStim should be subclassed and its _update_dotsXY and _newDotsXY methods overridden.
The maximum number of dots that can be drawn is limited by system performance.
‘sqr’ or ‘circle’. Defines the envelope used to present the dots. If changed while drawing, dots outside new envelope will be respawned.
Dot size specified in pixels (overridden if element is specified). operations are supported.
Number of frames each dot lives for (-1=infinite). Dot lives are initiated randomly from a uniform distribution from 0 to dotLife. If changed while drawing, the lives of all dots will be randomly initiated again.
If ‘same’ then the signal and noise dots are constant. If ‘different’ then the choice of which is signal and which is noise gets randomised on each frame. This corresponds to Scase et al’s (1996) categories of RDK.
Determines the behaviour of the noise dots, taken directly from Scase et al’s (1996) categories. For ‘position’, noise dots take a random position every frame. For ‘direction’ noise dots follow a random, but constant direction. For ‘walk’ noise dots vary their direction every frame, but keep a constant speed.
This can be any object that has a .draw() method and a
.setPos([x,y]) method (e.g. a GratingStim, TextStim…)!! DotStim
assumes that the element uses pixels as units. None defaults to
dots.
Specifying the location of the centre of the stimulus using a
x,y-pair. See e.g. ShapeStim for more
documentation/examples on how to set position.
operations are supported.
array_like
Specifying the size of the field of dots using a
x,y-pair. See e.g. ShapeStim for more
documentation/examples on how to set position.
operations are supported.
array_like
Change the coherence (%) of the DotStim. This will be rounded according to the number of dots in the stimulus.
Direction of the coherent dots in degrees. operations are supported.
Speed of the dots (in units/frame). operations are supported.
win (window.Window) – Window this stimulus is associated with.
units (str) – Units to use.
nDots (int) – Number of dots to present in the field.
coherence (float) – Proportion of dots which are coherent. This value can be set using the coherence property after initialization.
fieldPos (array_like) – (x,y) or [x,y] position of the field. This value can be set using the fieldPos property after initialization.
fieldSize (array_like, int or float) – (x,y) or [x,y] or single value (applied to both dimensions). Sizes can be negative and can extend beyond the window. This value can be set using the fieldSize property after initialization.
fieldShape (str) – Defines the envelope used to present the dots. If changed while drawing by setting the fieldShape property, dots outside new envelope will be respawned., valid values are ‘square’, ‘sqr’ or ‘circle’.
dotSize (array_like or float) – Size of the dots. If given an array, the sizes of individual dots will be set. The array must have length nDots. If a single value is given, all dots will be set to the same size.
dotLife (int) – Lifetime of a dot in frames. Dot lives are initiated randomly from a uniform distribution from 0 to dotLife. If changed while drawing, the lives of all dots will be randomly initiated again. A value of -1 results in dots having an infinite lifetime. This value can be set using the dotLife property after initialization.
dir (float) – Direction of the coherent dots in degrees. At 0 degrees, coherent dots will move from left to right. Increasing the angle will rotate the direction counter-clockwise. This value can be set using the dir property after initialization.
speed (float) – Speed of the dots (in units per frame). This value can be set using the speed property after initialization.
rgb (array_like, optional) – Color of the dots in form (r, g, b) or [r, g, b]. Deprecated, use color instead.
color (array_like or str) – Color of the dots in form (r, g, b) or [r, g, b].
colorSpace (str) – Colorspace to use.
opacity (float) – Opacity of the dots from 0.0 to 1.0.
contrast (float) – Contrast of the dots 0.0 to 1.0. This value is simply multiplied by the color value.
depth (float) – Deprecated, depth is now controlled simply by drawing order.
element (object) – This can be any object that has a .draw() method and a
.setPos([x,y]) method (e.g. a GratingStim, TextStim…)!!
DotStim assumes that the element uses pixels as units.
None defaults to dots.
signalDots (str) – If ‘same’ then the signal and noise dots are constant. If different then the choice of which is signal and which is noise gets randomised on each frame. This corresponds to Scase et al’s (1996) categories of RDK. This value can be set using the signalDots property after initialization.
noiseDots (str) – Determines the behaviour of the noise dots, taken directly from Scase et al’s (1996) categories. For ‘position’, noise dots take a random position every frame. For ‘direction’ noise dots follow a random, but constant direction. For ‘walk’ noise dots vary their direction every frame, but keep a constant speed. This value can be set using the noiseDots property after initialization.
name (str, optional) – Optional name to use for logging.
autoLog (bool) – Enable automatic logging.