stimPos

Experiments

Overrides the default centered row layout by shifting stimuli (stim1..stimN) to explicit positions relative to the canvas center. Supports per-stimulus fixed offsets, random positions from a set of alternatives, random positions within an interval, and position “blocks” (a positioned stimulus followed by unpositioned ones that lay out as a row centered on that position). Works for image trials and word trials.

Positions are resolved afresh at the start of every trial presentation, so random choices re-roll each time the trial is shown.

Syntax

Give each stimulus an X Y pixel offset from the canvas center, one segment per stimulus separated by semicolons: -250 0;250 0 puts stim1 250 px left of center and stim2 250 px right.

Segment i belongs to stim i. An empty segment means “no own position” (see the block behavior under Works with).

Each non-empty segment is either:

• a single point: X Y (coordinates separated by whitespace), or X alone (vertical defaults to 0);
• a set of point alternatives: (X Y)|(X Y)|..., from which one point is picked at random per presentation.

Each coordinate X or Y can be:

1. A keyword: center = 0, left = minus half the canvas width, right = plus half the canvas width, top = minus half the canvas height, bottom = plus half the canvas height. A keyword must be the whole coordinate.
2. An interval: MIN_MAX (integers, negatives allowed, e.g. -150_150), giving a uniform random integer between MIN and MAX.
3. Numeric alternatives: 100|200|-300, one number picked at random.
4. A plain integer.

Units: pixels offset from the canvas center. Positive X = right, negative X = left; positive Y = down, negative Y = up. On image trials the offsets scale with the participant’s screen size; on word trials the raw offsets are used with NO scaling.

Options

Segment / coordinate value	Effect
empty (whole cell)	default automatic layout (centered row)
empty segment (;;)	image trials: stim joins the block of the nearest preceding positioned stim; word trials: crashes, see Tips & gotchas
X Y	fixed offset from canvas center
X	horizontal offset only, vertical = 0
(X Y)|(X Y)|...	random pick of one point per presentation
coord center/left/right/top/bottom	keyword offset (see above)
coord MIN_MAX	random integer in interval
coord A|B|C (numbers only)	random pick of one number
coord integer (e.g. -200)	that many px from center
coord non-numeric garbage	not a number; layout silently breaks (no error)

Defaults & missing values

• When the column is absent or the cell is left blank, every stimulus uses the automatic centered-row layout.
• Fewer segments than stimuli (image trials): trailing stimuli join the block of the last positioned stimulus.
• The resolved positions of every trial are recorded in the results column stimPos_actual in the form h v;h v;... (unscaled values, with empty segments staying empty between the semicolons). Trials without positions record no value. This is how randomly picked positions are recoverable.

Works with

• Blocks with unpositioned stimuli (images): a segment with a position starts a new block anchored at that offset; following stimuli with empty/no segments extend that block into a horizontally laid-out row, and the whole block is CENTERED on the anchor point, exactly like the default layout is centered on the canvas center. Example: three stimuli with stimPos = -300 0;;300 0 render stim1+stim2 as a row centered on x = -300 and stim3 centered at x = +300.
• stimSize: computed stimulus widths/heights (from stimSize or natural size) determine spacing inside blocks.
• Word trials: each word is centered at canvas center + its own offset. There is no block behavior; every displayed word needs its own segment (see Tips & gotchas).
• target / mask: not shifted by stimPos; only the stimulus slots receive shifts. Mask position is computed independently.
• Audio/video: no effect; audio/video stimuli are always centered.
• stimOptions random: positions belong to display slots; stimulus order randomization shuffles which stimulus lands in each positioned slot.
• Vertical auto-shift: for image trials with a target above the stimuli, an extra vertical shift keeps everything on canvas; it is added on top of stimPos offsets.

Examples

type	stimFormat	stim1	stim2	stimPos
test	.jpg	left_img	right_img	-250 0;250 0

stim1 centered 250 px left of canvas center, stim2 250 px right.

type	stimFormat	stim1	stimPos
test	.png	probe	(left 0)|(right 0)

The single stimulus appears at the far left or far right edge offset, chosen randomly each time the trial runs; the chosen offset is saved in stimPos_actual.

type	stimFormat	stim1	stimPos
test	.png	dot	-300_300 -200_200

Stimulus placed at a uniformly random position within the rectangle x in [-300, 300], y in [-200, 200].

type	stimFormat	stim1	stim2	stim3	stim4	stim5	stimPos
test	.png	a	b	c	d	e	35 0; 70 0; 0 0; -35 0; -70 0

A real five-stimulus row: one explicit X Y offset per stimulus laying them out along a horizontal line. This positional-list-per-stim pattern (one segment per stimulus, plain integer offsets) is the most common real-world shape, alongside single-value cells like 0 0, 0, 400, -400, and pipe-alternative cells like -300|300 -300|300 for random left/right placement.

Tips & gotchas

• Re-rolled every presentation: random alternatives and intervals are evaluated each time the trial is shown; a repeated trial can show different positions each repetition.

Caution

Word trials need a segment per word: an empty or missing segment for any displayed word breaks the trial. Empty-segment block continuation only works on image trials.

• Keywords cannot appear inside coordinate-level | alternatives (left|right does not work), but they DO work inside point-level alternatives like (left 0)|(right 0).
• left/right/top/bottom resolve to half-canvas offsets of their own axis regardless of which coordinate slot they are used in; writing top in the X slot shifts horizontally by minus half the canvas height.
• A LEADING empty segment (e.g. ;100 0) gives stim1 no position at all: it falls back to the automatic layout’s first-slot placement but is never re-centered with the rest of its row, so with an even stimulus count its right edge sits at the canvas center instead of the row being centered. Start the cell with a real position.
• A segment containing | without parentheses is treated as a single point whose coordinates may still contain numeric alternatives.

Common combinations

stimPos appears in these worked recipes:

• Counterbalanced sides: Show a fixed pair of stimuli with the left and right assignment drawn once per participant, and score the choice correctly whichever side the target lands on.
• Side-by-side comparison: Show two images left and right of centre and let the participant click their choice, scored correctly whichever side the target lands on.
• Dot-probe task: Show a pair of images side by side, replace one with a probe, and measure how fast the probe’s location is reported, in one row per trial.