Dot Lattice Users Manual

From KubovyLab

Note: These instructions are somewhat out of date.

Overview

This manual describes how to install and use the Kubovy Lab Dot Lattice experiment.

This release is a "beta", intended to serve as a starting point for you to critique, experiment with, and encourage new ideas. It is written using the cross-platform, high-level programming language called Python using the psycho-physical toolkit Vision Egg. This experiment is envisioned as just one of a library of experiments and associated components we hope to develop.

Please send feedback, bug reports, and enhancement requests to mailto:simeon.fitch@mseedsoft.com and or mailto:kubovy@virginia.edu.

Download and Install

This first beta of the Dot Lattice Experiment is available here: http://www.mseedsoft.com/kubovy/DotLatticeBeta.zip. (We hope to have a more permanent location on a UVa server in the near future). Please download the zip file and extract the contents somewhere convenient.

At this point there is no "installer". The zip archive contains the main executable, DotLattice.exe and its support files. Launch the DotLattice.exe executable as you would any other program.

Experiment Setup

Setup Dialog Window

When you launch the application you will always be presented with the following setup dialog.

Note that the defaults values show above are the same each time you run the application. A possible future enhancement is to remember previous changes entered by the user.

The fields are as follows:

Subject & Session numbers: numbers for tracking session
Break interval: the number of trials executed before the subject is given a message to take a break.
Practice trials: the number of unrecorded trials the subject performs at the beginning.
Sequence file: the input file defining the variable settings for each trial. Described in more detail below.
Data file: the file path where the results from each trail are recorded. If the file already exists, it is appended to. Described in more detail below.
Configure display: when enabled, a screen configuration dialog is presented before the experiment commences.

The default input and output file location is your My Documents folder on Microsoft Windows, and the $HOME directory on other platforms.

First Time Setup

There are several steps you must take the first time you run the application on a particular computer.

You will first need a sequence file (format described below) in the location specified by the setup dialog. If the file is missing after pressing "OK" in the setup dialog, you will be presented with the option to have the application create a sample file for you.

Next you should enable the Configure Display option. Doing so causes the following window to appear after the "OK" button is pressed.

You will want to:

Consult your current property display settings to get your screen resolution and refresh rate:

You will need a minimum resolution of 1024x768.
Change the values in the setup dialog to match:
Save your changes so you don't have to repeat this step each time the application is run.

After pressing "OK" the experiment will start.

Trial Sequence Input File Format

The sequence input file is a three column, tab-delimited text file. Each row contains the input variables for a trial. Three variables are supported:

angle: Dot lattice rotation angle (degrees)
aspectRatio: Ratio of $\begin{Vmatrix}AB\end{Vmatrix}$ to $\begin{Vmatrix}BC\end{Vmatrix}$
gamma: Angle (degrees) between $\vec{AB}$ and $\vec{BC}$

See the Kubovy Lab papers on dot lattice experiments for more details.

Here is a sample file defining 6 trials:

angle	aspectRatio	gamma
0	1.0		60
15	1.4		75
95	1.2		65
20	0.8		90
82	1.1		82
120	0.9		65

Trial Results Output File Format

The trial logging output file is also a tab delimited text file, with each row representing the state and results for each trial. In addition to the session and subject numbers, trial number, input variables, and subject response, the data file attempts to record every possible internal variable as well to facilitate reproducibility.

The following columns are currently recorded:

trial: trial number
response: selected response vector $r \in \{abcd\}$
responseTime: seconds between stimulus and response
order: order that response vector options were presented
angle: dot lattice rotation angle (from sequence file)
aspectRatio: Ratio of $\begin{Vmatrix}AB\end{Vmatrix}$ to $\begin{Vmatrix}AC\end{Vmatrix}$ (from sequence file)
gamma: $\angle{BAC}$ (from sequence file)
lenA: $\begin{Vmatrix}AB\end{Vmatrix}$
angleA: $\angle{BAC}$
lenB: $\begin{Vmatrix}AC\end{Vmatrix}$
angleB: $\angle{ABD}$
lenC: $\begin{Vmatrix}BC\end{Vmatrix}$
angleC: $\angle{ACD}$
lenD: $\begin{Vmatrix}AD\end{Vmatrix}$
angleD: $\angle{BDC}$
breakInterval: number of trials between breaks
practiceTrials: number of practice trials
stimulusDuration: fractional seconds stimulus is displayed
fixationDuration: fractional seconds fixation spot is displayed
maskDuration: fractional seconds mask pattern is displayed
maskFrames: number of frames shown during mask duration
scale: distance betwen points in pixels
dotSize: size of points in pixels
apertureSize: aperature radius in pixels
background: RGBA 4-tuple for background color
foreground: RGBA 4-tuple for foreground color
session: session number
subject: subject number
version: program version
name: program name