DmDX help, itemfiles

DMDX Help.

Item Files.

For a discussion on what an item file actually is see the built in Basic Introduction.

Unlike previous versions of Dmastr, by default DMDX does not read pure ASCII text item files, it reads RTF files, Rich Text Files (it can in fact still read pure text files but you sure better not have the Unicode option active). These files contain a large amount of text formatting information, fonts, colors, bold, italic and so on. Converting an existing item file to rich text is as simple as opening the original file in WordPad and saving it as an RTF file and adding the .RTF extension to it's name (you could just keep the .ITM extension, however the operating system then does not know that the file should be interpreted as an RTF file).

There are thousands of different RTF control words and ways to use them, of which DMDX is only going to support a very few. When a control word is not supported an error message will be generated and parsing of the RTF file will stop and the job will not run (unlike previous versions of Dmastr, DMDX will not continue when it encounters an error). Because there are so many RTF control words and programs like Word 2000 continually emit new meaningless control words there is a check box to override the errors that result from them being in the RTF file. Checking this option could possibly cause an item file to display in an unintended fashion because the control word that is being ignored really did actually mean something, however DMDX already supports most of the obvious text formatting that windows itself natively supports so in the vast majority of instances checking this will simply allow an item file to be used that would otherwise get refused. If you find a control word is being used in your RTF file that you think should be supported by DMDX because the display is not what you expect when the "Ignore unknown RTF" check box is checked you are welcome to send to us the RTF file and a description of which control word DMDX does not support and what the feature is that you want supported that is causing that control word to be used and we will consider adding support for it.

The keyword to RTF support in DMDX is minimal, no embedded fonts or bitmaps (at least to date, embedded bitmaps could be useful). Following is a partial list of the control words and the features they implement supported in DMDX to date:

\f	Font number, an index into a table of fonts at the beginning of the RTF file.
\fs	Font size.
\b	Bold.
\i	Italic.
\strike	Strike through.
\cf	Foreground color, an index into a table of colors at the beginning of the RTF file.
\ul	Underline.
\ulnone	Turns off all underlining.
\\ \{ \} \~	The characters \, {, } and a space.
\plain \pard \secd	Reset all attributes.
\'	Control code, used with symbols.
\cgrid	No idea what it does but Word 97 sticks it in all over the place so I just parse it out.
\field \fldinst \fldrslt	Used by Word 97 when you use symbols. DMDX only supports the SYMBOL field, all others are not supported.

There are additional control words that DMDX knows, however like \cgrid, it simply ignores them.

When you have an RTF control word that DMDX is refusing to allow and you can't see a reason for it (a fairly common occurrence with Word) and you don't wish to check the "ignore unknown RTF" check box try retrieving the file in WordPad and saving it and then see if DMDX still refuses the control word -- most times I have seen this work and the file is even then editable with Word without having to re-save it again in WordPad. Mind you, I have gone to some length to make the generic output from Word 97 work, however there always seems to be some little gem that I have yet to see, in Word's case it's more like a chest full of them and they're adding new ones all the time.

If you are using different fonts across frames, (ie, a different font in each frame) then you will have to pay careful attention to getting their base lines to line up (vertically). This is because a given text frame's vertical position is determined by how high that frame is and it's height is dependent on the largest font in that frame. Different fonts in a single frame are automatically lined up, however this code does not look to the previous frame to determine where it's baseline was (and to put such code in would probably lead to some difficult to anticipate side effects). For example the following item segment would display the small font a few pixels below the big font:
"Big font", "small font"
To fix this spaces in the largest font size should be included in all frames to keep the base lines lined up, usually one before the text and one after to keep the horizontal centering correct as well:
"Big font", " small font "
Note that DMDX renders fonts almost twice as large as other programs might render them, see the <DefaultFontSize> documentation.

From Ken's DM and DMTG online manual (http://psy1.psych.arizona.edu/~kforster/dmastr/) (my DMDX specific additions are in Arial):

1. STRUCTURE OF AN ITEM FILE

The broad structure of an item file is as follows:

Parameter line
Instructions to subject
Practice items
Experimental items
Termination line (end-of-experiment message)

Parameter line.

The first line of the item file contains the parameters which control the conditions of the experiment. The following is a brief summary of the parameters. These are discussed more fully in Section 3.

NITM (n) the number of items in the file

MDSP (m) method of display.

