SDA 3.5 Documentation for IDL

NAME

IDL - Instrument Documentation Language

DESCRIPTION

Instrument Documentation Language (IDL) is used for describing the content of a CAI instrument. An IDL file is an ASCII file, that describes an instrument using that language. Currently the primary purpose of an IDL file is to serve as input into the extended codebook program XCODEBK in order to produce an Instrument Document (IDOC). However, an IDL file can easily be read by any other program that can interpret IDL descriptions.

A file written in IDL can be created by the QEXTRACT program, which reads CASES instrument files (Q-files) and a file produced by the CASES ‘layout’ program (version 4.3 and higher). However, all or part of an IDL file could also be created with a text editor, or with a program that reads instruments for systems other than CASES.

Note that this document only defines the meaning of each element, and it does not specify that any particular element is required. An IDL file may contain any or all of these elements; that will depend on the application.

CONTENTS OF THIS DOCUMENT

Overview
Syntax of the Specifications
Characteristics of the Instrument as a Whole
Attributes of Each Item
Category Labels or Text
Missing Data Specifications

OVERVIEW

The descriptions in an IDL file are of two types: a description of the instrument as a whole, and a description of each item. The description of the instrument as a whole includes a title for the study, the names of the instrument files, and information on rosters and sections. The description of each item includes its name, an optional long label for the item, the wording of the question (if it is an input item), labels for code categories, missing-data specifications, and many other attributes of the item.

An IDL file must be laid out in various segments, separated by an asterisk (*) in column 1. The first segment is the description of the instrument as a whole. Each subsequent segment describes one item.

SYNTAX OF THE SPECIFICATIONS

The specifications are given in the form "attribute_tag = specification" with the tag placed at the beginning of a line. In general each specification must be contained on the same line as the attribute tag, although some specifications may extend over multiple lines, as noted in the descriptions below.

Attribute tags may be given in either upper or lower case and may be given in any order within each segment. Lines beginning with ‘#’ are treated as comments and are not significant. Blank lines are significant within a block of text, but otherwise they are ignored.

There are no required tags in an IDL file, aside from the name of each item. It is the job of the programs that generate or use the file to enforce requirements or supply default values. The IDL file is simply a means of structuring information that is relevant to documenting instruments.

Specifications Expected After the Attribute Tags

The valid tags are as given below. The expected specification, shown after the equal sign after each tag, has the following meaning:

N: A single number
I: The name of an item in this instrument
W: A single alphanumeric word (without embedded blanks)
WW: One or more alphanumeric words or numbers on a single line
LL: One or more lines of text (up to the next attribute tag)

CHARACTERISTICS OF THE INSTRUMENT AS A WHOLE

title=WW: Title of the study
qfile=num(N),name(W),label(WW): Number and name of the instrument file, and descriptive label for the file
(repeated for each instrument file)
roster=num(N),level(N),parent(N),name(W),label(WW): Number of the roster, nesting level, number of the parent roster, name of the roster, and descriptive label for the roster
(repeated for each roster contained in the instrument)
section=rosternum(N),range(N-N),name(W),label(WW): Number of the roster that this section or roster cycle belongs to, the range of item numbers included in the section, the name of the section, and descriptive label for the section
(repeated for each section contained in the instrument)

Description of internal system data file

(This may not match the actual data file produced after interviewing has been completed.)

reclen=N: Length of each record
records/case=N: Number of records per case
ncases=N: Number of cases

ATTRIBUTES OF EACH ITEM

Basic information about the item

name=I: Name of this item in the instrument
itemnum=N: Number of this item in the instrument
label=WW: Long label for this item
formlabel=WW: Long label for this multi-item form or screen
text=LL: Wording of the question
text.2=LL: Wording of the question in language #2
text.3=LL: Wording of the question in language #3
(Up to 9 languages can be specified in this way.)
catlabels=LL: Category text and labels (see discussion below)
dname=W: Name that should be given to this item for analysis purposes (used especially if the item name is too long for SAS or SPSS)

Location (in internal system data file)

(In CASES these locations are only unique within rosters)

record=N: Number of the record containing this item
column=N: Column location of the left-most character
width=N: Number of columns used by this item

Properties

itype=W

Item type within the instrument, specified as follows

single -- (single item)
form -- (multi-item form or screen)
pform -- (part of a multi-item form)
array -- (array definition)

input=y or n

Whether this is an input item (y) or not (n)

type=numeric or character or nodata

Whether the content of this item is numeric or character data (or no data location at all)

ctype=reference or template

Identifies special types of CASES items used for help screens and displays of item contents

decimals=N

Number of implied decimal places in a numeric field

incodes=WW

List of all codes the item could contain (valid or invalid)

md=WW

List of invalid or missing-data codes and/or ranges of codes
(see examples below)

min=N

Minimum valid code

max=N

Maximum valid code

blank=N

