SDA 3.5 Documentation for Q4TODDL EXAMPLES


NAME

Q4TODDL EXAMPLES - examples of files produced by Q4TODDL

DESCRIPTION

Some examples of the DDL output produced by Q4TODDL are given below. See the main Q4TODDL document for a discussion of all the program options.

Each of the following examples is given in two parts. First the Q-language input is given. Then the corresponding output produced by Q4TODDL is shown. The first 3 examples are compatible with instruments from CASES versions 3 or 4. The next 5 examples are for CASES version 4 only.

The following examples are included:



1. DEFAULT PROCESSING

1a. Q-Language Input

>ex01<
     Here is a typical Q language item.
     What will Q4TODDL produce?

     (Notice that the first line of the item text is now the
      default long label for the variable.)

         <1>  A usable but not completely descriptive DDL file
         <3>  A complete DDL file without need of improvement

         <8>  Don’t know
         <9>  Refused

     ===>

1b. DDL Output

name =   ex01
label =  Here is a typical Q language item.
column = 6
labels =
            1 A usable but not completely descriptive DDL file
            3 A complete DDL file without need of improvement
            8 Don’t know
            9 Refused
text =
     Here is a typical Q language item.
     What will Q4TODDL produce?

     (Notice that the first line of the item text is now the
      default long label for the variable.)


2. ADDING Q-LANGUAGE EXTENSIONS

2a. Q-Language Input