DEL (d) the number of ticks delay between pressing the foot switch and presentation of the item.

FD (f) frame duration. This controls the normal duration of a frame in clock ticks. Defaults to 0 if not specified.

TIME LIMIT (t) the time limit for a correct response (in msec).

BLOCKSIZE (s) the size of a block for item-scrambling purposes (see Scrambling).

GROUPING (g) the number of items to be grouped together for scrambling purposes (see Scrambling).

SEED (i) an initial seed for the random number generator used in item-scrambling (see Scrambling).

These parameters must be entered on the first line of the item file, but may be entered in any order. Each parameter value is preceded by the special code-letter (specified above in brackets). Each parameter is terminated by a blank. DMDX adds a number of keyword parameters to this list and can also have the parameter line extended beyond the first line of the item file with extended parameters.

A typical first line of an item file might then look like this (there's a DMDX Hello World example below):

n100 f4 m40 s16

This line specifies that there are 100 items, with a frame duration of 4 ticks, a method of display designated as option 40, and a scramble blocksize of 16.

Items.

Then follow the instructions, the practice items, and the test items. For checking purposes, each item or instruction should be followed by a carriage return, but this is not essential (although the carriage return after the parameter line is essential).

Termination line.

The final item in the file should be an instruction informing the subject that the experiment is finished. This should contain a marker (L) indicating that this is the end of the file.

ITEM STRUCTURE

An item consists of a sequence of frames. The total length of an item in DM may not exceed 500 characters (including the item number and special characters), it's pretty much unlimited in DMDX. The end of the item, or sequence, is marked by the symbol ";".

The sequence is divided up into any number of frames, the boundary of a frame being marked by "/". DMASTR displays the sequence one frame at a time, with the frame automatically centered in the screen. Frames can de displayed on any one of four different lines. As each frame is displayed, any characters on the same line as this frame are normally erased before the new frame is displayed. There is no gap in time between the erasure of the previous characters and the display of the new characters, since the erasure occurs in between successive sweeps of the raster.

Each frame contains text characters, and display-control switches. The text characters are enclosed in double quotation marks. These are the characters actually displayed to the subject. All characters not so enclosed are treated as display-control switches. For example:

B"DOG"/C"HOUSE"//"WATCH"/;

consists of 5 frames. This sequence displays first the word DOG, then HOUSE superimposed on it, then a blank frame, then WATCH. The first frame contains the display-control switch B, and the second contains the display-control switch C (the functions of these characters is explained in sect. 3.3). The final frame (/;) serves merely to erase WATCH, and hence is termed the erase frame. If the final / was omitted, then WATCH would remain on the screen.

ELEMENTS OF AN ITEM

Correct response indicator (CR).

This symbol informs DM what the correct response to this item is. There are four possibilities:

+ refers to positive responses such as Yes, Same, True, Grammatical, etc.

A response will be treated as correct if the positive button is pressed.

- refers to negative responses such as No, Different, False, Ungrammatical, etc.

A response will be treated as correct if the negative button is pressed.

^ no response at all should be made.

= either positive or negative responses are correct

The CR indicator may be omitted under certain circumstances: e.g., if the subject is not expected to make any timed response (e.g., if the item displayed is an instruction, or if the subject is to make a written identification response), or if the display is a response-contingent display (i.e., the next frame in the sequence is not displayed until the subject makes a response), in which case, the CR indicator is located in the appropriate frame.

Note: If the CR indicator is equal to "!", the entire item is ignored by DMDX, which permits items to be used as comments lines. Note that those comments still need to be terminated in a semi-colon, the comment is not a line by line operator but is instead a literal item so the following would be interpreted as one comment item and would not gather an RT:

! an item comment
+1 "item" *;

Whereas the following will be interpreted as two items and gather an RT:

! an item comment;
+1 "item" *;

Item number (ITMID).

This gives the item number, which will serve to identify the item when the data are retrieved from the data file. If two items have the same item number, then the data from the item presented second will replace the first when using DM's original .DTP data file format, however no one uses this format any more and instead use .AZK or .ZIL files where any number of occurrences of an item can occur.

The DM item number must be less than 512 (DMDX item numbers can be up to 2.1 billion or so, 2^31), and must be terminated by a blank space. Note that the sign before the item number (indicating the correct response) does not change the value of the item number. That is, +25 is the same as -25 as far as the item number is concerned. Each item should have a different number.

If the ITMID is zero, the sequence is treated as an instruction to the subject rather than as an item (the key characteristic of an instruction being that if continuous running has been specified where items no longer wait for a request after each response an instruction will continue to do so).

Practice items may have their own numbers, or identical numbers (if two items have the same number, then the response to only the most recently presented item will be stored).

Text characters.

The characters displayed on the screen. These must be preceded and terminated by quotation marks.

e.g., "This appears on the screen" but this doesn't;

The only characters that are not permitted are the double quotation marks themselves, and the item terminator (";"). While there are in fact ways of displaying these characters originally they involved editing your RTF item file with a text editor and adding RTF escape codes for them (\'3b for a semicolon and \'22 for a double quote) however the second you open the file in an actual RTF editor they'll revert to the normal values undoing your editing. If you do pursue such a path I recommend using WordPad's output for editing as it's much easier to read than Word's. Alternatively (and much more realistically) if you care to turn the Unicode code path on there are all sorts of alternate characters like the full width semicolon U+FF1B and the full width double quote U+FF02 found in Asian fonts that DMDX doesn't parse as delimiters and that you can actually manipulate with an RTF editor (although I notice that my version of WordPad just replaced mine with double byte code page characters (\'a3\'bb for the semicolon and \'a3\'a2 for the double quote) from the SimSun font so Unicode would appear to not be required). You could also use <sprintf> with the %c character format specifier to get semicolons and double quotes into a frame's text.

Display-control characters.

These signal special action for the current frame (e.g., reading the clock, changing to a new line). These are defined here and DMDX keywords here.

Frame delimiters (/ or , or : for NVIDIA 3D shutter glasses).

This marks the boundary of each frame. For example:

"each" / "word" / "in" / "a" @1 , "separate" @2 , "frame" @3

The slash is used to separate frames in a timewise fashion (determined by the default frame duration), the comma to separate them spacewise ("a" @1 , "separate" @2 , "frame" @3 is displayed simultaneously on three lines). Note that display durations in comma separated sequences of frames have to be specified in the last frame of the sequence as a comma is exactly equivalent to %0 / ! so the %0 overrides any earlier specification. Many different switches and keywords can occur in frames.

Item delimiter (;).

Every item and every instruction must be terminated by this character.

The following is a typical example of a complete item:

+004 "The" / "boy" / "went" / * "HOME" / ;

This displays each word for the time specified in FD in the center of the viewing area. The subject is intended to respond to the item in upper-case letters, hence the display-control character * (the clock-on symbol) is located in this frame. The reaction time would be stored and labeled as the RT for item 4. The correct response is a positive response (indicated by the + at the beginning).

Hello World Example.

The classic method of introducing a programming language is to detail how to display "Hello World" so I'll do so for DMDX. DMDX's item file must contain a few bare minimum things before DMDX can do anything. It needs a parameter line with a video mode and a default frame duration:

The frame duration is specified in ticks, a tick being a single raster interval or display refresh, usually 1/60th of a second. The video mode here is a special video mode that is what the Windows is currently using for the desktop. It will need to have been timed in TimeDX (unless you have to be using the EZ mode of DMDX).

Next the item to display "Hello World" will need an item number and a text segment that it will display. We'll use item number zero as that's an instruction (because we don't want to gather a response):

0 "Hello World";

If we wanted to display Hello then World 30 ticks apart (because the default frame duration has been set to 30 and most displays these days tend to be 60 Hz displays) we'd separate the text into two frames with a / frame delimiter:

0 "Hello" / "World";

If we wanted to display World below Hello we'd use the comma frame delimiter that merges frames together and the <line> keyword to put World on the next line (the default being line zero in the middle of the display):

0 "Hello" , <Line 1> "World";

Returning to the earlier example if we wanted to gather a response as World is displayed we'd put a clock on symbol in that frame, we'd also use an item number other than zero because it's no longer an instruction and we'd also have to include a correct response indicator:

+1 "Hello" / "World" * ;

More complex examples.

There is a general introduction followed by a number of increasingly complex examples in DMDX's built-in Introduction, either run DMDX and hit it's introduction button or you can examine the text of it here. Ken's examples page is included here in case that one ever goes away. There are dozens of other much more complex examples interspersed throughout these pages such as the dynamic item content page, the Probabilistic Selection Task Example and the macro definition page among others.

DMDX Index.