Code into which a blank numeric field should be converted, for purposes of analysis

other=N

Code into which a non-numeric character should be converted, for purposes of analysis

Context within the instrument

qfilenum=N: Number of the module or instrument file containing this item (matches the number defined in the section on characteristics of the instrument as a whole)
rosternum=N: Number of the roster to which this item belongs (matches the number defined in the section on characteristics of the instrument as a whole)
parentform=I: The name of the multi-item form or screen of which the current item is a component.
nextform=I: The name of the next form or screen in the instrument files

Commands executed at this item

pretemplate=LL: Commands to execute before the screen is displayed (or commands executed at this item if it is not an input item)
posttemplate=LL: Commands to execute after the screen has been displayed

Description of logical and instrument flow

The position of each item both within the logical path and within the order of items in the instrument files is summarized by a series of attributes. Note that help screens and templates, which do not have any effect unless they are referred to by some other item, are not included in the description of the logical and instrument flow.

forward=LL

Specification of next items -- both logically and in instrument order:

codevalue(I,W) -- (go to item I, IF the answer to this item is W)
conditional(I,I,I) -- (go to the specified items, IF certain conditions are met)
goto(I) -- (unconditionally go to item I)
error(I) -- (if there is an error, go to item I)
next(I) -- (go to the next item, I, if no other branching is executed)
inext(I) -- (item I is the next item in the instrument -- regardless of whether or not it is on the logical path from the current item)
last -- (this is the last item in the instrument -- there is no next item)

previous=LL

Specification of preceding items -- both logically and in instrument order:

first -- (this is the first item in the instrument; there is no preceding item)
target(I,I,I) -- (this item is the target of goto commands in the specified items)
preceding(I) -- (item I is the preceding item in the instrument, AND it leads directly and logically to the current item
ipreceding(I) -- (item I is the preceding item in the instrument -- regardless of whether or not it precedes this item logically

prevbranch=I

If the current item could only be reached logically from one other item in the instrument, item I is the closest previous item that could be reached in more than one way. In other words, all the items between item I and the current item are on a simple logical path in which one item leads to the next item.

universe=LL

User-supplied description of how this item is reached

flowlabel=LL

User-supplied description of where the instrument goes from this item

Who answered, and to whom or what the item applies

responseunit=WW: Respondent to this item (user-supplied description)
analysisunit=WW: Object or unit of analysis (user-supplied description)

Keywords

keywords=LL: User-supplied keywords or keyword phrases, separated by semicolons

Items that potentially modify the current item

varmodi=LL: Input items that contain a command that modifies the current item
varmodn=LL: Non-input items that contain a command that modifies the current item
overlayi=LL: Input items that share one or more columns with the current item and consequently could affect the content of the current item
overlayn=LL: Non-input items that share one or more columns with the current item and consequently could affect the content of the current item

CATEGORY LABELS OR TEXT

Labels or text assigned to response categories can be of any length. In most cases, the label corresponding to a specific category is the same as the text corresponding to that category. The basic format is to specify pairs of codes and labels as follows:

     catlabels=
       1 Yes
       2 No

If the text corresponding to a category is long, analysis programs will often create a shorter category label; this shorter label would be more appropriate for printing the results of an analysis such as crosstabulation. Depending on the analysis program, the category label might be created by truncating the text to the first 8, 16, or 20 characters. If the label created by truncating the text would be unclear or ambiguous, it is useful to provide your own abbreviated category label. This is done by enclosing the short label in square brackets after the category text. Programs that read the IDL file can then differentiate between the (long) text of a category and the (short) label corresponding to the same category.

     catlabels=
       1 Definitely will vote in the next election     [Def vote]
       2 Probably will vote in the next election       [Prob vote]
       3 Probably will not vote in the next election   [Prob not vote]
       4 Definitely will not vote in the next election [Def not vote]

Category text can extend over more than one line, provided that a backslash (‘\’) is the last character of every line except the last line:

     catlabels=
       1 Definitely will vote\
           in the next election       [Def vote]
       2 Probably will vote\
           in the next election       [Prob vote]
       3 Probably will not\
           vote in the next election  [Prob not vote]
       4 Definitely will not vote\
           in the next election       [Def not vote]
       8 Don’t know
       9 Refused

MISSING DATA SPECIFICATIONS

In numeric variables, it is possible to flag any number of codes or ranges as invalid and to be excluded from analysis. Multiple codes or ranges are separated by a comma or a blank. Some examples are as follows:

MD=8,9: Codes 8 and 9 are missing-data
MD=7-9: Codes 7 through 9 are missing-data
MD=8-*: All numbers 8 and larger are missing-data
MD=*-0: All numbers less than or equal to zero are MD
MD=D,R: The characters ’D’ and ’R’ are missing-data
MD=-1,97-99,D,R: Several missing-data codes

CSM, UC Berkeley
April 12, 2011