>ex02<
    This item includes four of the Q-language extensions:

       1. Abbreviated category labels
       2. Long variable label
       3. First missing-data code
       4. Second missing-data code

    These keywords will not appear in the translated
    instruments; they are used only by Q4TODDL.
    The keywords may be placed anywhere within the item.

    Do you think you will put them in your instruments?
         <1>  Probably not               [##[prob not]
         <3>  Always: better to be prepared

         <8>  Have no idea, can’t say    [##[ no idea]
         <9>  Refused

    [##label=An Example of Some Q-language Extensions]
    [##md1=9]  [##md2=8]
    ===>

2b. DDL Output

name =   ex02
label =  An Example of Some Q-language Extensions
column = 7
md1 =    9
md2 =    8
labels =
            1 Probably not [prob not]
            3 Always: better to be prepared
            8 Have no idea, can’t say [ no idea]
            9 Refused
text =
    This item includes four of the Q-language extensions:

       1. Abbreviated category labels
       2. Long variable label
       3. First missing-data code
       4. Second missing-data code

    These keywords will not appear in the translated
    instruments; they are used only by Q4TODDL.
    The keywords may be placed anywhere within the item.

    Do you think you will put them in your instruments?


3. SPECIFYING WHICH TEXT TO COPY

3a. Q-Language Input

>ex03<
    This item illustrates Q4TODDL’s text control keywords.
    By default, Q4TODDL puts into the ‘text=’ DDL segment the
    text between the item name and the first response code.

    If you want the DDL text segment to include selected lines
    of the entire Q-language item, use the ‘bt’ (begin text)
    and ‘et’ (end text) keywords.
    Is it clear how they work?

         <1>  Yes
         <5>  No
         <8>  No idea, can’t say
[##et]
    These two lines will not get copied to the text segment,
    because they come after the ‘et’ command.
[##bt]
    Now begin copying to the text segment again.
    Copying will continue until another ‘et’.
[##et]

     ===>

3b. DDL Output

name =   ex03
label =  This item illustrates Q4TODDL’s text control keywords.
column = 8
labels =
            1 Yes
            5 No
            8 No idea, can’t say
text =
    This item illustrates Q4TODDL’s text control keywords.
    By default, Q4TODDL puts into the ‘text=’ DDL segment the
    text between the item name and the first response code.

    If you want the DDL text segment to include selected lines
    of the entire Q-language item, use the ‘bt’ (begin text)
    and ‘et’ (end text) keywords.
    Is it clear how they work?

         <1>  Yes
         <5>  No
         <8>  No idea, can’t say

    Now begin copying to the text segment again.
    Copying will continue until another ‘et’.

4. CASES VERSION 4 FORM WITH A SINGLE NAMED ITEM

4a. Q-Language Input

>form1<
    This is a form with a single named input field.
    (Single items on a form do not have to be named;
    if they are not, the variable name is just the
    name of the form -- e.g., form1)

    Q4TODDL will treat this item the same as a CASES
    version 3 item:  The template area down to the
    first precode will become the DDL text segment.
    The first line of the text is the default long label.
    Any text to the right of each precode is interpreted
    as the category label.  Notice that the Q-language
    extensions work here too.

    <1> True
    <2> False

    <8> Don’t know                [##md1=8]
    <9> Refused                   [##md2=9]

    @field1

4b. DDL Output

name =   form1@field1
label =  This is a form with a single named input field.
record = 2
column = 4
md1 =    8
md2 =    9
labels =
            1 True
            2 False
            8 Don’t know
            9 Refused
text =
    This is a form with a single named input field.
    (Single items on a form do not have to be named;
    if they are not, the variable name is just the
    name of the form -- e.g., form1)

    Q4TODDL will treat this item the same as a CASES
    version 3 item:  The template area down to the
    first precode will become the DDL text segment.
    The first line of the text is the default long label.
    Any text to the right of each precode is interpreted
    as the category label.  Notice that the Q-language
    extensions work here too.

5. FORM WITH MULTIPLE INPUT FIELDS

5a. Q-Language Input

>form2<
    This is a form with multiple input fields (items).

    The entire form will be preserved as the text segment
    for the first item.  The text for subsequent items
    will contain only that part of the form that has the
    text associated with that particular field.

    The default long label for each item will be the
    first line of the text associated with that field.

    The DDL names for both items on the form are being
    shortened by using the ’dname=’ command.
    [##dname=form2a]

       <1> OK <2> Not OK   @field1

    This is text associated with the second field.
    Do you see where it goes?
    [##dname=form2b]

       <1> Yes <2> No      @field2

5b. DDL Output

*
name =   form2a
label =  This is a form with multiple input fields (items).
record = 2
column = 5
labels =
            1 OK
            2 Not OK
text =
    This is a form with multiple input fields (items).

    The entire form will be preserved as the text segment
    for the first item.  The text for subsequent items
    will contain only that part of the form that has the
    text associated with that particular field.

    The default long label for each item will be the
    first line of the text associated with that field.

    The DDL names for both items on the form are being
    shortened by using the ’dname=’ command.


       <1> OK <2> Not OK   @field1

    This is text associated with the second field.
    Do you see where it goes?


       <1> Yes <2> No      @field2

          (This item ’form2a’ is the first on this form.)

          (The Q name was ’form2@field1’.)
*
name =   form2b
label =  This is text associated with the second field.
record = 2
column = 6
labels =
            1 Yes
            2 No
text =
    This is text associated with the second field.
    Do you see where it goes?



          (See ’form2a’ for full text of this form.)

          (The Q name was ’form2@field2’.)

6. FORM WITH RESPONSE PRECODES IN THE POST-TEMPLATE AREA

6a. Q-Language Input

>form3<
    This is a form with precodes in the post-template area.
    Q4TODDL will look for plain text after each precode;
    if it finds any, it will preserve that textual information
    as category labels.

     (1) Numbers in parentheses are just interpreted as text
         by QT and Q4TODDL.

     (2) Therefore, the actual precodes and any associated
         category text must be located in the post-template.

            @field1

    [@field1] <1> First precode <2> Second precode

6b. DDL Output

name =   form3@field1
label =  This is a form with precodes in the post-template area.
record = 2
column = 7
labels =
            1 First precode
            2 Second precode
text =
    This is a form with precodes in the post-template area.
    Q4TODDL will look for plain text after each precode;
    if it finds any, it will preserve that textual information
    as category labels.

     (1) Numbers in parentheses are just interpreted as text
         by QT and Q4TODDL.

     (2) Therefore, the actual precodes and any associated
         category text must be located in the post-template.

7. FORM WITH NON-INPUT ITEM DEFINED IN POST-TEMPLATE AREA

7a. Q-Language Input


>form4<
    This form has multiple input fields plus a non-input item
    defined in the post-template area.
    As for any non-input item, Q4TODDL will generate DDL for the
    item if it is named in a variable list or if the option to
    process non-input items is in effect.

    This first input field has a mixture of precode locations
    -- some in the template and some in the post-template.

      <1> First template precode <2> Second template precode

    @field1

    The second input field has all its precodes in the post-template.

         (1) This isn’t a real precode
         (2) The real precodes are in the post-template

    @field2

    [@field1] <9> Extra precode defined for field1

    [@field2] <1> First real precode <2> Second real precode

    [@noninp] [allow char 5] Non-input var defined in post template
    [store  in @noninp]


7b. DDL Output

*
name =   form4@field1
label =  This form has multiple input fields plus a non-input item
record = 2
column = 8
labels =
            1 First template precode
            2 Second template precode
            9 Extra precode defined for field1
text =
    This form has multiple input fields plus a non-input item
    defined in the post-template area.
    As for any non-input item, Q4TODDL will generate DDL for the
    item if it is named in a variable list or if the option to
    process non-input items is in effect.

    This first input field has a mixture of precode locations
    -- some in the template and some in the post-template.

      <1> First template precode <2> Second template precode

    @field1

    The second input field has all its precodes in the post-template.

         (1) This isn’t a real precode
         (2) The real precodes are in the post-template

    @field2


          (This item ’form4@field1’ is the first on this form.)
*
name =   form4@field2
label =  The second input field has all its precodes in the post-template.
record = 2
column = 9
labels =
            1 First real precode
            2 Second real precode
text =
    The second input field has all its precodes in the post-template.

         (1) This isn’t a real precode
         (2) The real precodes are in the post-template

    @field2

          (See ’form4@field1’ for full text of this form.)
*
name =   form4@noninp
label =  Non-input var defined in post template
record = 2
column = 10
width =  5
type =   character
text =
  Non-input var defined in post template


8. ARRAY DEFINITION

8a. Q-Language Input

>testarr<
    This is a non-input item containing a two-dimensional array
    of floating point numbers, with one decimal place.
    Q4TODDL will create a variable in the DDL file for each
    element in the array.  The variable name will be formed
    by appending the array subscripts to the array name.
    For example, "testarr_1_2" will be the name of the
    array element testarr(1,2).

    Text is usually saved for non-input items, but we are
    suppressing it by using the ’nt’ command.
    [##nt]

    [allow float 2.1 for 2 by 2]
    [store <1.5> in testarr(<1>,<1>)]
    [store <2.5> in testarr(<1>,<2>)]
    [store <3.5> in testarr(<2>,<1>)]
    [store <4.5> in testarr(<2>,<2>)]

8b. DDL Output

*
name =   testarr_1_1
label =  This is a non-input item containing a two-dimensional array
record = 2
column = 15
width =  2
scale =  1
*
name =   testarr_1_2
label =  This is a non-input item containing a two-dimensional array
record = 2
column = 17
width =  2
scale =  1
*
name =   testarr_2_1
label =  This is a non-input item containing a two-dimensional array
record = 2
column = 19
width =  2
scale =  1
*
name =   testarr_2_2
label =  This is a non-input item containing a two-dimensional array
record = 2
column = 21
width =  2
scale =  1

LAYOUT FILE

The ‘LAYOUT’ file used to generate the examples given above is as follows:

  Item name                Item type  Record   Column   Width   Input
                                      number                    Item?

  CASEID                    integer      1        1      5
  ex01                      integer      1        6      1        y
  ex02                      integer      1        7      1        y
  ex03                      integer      1        8      1        y
  form1@field1              integer      2        4      1        y
  form2@field1              integer      2        5      1        y
  form2@field2              integer      2        6      1        y
  form3@field1              integer      2        7      1        y
  form4@field1              integer      2        8      1        y
  form4@field2              integer      2        9      1        y
  form4@noninp              char         2       10      5
  testarr                   float        2       15      2.1
  array [2 by 2]            float        2       21      2.1

  
(The lines beginning with the item names are sufficient for Q4TODDL.)

OVERALL DATASET DEFINITIONS

The ‘SDEFS’ file used for the preceding examples is as follows:

     path =  .
     title = Demonstration Items for Q4TODDL
     ncases = 100
     records/case = 2
     lrecl = 80
     *
     name =   CASEID
     label =  Case identification number
     record = 1
     column = 1
     width =  5

(This file includes information about the study as a whole, and about the ‘CASEID’ variable.)


CSM, UC Berkeley
April 12, 2011