Digram-Balanced Latin Square Stimulus Presentations

copyright c 1996 Robert Ellis

Digram-Balanced Latin-Square Designs
	Digram-balanced Latin squares are often used as a counterbalancing technique in repeated-measures designs. Digram-balanced Latin squares must satisfy 2 distinct criteria. To qualify as a Latin square, the stimulus (level, treatment, etc.) must appear only once in each row and be in a different column (order) for each row (subject) of the Latin square. To qualify as digram balanced, a Latin square must be ordered such that, throughout the square, each stimulus is directly preceded and followed by all other stimuli exactly once.
	These criteria can be met for even numbers of stimuli  and such designs can be run provided the number of subjects utilized by an experiment of this design equals an integer multiple (including 1) of the number of stimuli. Thus, if an experiment has 12 stimuli, the fewest number of subjects is 12 and any additional subjects must be added in sets of 12. If the number of subjects varies from this restriction, the counterbalancing this design affords is lost. 
	However, when the number of stimuli is odd, these criteria can only be met across 2 Latin squares. Note that here the criteria are 'stretched' a little in that, across both squares, each stimulus is in each column twice and is proceeded and followed by each other stimulus twice. Since two Latin squares are required to achieve the required balance, it follows that, for an odd number of stimuli, the number of subjects utilized by an experiment of this design equals an integer multiple (including 1) of the number of stimuli X 2. Thus, if an experiment has 11 stimuli, the fewest number of subjects allowed under this design is 22, and any additional subjects must be added in sets of 22. Again, if the number of subjects varies from this restriction, the counterbalancing this design affords is lost.
	Note that for any Latin square, the stimuli must be randomly assigned to the designations (columns) specifying the square, and the subjects must be randomly assigned to the particular sequences (rows or lines).  

The Program 
	Digram Balanced Latin-Square Stimulus Presentations (DBSP.EXE) was written in Turbo Pascal Version 7.0. DBSP is designed to run in a DOS environment but it seems to run fine under Windows 3.1 (see helpful hint 4 for details). An icon file (DBSP.ICO) is included for this purpose. The program itself is quite crash-proof and does extensive error checking (range, type etc.) on the values the user inputs. Throughout the program, the user is afforded the opportunity to quit. (See bottom right of screen when program is running to determine how). Although the above is true, USE THIS PROGRAM AT YOUR OWN RISK!

	Digram-Balanced Latin-Square Stimulus Presentations is a data collection program designed to facilitate presentations of a stimulus set (up to 85 stimuli) which after collapsing across subjects will be a digram-balanced Latin-square design. It requires the input of either real, integer or string characters after each presentation. The user must create 2  ASCII files prior to running this program. One must be created with DBG.EXE described below and the other must contain the names of the stimuli in it (see below for details). The lines of both of these files must be randomized once with the program LINERAND.EXE before beginning the experiment. When DBSP is run, it prompts the user for the relevant input operating parameters (see Input Information section for details) and, on completion, produces an output data file (see Output File for details).

Stimuli File

	Prior to running DBSP.EXE you must create a file containing the names or numbers of your stimuli. Note that, in the creation of the stimuli file (use any ASCII editor), the user has only a field of the first 19 characters of each line to use (DBSP.EXE will not read any characters from column 20 and beyond). Furthermore, DBSP.EXE will only read the first 170 lines of the stimulus file. However, the field of 19 characters can be split into different subfields. For example, in a recent experiment investigating roughness discrimination, I had stimuli differing in average interdot spacing (the distance between raised dots). If we look at only four of these stimuli, the spacing may have been 2, 2.125, 2.25 2.375 mm. However, for simplicity of presentation, rather than having to discriminate between such similar dimensions, I simply labeled the stimuli 1, 2, 3, 4. Therefore, I made the stimuli file as follows:

     2.000   1
     2.125   2
     2.250   3
     2.375   4  

Several points are worth noting here:

A/ The reason I included the interdot spacing measure was so that the output data file would contain a record of the actual stimulus dimension of interest. Several months (years) from now, it's a pretty fair bet that stimulus 3 would have no meaning to me without the interdot spacing measure of 2.250 mm to go with it. 

B/ For ease of opening the output data file with a spreadsheet package (e.g., Excel), it is worth keeping the main field (and any subfields the same width). For example, if I were presenting four colours, I would denote them as follows:

red...
blue..
green. 
yellow         	

	Also, if there were between 10 and 99 stimuli, and I were coding the stimuli with numbers, I would call the first nine 01 - 09 not 1 - 9. Similarly, if there were over 100 stimuli, and I were coding them with numbers, I would label the first ninety-nine 001 - 099 not 1 - 99.

C/ If possible separate your subfields with more than one space. While not strictly necessary, it may be easier for a spreadsheet to split your output data file into appropriate columns. Note that in the above example, I provided three spaces between each stimulus's interdot spacing and each stimulus's number. 

D/ For optimal screen presentation, center the number of characters you use in your stimuli file evenly over the 19 characters you are allowed. This is strictly a cosmetic consideration. Note that in the above example there are five spaces before the first interdot spacing character and the stimulus number is character 14 of the line so there are effectively five blank spaces after it.


Digram-Balanced Latin-Square File

	This is a file generated by DBG.EXE. When run, this program prompts the user for the number of stimuli (max. # = 85) and the name of the output file. If the number of stimuli is even, it generates an ASCII file containing a digram-balance Latin square. The structure of this file is such that each line contains a unique ordering of the stimuli. Across lines (# of lines = # of stimuli), the ordering forms a digram-balanced Latin square. That is, each stimulus (level, treatment, etc.) appears once in each line and across lines, each stimulus is in a different column and each stimulus is directly preceded and followed by all other stimuli exactly once.
	If the number of stimuli is odd, 2 Latin squares are generated. The structure of this file is such that there are 2 lines sharing an ordering of the stimuli. Across lines (# of lines = # of stimuli X 2) both Latin squares together are digram balanced. That is, each stimulus appears once in each line and, across lines, each stimulus is in each column twice and is proceeded and followed by each other stimulus twice. 


Line Randomization

	As mentioned previously, for any Latin square, the stimuli must be randomly assigned to the designations (columns) specifying the square, and the subjects must be randomly assigned to the particular sequences (lines). This can be easily done by running RANDLINE.EXE twice. Once specifying the user created stimuli file (see above) and once specifying the file generated by DBG.EXE (see above). Note that this is done only once per experiment. The user defined output files generated by LINERAND.EXE are the files to be named in the input information below.

Input Information Required By DBSP.EXE

1. Name (and Path) of File containing Stimuli Names? 

	Here, the program requires the name (and path if in a different directory than DBSP.EXE is being run from) of the randomized stimulus file alluded to above. It will not proceed until it gets this file, although, it will allow you to exit.

2. Name (and Path) of File containing Digram Square? 

	Here, the program requires the name (and path if in a different directory than DBSP.EXE is being run from) of the randomized version of the digram-balanced Latin-square that DBG.EXE generated. It will not proceed until it gets this file, although, it will allow you to exit.

3. What line of the Digram Square is to be used?

	Because the Digram Square has been randomized, the user should simply consecutively increase this number for each subject. That is, the user would input 1 for the first subject run in the experiment and 2 for the second subject etc. It is critical that the experimenter keep track of what number the current subject is when answering this question. Remember that, if the number of stimuli is even, the number of subjects must equal an integer multiple of the number of stimuli. Alternatively, if the number of stimuli is odd, the number of subjects must equal an integer multiple of the number of stimuli X 2.

4. Name of Output File for Data (Include Path)?

	Here, the user must specify the path (if you want it in a different directory from the one DBSP.EXE is in) and a filename for the data this program will generate. Personally, I like to end the data filenames with a .dat extension. If the file already exists, the program will warn you and allow you to either open it anyway, rename your data file, or exit the program. Be aware that choosing to open it anyway will erase the existing contents of that file. The eventual contents of this file are discussed under the heading 'Output File' below.

5. Do you want your Data to be Type Real, Integer or String?

	The user must choose from the above data types or exit.
If type Real is chosen, the user will be prompted for the lowest and highest real numbers allowed. Both of these numbers must be within the range of -99999.9999 and +99999.9999. I suggest you allow only the smallest range possible. For example, if you don't allow negative numbers, set the lowest allowable to zero. If you have an upper limit, use it. The advantage of setting the range as tightly as possible is that the program will check your input for a keyboard entry error. As an example, I often collect absolute magnitude estimates. It's been my experience that such estimates rarely (never?) exceed 999. According, I set my lowest and highest allowable numbers at .0001 and 999, respectively. Thus, if I happen to enter 1000 instead of 100, or 0 instead of 10, the program requires me to re-enter the data. If I were to get a response higher than 999, I would simply write the name of the stimulus presented, the repetition number and the response of the subject on a slip of paper. I would then enter an allowable number into the computer (e.g., 999) and proceed with the experiment. Upon completion of the experiment, I would open the data file, go to the appropriate line of data, and change the recorded response of 999 to whatever value it should have been. 
	
	If type Integer is chosen, the user will be prompted for the lowest and highest integer allowed. Both of these numbers must be between -32768 and +32767. Again, to minimize the possibility of a keyboard entry error, I suggest you allow as small a range as possible.
	
	If type String is chosen, the user is afforded 19 characters to write any response whatsoever. Again, this datafield can split into separate columns (see Stimulus File section above for a detailed explanation). Type string input is obviously not range checked.

6. Subject ID?

	The user has a field of 19 characters to provide subject identification information. Again, this 19 character field can be split into several subfields if desired (see Stimulus File section above for a detailed explanation). For example, in my research, I typically record the subject number, the sex of the subject, the age of the subject, and the handedness of the subject. Further, if I were running a between groups experiment (e.g., active and passive touch), this would be an ideal location for the group designation. Accordingly, if the first subject of my experiment were female, aged 19, left handed and assigned to the active touch group, I would enter the Subject ID as follows:

s01  F  19  L  act

	Note here that all subfields should be the same width. Since I designated the first subject s01, I can run up to 99 subjects without going into the 4th character column. If I thought I were going to run 100 or more subjects, I would have designated the first subject s001. Also, for the subjects in the passive touch group, I would enter pas rather than act - again, keeping the data field the same width. Further, note that I had the room to allow two spaces between all subfields. This, and the same field widths should allow spreadsheets to easily open and convert the data file to the appropriate format. 

7. Response?
	
	The user must type in the response of the subject. It must conform to the parameters established for the chosen data type (see 4. above). Note that Ctrl-Break will exit the program anytime during the collection of responses, BUT ALL DATA COLLECTED UP UNTIL THAT POINT WILL LIKELY BE LOST.
     	


Output File
	
	On completion of the program, the generated data file will consist of 4 columns of data (unless you designated subfields - see above) with 1 row of data corresponding to each stimulus presentation and subsequent subject response. (# of rows = # of stimuli. The columns represent:
    
Column 1
	characters 1 - 19, Subject ID - a string of up to 19 		user specified characters - this will be split into 	several columns by a spreadsheet program if subfields 	were used in the input.

Column 2
     characters 21 - 23, Presentation Order - the order in 	which the stimulus was picked by the program	and 	subsequently presented to the subject. This order is 	specified by the line number of the randomized digram 	square inputted by the user.

Column 3 
	characters 25-43, Stimulus Name (name of the presented 	stimulus as read from the randomized stimulus file 	created by the	user prior to running DBSP.EXE).

Column 4 
	characters 45-63, Subject's Response (user defined as 	to type and range). Real numbers are written to 4 	decimal places.

	Note here that, because the output file is limited to a width of 63 characters, it can be efficiently printed out by the Windows notepad accessory.

An Example
     You wish to present 12 different stimuli in a digram- balanced Latin-square order to 12 subjects (because the number of stimuli is even the number of subjects must be an integer multiple of the number of stimuli). Using any ASCII editor, create a data file (call it as stim) with the names of the 12 stimuli (remember, one line per stimulus, 19 characters maximum length). Start DBG.EXE and generate a digram-balanced Latin-square for 12 stimuli (call it digr12). Start LINERAND.EXE and randomize stim to stimr. Start LINERAND.EXE and randomize digr12 to digr12r (It might be smart to remove the files stim and digr12 from the directory to avoid an input error - see Helpful Hint 1). These files are now properly structured to run the experiment. DO NOT RUN LINERAND.EXE AGAIN FOR THIS EXPERIMENT. Start DBSP.EXE and answer the prompts as follows:
     
      Input File?         : stimr
      Digram Square File? : digr12r
      Line #              : 1
      Output File         : subj01.dat
      Response Type?      : R
      Lowest Allowed?     : .0001
      Highest Allowed?    : 999     
      Subject ID?         : S01 (max. of 19 chars. of input)

	The program will present the first stimulus name specified by line #1 of digr12r. You present the appropriate stimulus to the subject and input an allowable response. In this particular case, it must be a real number in the specified range (.0001 - 999). The program will then present the 2nd stimulus name specified by line #1 of digr12r and waits for the next response (note that the program keeps you informed as to how many stimuli you have presented). This continues until the program presents all the stimuli names in the order specified by the relevant line number of the digram square file. It then prompts you to "Hit Any Key To Exit". Exit the program and you can now open subj01.dat with any text editor. 
	Start DBSP.EXE (again, do not run linerand) and repeat the response steps for subjects 2 - 12, but change the input of the line number to match the subject number (2 - 12, respectively) and name the data files subj02.dat .. subj12.dat, respectively. The data files can be joined with a DOS copy command or imported 'as is' into a program like EXCEL for data manipulation (sorting, changing rows to columns, analysis, etc.).


Helpful Hints:

1. To avoid the chance inputting the unrandomized versions of both the stimulus file and the digram square file remove the unrandomized versions of these files from the directory from which DBSP.EXE is being run.
  
2. Remember, data files are precious. ALWAYS, ALWAYS, ALWAYS, back them up on a physically different disk from where they are initially stored. Be aware that a single physical hard drive may be partitioned into several virtual hard drives. Therefore, backing files up from C: to D: or E:, etc. may not actually put your files on a physically different hard disk. If in doubt about the configuration of the hard drive, back your data up on floppies. This will keep them safe from drive crashes, accidental erasures, viruses etc.. This is most definitely experience talking. Learn from my mistakes.

3. When naming both the data files and the subject ID keep the number of characters the same across subjects or you may face some sorting problems. For instance, if you are running 10 - 99 subjects, call subject 1's data file subj01.dat and the ID s01 not subj1.dat and s1. Similarly, if > 99 subjects are run, use subj001.dat & s001 respectively.
	Furthermore, when naming the data files it may be helpful to give them all the same extension (i.e. .dat). Also, you should ensure that there are no other .dat files in the directory where these are stored. Then, all the files can be joined in one file (e.g. alldata). This is most easily accomplished if the new file has a different extension (or none) than the individual files. This will not erase the original .dat files. The DOS command is:

                     copy *.dat alldata

If the .dat extension is wanted on the new file use the DOS rename command as follows:

                     ren alldata all.dat

The new file is now called all.dat.

	It's not clear (to me at least) what order DOS will use when joining the .dat files. I suspect it copies the first .dat file listed in the directory to alldata and then adds to the end of it the 2nd .dat file listed etc.. If this is true, it might be worth sorting the directory with Norton or some other utility program prior to performing the above copy command. With Norton, the command DS EN should do the job. In any event, if the alldata file doesn't have the subject's ID in the appropriate order you can always sort it. Sorting by Subject ID and Presentation Order (columns 1  & 2) should put it in the same arrangement as the original subj.dat files.

4. Personally, I find it convenient to use DBSP.EXE through Windows 3.1. Here's how I do it. First, I create a new directory specifically for LINERAND.EXE, LINERAND.ICO, DBG.EXE and DBG.ICO. I then create new program items in one of my Windows program groups and fill in the description, command line, working directory and change icon dialogue boxes appropriate to the directory LINERAND.EXE, LINERAND.ICO, DBG.ICO and DBG.EXE are in. It is particularly important to fill in the working directory box because, if this is done, no path descriptions have to be given while running LINERAND and DBG. I use this directory to create and subsequently randomize both the stimuli file and the digram square file.
	Second, I create a new directory specifically for the data of the experiment I am going to run. Into this directory, I either copy or move DBSP.EXE, DBSP.ICO, the appropriate randomized digram square file, and the appropriate randomized stimulus file. I then create a new program item in one of my program groups and fill in the description, command line, working directory and change icon dialogue boxes appropriate to the directory DBSP.EXE and DBSP.ICO are in. Again, fill in the working directory box because, if this is done, no path descriptions have to be given while running DBSP. DBSP will read both the stimulus file and the digram square file from, and store all output data files, into the directory specified in the working directory dialogue box. On completion of the program, the output data file can be easily viewed and printed from the Windows accessory Notepad.   



1





