A checkerboard pattern. Includes options for flicker, phase drift, and internally balanced phase drift. This element type also includes an animation option commonly used in retinotopy tasks: a sequence of isolated bars shown by stepping an aperture across the checkerboard. For just a static checkerboard or with flicker or phase drift only, see element type checkerboard. See also dartboardRetinotopy.

"Ends on its own" means ends automatically at that point. If an element can end on its own, you don't need to set end conditions for it in property end (unless you want it to maybe end earlier).

size

Default: square with sides 10 deg

A number that is side length for a square checkerboard, or a vector [width height] for a rectangle (deg).

numChecks

Default: 20 square checks across checkerboard width

Number of checks across the width of the checkerboard. Number of checks across its height is then automatic to give square checks.

Or a vector [n_w n_h] setting number of checks across width and height independently. You can use this if you want non-square checks.

orientation

Default: horizontal and vertical

Orientation angle of the checkerboard, + = clockwise (deg). 0 = horizontal and vertical rows/columns of checks. This sets rotation of the checkerboard within its rectangular display area. If you want rotation of the whole display, use property rotation.

phase

Default: first check right and below center is light

0/1 setting the initial pattern: 0 = first check right and below display center is dark, 1 = light. Currently the checkerboard is always centered at element position, with the corners of four checks at that point. Element position can be set in property position.

meanIntensity
amplitude
contrast

Defaults: meanIntensity = 0.5, amplitude = 0.5

meanIntensity is a number between 0–1 (black–maximum) setting the mean intensity of dark and light checks.

Also set one of amplitude OR contrast:

amplitude is intensity of light checks − intensity of dark checks.

contrast is Michelson contrast, amplitude / mean intensity. If you set contrast, mean intensity must be > 0.

Intensity always clips at 0 and 1. It's possible to set a combination of these properties that causes the checkerboard to clip in this way. See record properties maxAmplitude and maxContrast below.

color

Default: white <cd>[1 1 1]<cd>

A 1×3 RGB vector with numbers between 0–1. This defines the color at intensity = 1. Color at intensity = 0 is <cd>[0 0 0]<cd>. Color at intensities between 0–1 is linearly interpolated between the two. Note intensity, as defined by amplitude/contrast + meanIntensity above, always clips at 0 and 1, so color clips at <cd>[0 0 0]<cd> and color.

flickerFrequency
temporalFrequency
temporalFrequencyBalanced
fps

Defaults: no flicker or phase drift
Default: fps = 30 frames/sec

You can set one of flickerFrequency, temporalFrequency, OR temporalFrequencyBalanced:

flickerFrequency is frequency of switching between dark–light checks (cycles/sec). 0 = no flicker.

temporalFrequency is continuous phase drift rate. This is a 1×2 vector [v_x v_ y] specifying a rate for either horizontal or vertical drift (cycles/sec). You can only do horizontal OR vertical, so leave the other number at 0. The number you set can be positive or negative to specify direction: +/− = right/left or down/up (at orientation above = 0).

temporalFrequencyBalanced is similar except alternating rows or columns drift in opposite directions, creating an internally counterbalanced phase drift (cycles/sec). Here +/− just switches which rows/columns move in which direction.

You can combine using these properties with bar apertures below.

fps: If you set temporalFrequencyBalanced, PsychBench implements the animation as a sequence of images showing at some frame rate (maximum). You can change that frame rate here if you want (frames/sec). Note this doesn't affect actual temporal frequency, just maybe the quality of the animation.

showBars
apertureSize
apertureStep
apertureInterval
maxNumLoops

Default: showBars = don't show bars—show whole checkerboard
Default: apertureSize = 2 checks
Default: apertureStep = 1 check moving right
Default: apertureInterval = 1 sec
Default: maxNumLoops = show one pass through the checkerboard

showBars = <cd>true<cd>/<cd>false<cd>: show a sequence of isolated bars by stepping an aperture across the checkerboard. If set = <cd>true<cd>:

apertureSize is bar width (checks).

apertureStep is how far the bar moves at each step (checks). +/− determines direction of movement: + = right, − = left.

apertureInterval is time between steps (sec).

maxNumLoops is a number > 0 that is number of passes through the checkerboard to show, after which the object ends. <cd>inf<cd> = repeat until a condition you set in property end.

Note these numbers can be fractional, not just integer.

Currently the bar always moves horizontally. If you want it to appear to move at other angles, use property rotation to rotate the display. Initial bar shown is always at the left edge of the checkerboard if apertureStep > 0, or right edge if apertureStep < 0 (moving left/right at rotation = 0).

position
nn_eyes
rotation
colorMask
alpha
intensity
contrastMult
drawCodeVars

maxAmplitude
maxContrast

Maximum amplitude and contrast where intensity would clip at 0 or 1, whichever is reached first, given the set mean intensity.