4: Basic Tables – Enghouse Insights (Powered by Survox) Documentation

[toc]

INTRODUCTION

This chapter describes how to create basic tables after you have collected and cleaned your data. It covers information on using simple table options. Chapters 5 and 6 provide more detailed information on how to use intermediate and advanced table functions.

The end of this chapter provides a section on E-Tabs. For more informaton, go to USING E-TABS.

4.1 PARTS OF A TABLE

Table is short for cross-tabulation. A table is a rectangular arrangement of columns and rows with values in the intersecting cells. Tables can be simple crosstabulations of one variable against another, or can be complicated and include expressions that join several variables together and include statistical calculations.

Tables generally consist of a header, title, banner, stub, footer, and the “Total” and “No Answer” rows and/or columns. These elements are defined in the following section.

Header: Optional text that appears on the top of the page on all tables. By convention, it is the name of the study.

Title: The survey question text.

Banner: The headings of each of the columns in the table. These headings are referred to as “banner points.” In the simplest table, the banner could be only one column labeled “Total.” Usually, banners consist of several column headings. By convention, banner points are demographics (for example, age or income) or some other characteristic that distinguish groups of people that answer a survey question.

Stubs: The labels for each of the rows in the table. By convention, stubs are the responses to the question in the survey.

Total: The “Total” row/column is the number of respondents to the survey. No Answer: The “No Answer” row is the number of respondents that did not answer this particular question.

Footer: An optional text line at the bottom of the table.

Following is a typical table with the table elements labeled.

ROADRUNNER’S PIZZA SURVEY <–Header

TABLE 001

Q1. How much do you agree with the following statement: <–Title

The fast food at Road Runners is worth what I pay for it.

<——–AGE——–> <—–INCOME——-> <–Banner

Under Over Under $15- Over

TOTAL 35 35-54 54 $15k $35k $35k

—– —– —– —- —– —– —-

Total 500 141 140 143 74 148 215 <–Total Row

100% 28% 28% 29% 15% 30% 43%

100% 100% 100% 100% 100% 100% 100%

No Answer 75 29 18 22 16 18 29 <–No Answer Row

100% 39% 24% 29% 21% 24% 39%

15% 21% 13% 15% 22% 12% 13%

(5) Completely agree 88 21 29 23 10 30 36 <–Stubs

100% 24% 33% 26% 11% 34% 41%

18% 15% 21% 16% 14% 20% 17%

(4) Somewhat agree 92 26 27 27 14 30 35

100% 28% 29% 29% 15% 33% 38%

18% 18% 19% 19% 19% 20% 16%

(3) Neither agree 86 23 26 24 13 22 45

nor disagree 100% 27% 30% 28% 15% 26% 52%

17% 16% 19% 17% 18% 15% 21%

(2) Somewhat disagree 73 13 23 21 13 21 33

100% 18% 32% 29% 18% 29% 45%

15% 9% 16% 15% 18% 14% 15%

(1) Completely disagree 86 29 17 26 8 27 37

100% 34% 20% 30% 9% 31% 43%

17% 21% 12% 18% 11% 18% 17%

Tables prepared by Computers for Marketing Corp. <–Footer

Page 1

4.2 TABLE BUILDING BASICS

In order to create a table, you must define table elements, identify where to get data from, and issue commands to build and print the table. These instructions are contained in a specification file (with the extension of spx). The main commands are:

~DEFINE tells Mentor what information you want in the table and how you want it formatted.

~INPUT tells Mentor what it needs to know about the data file.

~EXECUTE gives Mentor the commands to build and print the table.

As you can see, these Mentor commands are preceded by a tilde (~). Most tilde commands start command blocks; that is, once the tilde command is given, the commands following it are specific to that block.

If you have CfMC’s Survent software, much of the table specification work may have already been done for you. For further information, see 4.12 USING Survent TO GENERATE Mentor SPECIFICATION FILES.

Here is a specification file to build a simple table.

~DEFINE

TABLE_SET={example:

COLUMN=: Total

ROW=: [1^1/2]

TABLE=*

}

~INPUT $

~EXECUTE

TABLE_SET=example

~END

Here is the same spec file with each line explained.

~DEFINE <–start the DEFINE block

TABLE_SET={example: <–name a set of table elements “example”

COLUMN=: Total <–set up a column that consists of the total number of respondents

ROW=: [1^1/2] <–set up two rows from answers one and two

TABLE=* <–save table information in memory

} <–end the DEFINE block

~INPUT $ <–$ use a phantom file (with one dummy case) as input

~EXECUTE <–start the EXECUTE block

TABLE_SET=example <–build the table with the elements defined in table set “example”

~END <–exit Mentor

If you put these specifications into a file and execute them (Mentor file.spx -output.lfl), you can look at the output file to see Mentor has built a small table that looks like this:

TABLE 001

BANNER: TOTAL

STUB: example_r[1]

Total N/A TOTAL

Total 1 – 1

100.0% 100.0%

N/A 1 – 1

100.0% 100.0%

1^1 – – –

1^2 – – –

There are two columns labeled “Total” because by default, Mentor includes a system generated Total column. Tables also have by default a Total row, a N/A (No Answer) row, and a N/A (No Answer) column. You can use the ~DEFINE EDIT keyword to remove these system generated Total columns and change things like column width. This is explained in detail in 4.3.2 Changing Table Element Defaults (The DEFINE EDIT Statement).

4.3 DEFINING TABLE ELEMENTS

You can use DEFINE to define each element of a table and then call each element separately in the EXECUTE block. Or, you can use the TABLE_SET keyword to define major elements of a table as a group and then call the group of table elements with one EXECUTE statement.

TABLE_SET is the basic building block for creating tables. Once an item is defined or turned on, it stays in effect until it is redefined or turned off. This allows you to define table elements globally in one TABLE_SET, and then only define what needs to change for each particular table in subsequent TABLE_SETs. Typically, you will use one TABLE_SET to define the banner text, the column variable, and table printing options which will be used across all of the tables in your study, and one TABLE_SET for each question in the study, which includes the title, stubs, and row variables.

Let’s use the same specification file as before, but this time define the banner once for two tables in a banner table set. Since the TABLE_SET definition for the banner only defines part of a table, it does not need a TABLE= command. We are also adding the >PRINTFILE command to send the tables to a separate file (see 4.5 META COMMANDS). If you are trying these specs, look for the final tables in the file called “mytables.prt”.

>PRINTFILE mytables

~DEFINE

TABLE_SET={one:

HEADER=: These Are My Tables }

BANNER=:

| Total Male Female

| —– —- —— }

COLUMN=: Total WITH [2^1] WITH [2^2]

}

TABLE_SET={two:

TITLE={:

How much do you like building tables? }

STUB={:

3-Very Much

2-Somewhat

1-Not Much

9-Don’t Know }

ROW=: [12^3/2/1/9]

TABLE=*

}

TABLE_SET={three:

TITLE={:

How much do you like Roadrunner’s Pizza? }

STUB={:

3-Very Much

2-Somewhat

1-Not Much

9-Don’t Know }

ROW=: [13^3/2/1/9]

TABLE=*

}

~INPUT $

~EXECUTE

TABLE_SET=one

TABLE_SET=two

TABLE_SET=three

~END

If you run these specifications and look at the tables, you will see the column headings (these are called banner points) do not line up exactly over the numbers in the columns. You can learn how to correct this in 4.8 FORMATTING BANNER TEXT.

Note: Using “|” before each line of the Banner text will keep the formatting intact. For example, “| Total” will print as ” Total”, while “Total” will print as “Total”, without the leading spaces.

You can also use TABLE_SETs to do a global screening of the data, such as filters, bases, or weights. By convention, that tabset is named global. You can also include additional rows by adding a stub prefix or stub suffix. Examples of banner table sets will follow. If you have more than one banner, you can create a separate TABLE_SET that will have definitions for the elements that will be the same in all the tables, such as headers and footers. (See 5.4 Printing Multiple Banners For Each Table Row for an example of printing all the tables by more than one banner.)

Items that are defined in a TABLE_SET stay in effect for the following tables until they are turned off or redefined, or unless you use one of the ~SET DROP keywords that instruct Mentor to only use an element once and then discard it. See 4.3.3 Changing Table Processing Defaults (The SET Statement) for a complete list of the ~SET DROP keywords.

4.3.1 Assigning Variable Names

Mentor allows you to assign a name to any table element: a row, a banner, or an entire table set. You can then refer to the table element (or group of elements) by just using the name. This means you can use a table element exactly as before (such as a stub label set), or the same as before with minor modifications.

Here is the syntax for the TABLE_SET command, as you can see, you can assign variables to individual table elements, the entire tabset, or both.

TABLE_SET={varname=oldname:

KEYWORD=varname: definition

}

TABLE_SET The keyword that tells ~DEFINE that a table set definition follows. It can be abbreviated

TABSET.

{ Marks the beginning of the TABLE_SET definition; is optional.

varname Assigns a name to the TABLE_SET. The name can be 1-14 characters long, and can include

periods or underscores. The maximum recommended length is 10 characters, because Mentor will

use this name and add extensions to it to create table element names automatically. See

“Default Varname Generation” for details.

=oldname Optional, means use the table elements from a previously defined table set and add any new

elements in this table set.

KEYWORD= Commands for defining table elements (such as TITLE, HEADER, STUB, or ROW). These elements

stay in effect until they are redefined or turned off. You can turn off keywords by using a

minus sign in front of it, for example, – HEADER. All of the table element keywords are

listed and described in Mentor, Appendix B, ~EXECUTE.

varname Refers to an existing variable or assigns a variable name to the keyword (this overrides

Mentor’s default variable names). The colon is required to assign a variable name, for

example, “HEADER=mainhead” refers to the previously defined variable mainhead, while

“HEADER=mainhead:” assigns the name mainhead to the heading which is about to be defined.

definition The definition of the keyword, such as table text or information about the data to be

printed in the table cells. Keywords that define table text (such as BANNER and FOOTER)

and GLOBAL_EDIT, EDIT and LOCAL_EDIT require a closing brace(}) to end the keyword

definition. Keywords that describe data (such as COLUMN, ROW, and STUB) do not require a

closing brace (}).

} Ends the TABLE_SET definition.

Keywords do not need to be in any particular order, but a table set can contain only one occurrence of a keyword. For example, you cannot assign a HEADER and then turn it off with -HEADER in the same table set. Variables can be assigned outside the TABLE_SET block, but then you must instruct Mentor to make it a part of the table in the ~EXECUTE block.

So, for the previous example, instead of repeating the stub definition in the third tabset (TABLE_SET=three), you could have assigned a variable to the stub (STUB=mystub:) when you first defined it, and then use the variable name in the third tabset with the command STUB=mystub.

~DEFINE TABLE_SET={two:

TITLE={:

How much do you like building tables? }

STUB={mystub:

3-Very Much

2-Somewhat

1-Not Much

9-Don’t Know }

ROW=: [12^3/2/1/9]

TABLE=*

}

TABLE_SET={three:

TITLE={:

How much do you like Roadrunner’s Pizza? }

STUB=mystub

ROW=: [13^3/2/1/9]

TABLE=*

}

Remember, if you follow the command with a colon (“STUB=mystub:”), Mentor assumes you are redefining the variable, rather than referring to an existing definition.

Variables (and tables) can be stored and called in later runs, see 4.5 META COMMANDS.

DEFAULT VARNAME GENERATION

If you do not assign a variable name to a keyword, Mentor will generate default variable names by adding an extension to the table set name. For example, a banner from the table set named “example” would have the variable name “example_bn”. Below is a partial list of the default variable names.

BANNER=* _bn ROW_SHORT_WEIGHT= _rsw

BASE=* _b ROW_WEIGHT= _w

COLUMN= _c STUB=* _s

COLUMN_SHORT_WEIGHT= _csw STUB_PREFACE* _sp

COLUMN_WEIGHT= _cw STUB_SUFFIX* _sx

EDIT=* _e STATISTICS= _st

FILTER=* _f TITLE=* _t

FOOTER=* _fo TITLE_2=* _t2

HEADER=* _h TITLE_4=* _t4

LOCAL_EDIT=* _le TITLE_5=* _t5

ROW= _r WEIGHT= _w

BANNER_TITLE=* _bt FILTER_TITLE=* _ft

*means that the keyword requires a closing right brace (}) and, except for EDIT and LOCAL_EDIT, all of these keywords define table text. All others define the actual data (i.e., type, categories, statistical calculations) to be printed in the table cells.

NOTE: Not having a closing brace is common error in spec files. Be sure that your BANNER, EDIT, STUB and TITLE definitions include a closing brace.

Maximum name length is 14 characters including the extension. (If your tabset names are ten characters or less, you will not have a problem with the length of your table element names.) This is not an exhaustive list of all the keywords or commands that can be specified inside the TABLE_SET structure, but these are the ones that either specify a table element or print format control.

4.3.2 Changing Table Element Defaults (The DEFINE EDIT Statement )

Below is a list of Mentor defaults for printed tables. The EDIT statement is what you use to change any of these defaults. There are several options available to control what and how table elements are printed on a table. For a complete list, see 5.3 Changing Table Specifications or MENTOR APPENDIX B: TILDE COMMANDS, ~DEFINE EDIT.

System Total row and column

System No Answer row and column

Column width: 8 spaces

Stub (row label) width: 20 spaces

Frequencies with no decimal places

Frequencies with a value of zero print as a dash (-) in the cell

Vertical percents off the Total row (no horizontal percents) to 1 decimal point.

Percent sign (%) prints.

Page length = 60 lines

Page width = 132 columns

No table of contents printed

Below is an edit statement that changes some of the default values. It has been given the variable name “defedt,” so this set of options can be referenced later. A comma and/or space(s) separate the options.

EX:

EDIT= {defedt: -COLUMN_NA, -ROW_NA, COLUMN_WIDTH=7, RUNNING_LINES=1, TCON }

EDIT= The ~DEFINE keyword used to specify table and page formatting controls.

{ Left brace marks the beginning of the definition. (optional)

defedt: The name of this definition. (optional if defined within a TABLE_SET structure).

-COLUMN_NA Suppresses the printing of the default system-generated No Answer summary column.

-ROW_NA Suppresses the printing of the default system-generated No Answer summary row.

COLUMN_WIDTH=7 Controls the width for all table columns; the default is eight. See also COLUMN_INFO= to

control column by column and STUB_WIDTH= to control row width.

RUNNING_LINES=1 Prints the table title lines continually across the page up to the specified page width

(default is 132).

TCON Creates a table of contents that, by default, includes: the table name, all titles, the

header and footer, and tcon page numbers. Refer to the keywords listed for ~DEFINE

EDIT=TCON in Appendix B: TILDE COMMANDS to change these defaults.

} Ends the definition.

THE THREE LEVELS OF EDIT

Mentor provides three levels of the edit statement. They are GLOBAL_EDIT, EDIT, and LOCAL_EDIT. GLOBAL_EDIT settings supersede any previous GLOBAL_EDIT, EDIT, or LOCAL_EDIT statements. Items are defined in an EDIT statement and stay in effect until a LOCAL_EDIT or another EDIT statement changes or turns off the item, LOCAL_EDIT options stay in effect for succeeding tables unless specifically overridden. If you want to use a LOCAL_EDIT option for just one table, use the SET DROP_LOCAL_EDIT command (see the next section on the SET DROP options). To return all EDIT settings to the defaults, use GLOBAL_EDIT=.

With these three levels of control, it is suggested that you do the following: use GLOBAL_EDIT to set the conditions which are true for all the tables in a single Mentor run; use EDIT for banner tabsets; and use LOCAL_EDIT for special features, such as statistics, ranking and zero suppression on stubs.

All three EDITs can be defined within a tabset, or they can be defined in a ~DEFINE block before a tabset. Use EDIT in the ~DEFINE block, and then call the settings in with GLOBAL_EDIT, EDIT, or LOCAL_EDIT in the tabset. Below is an example.

EDIT={globex:

PUTCHARS=—-

RANKD_IF_INDICATED

PERCENT_SIGN

PDEC=2

}

TABSET={sample:

HEADER={:=

Table Heading for a Great Table

}

FOOTER={:=

Wonderful Client and Associates

}

GLOBAL_EDIT=globex

}

Here is a list of frequently used LOCAL_EDIT options:

ALL_POSSIBLE_PAIRS_TEST

ANOVA

ANOVA_SCAN

CHI_SQUARE

COLUMN_MEAN

COLUMN_MEDIAN

COLUMN_SE

COLUMN_SIGMA

COLUMN_STD

COLUMN_STATISTICS_VALUES

DO_STATISTICS

FISHER

LEAVE_PAGE_OPEN

LEAVE_TABLE_OPEN

NEWMAN_KEULS_TEST

USE_RANK_INFO

See Mentor, Appendix B, ~DEFINE EDIT for details on each of these options.

4.3.3 Changing Table Processing Defaults (The SET Statement)

The SET statement controls table-processing defaults for the entire run. SET statements can be located at the beginning of the specification file, within table sets, or inside the EXECUTE block. Put SET statements at the beginning of a specification file for settings you want to be in effect for an entire run. SET statements can also be specified inside the ~EXECUTE block so they can be turned off and on to control processing for individual tables. Or, SET commands can be included in the definition for a table in combination with one of the SET DROP commands to drop the corresponding element(s) after the table set is used. See below for a list of the SET drop commands.

From the ~SET block you control Mentor’s processing defaults. Default settings are listed under ~SET in Appendix B: TILDE COMMANDS. In general, these controls are set for the entire run, but it is possible to specify the SET commands in a TABLE_SET or from the ~EXECUTE block. The first SET command you will probably use is AUTOMATIC_TABLES (abbreviated SET AUTOTAB). This automatically builds a table when Mentor encounters the ROW keyword, rather than requiring a TABLE or STORE command in each tabset. For details, see 4.4 TABLE BUILDING (The INPUT and EXECUTE statements).

Mentor retains table elements, such as titling, as a default until they are redefined or turned off. Keywords can be turned of by using -KEYWORD or KEYWORD=;. Since table elements remain set until they are specifically turned off, this can cause unwanted elements to show up in subsequent tables. To prevent this from happening, you can use the following ~SET DROP commands, which causes Mentor to use a table element for one table only and then discard it. This can be reversed, meaning table elements, once defined, will once again be carried to subsequent tables, by using the SET command within a tabset or ~EXECUTE block with the DROP command with a minus sign in front of it, for example, SET -DROP_BANNER.

Here is the list of the SET DROP commands:

DROP_BANNER

DROP_BANNER_TITLE

DROP_BASE

DROP_COLUMN

DROP_COLUMN_SHORT_WEIGHT

DROP_COLUMN_WEIGHT

DROP_EDIT

DROP_FILTER

DROP_FILTER_TITLE

DROP_FOOTER

DROP_HEADER

DROP_LOCAL_EDIT

DROP_ROW

DROP_ROW_SHORT_WEIGHT

DROP_ROW_WEIGHT

DROP_STATS

DROP_STUB

DROP_STUB_PREFACE

DROP_STUB_SUFFIX

DROP_TABLE_SET

DROP_TITLE

DROP_TITLE_2

DROP_TITLE_4

DROP_TITLE_5

DROP_WEIGHT

See Mentor, Volume II, Appendix B, ~SET for definitions of each of the DROP commands.

~SET TABLE_EFFORT controls what is put into the tables. It can save you time by building tables without actual data, allowing you to find processing or syntactical errors in your spec file. Here are the options for TABLE_EFFORT:

TABLE_EFFORT=1 Makes tables with data from the file specified in the INPUT statement (DEFAULT).

TABLE_EFFORT=3 Makes zero-filled tables, allowing you to preview tables without processing the data file.

In addition to formatting problems and specification syntax errors, errors in table size

will be apparent using TABLE_EFFORT=3. You might want to test run your specifications with

this setting before running a large job.

TABLE_EFFORT=4 Processes only the specification file and prints a table of contents. Tables are not made

and the data file is not read. Use this setting to check specification syntax only.

TABLE_EFFORT=5 Makes zero-filled tables, and shows all of the elements in effect on the printed table for

debugging purposes. This includes all default values being used, the column and row

variables, the category descriptions, and the stubs, banner, and data locations used to

calculate statistics.

4.4 TABLE BUILDING (The INPUT and EXECUTE statements)

~INPUT opens the data file. Mentor assumes the filename has an extension of TR, because that is the default extension for CfMC data files (also called a System File). You can eliminate the expectation for the TR by preceding the file name with a dollar sign ($) or with the META command >-CFMC_FILE_EXTENSIONS. The INPUT command has several options, which allow you to use different data file types or use only selected cases from the data file. See Appendix B: TILDE COMMANDS, ~INPUT for a complete list of options. If you need to copy or reformat your data file, see the COPYFILE utility in the Utilities manual.

~EXECUTE is the command that triggers the construction and printing of tables. For maximum flexibility and control, Mentor provides several ways to build tables. This allows you to make table creation and printing separate procedures, for example, if you want to run the tables and print them later. See ~EXECUTE in Mentor Appendix B for all of the options.

It is possible to define table elements or tabsets directly in the EXECUTE block, but available memory limits the size of some variables (such as the column or row) that you can define, and you cannot save any elements using this method. You could also define each table element in the DEFINE block, and call each item in the EXECUTE block separately. For example,

~DEFINE

ROW=R1: [12^3/2/1/9]

COLUMN=C1: Total WITH [2^1] WITH [2^2]

~EXECUTE

ROW=R1

COLUMN=C1

This method, while straightforward, requires lots of typing and would result in huge specification files. It is much more efficient to define tables in tabsets and then call them in the EXECUTE block. If you are building only a few tables, you can store tabsets in memory and call them individually in the EXECUTE block (TABLE_SET or TABLE=). It is more efficient to have all the tables built at once, and then printed, you can do this and you can also store tabsets in a db file so you can print them later (STORE_TABLES=). Or, you can print all of the tables created in the run with one command (MAKE_TABLES). Below are examples of each of these methods.

PRINTING INDIVIDUAL TABLES (USING TABLE_SET OR TABLE=)

An easy way to define and build tables is to define table elements as a group in a table set, and then store those elements in memory. In the table set, use the TABLE= command. The TABLE= command in the DEFINE block stores the table elements and data in memory, and then the TABLE_SET command in the EXECUTE block causes the table to be built and printed. This method is best for a building a single table or a few tables because it only makes one table for each pass through the data, which would be very slow and inefficient for many tables. This is the method used in the first two examples in this chapter:

~DEFINE

TABLE_SET={example:

COLUMN=: Total

ROW=: [1^1/2]

TABLE=*

}

~INPUT $

~EXECUTE

TABLE_SET=example

You can use TABLE= in the EXECUTE block instead of TABLE_SET. TABLE= causes Mentor to build a table using the current table elements and then print the table immediately. TABLE= can specify a specific table name or asterisk (*) to mean use the current table name and increment by one. The first tabset has the default table name T001, and tabset two would have the name T002. (You can use the SET command TABLE_NAME to specify the current table name.)

STORING TABSETS IN THE DB FILE (USING STORE_TABLES )

Instead of the TABLE= command, you can use STORE_TABLES (abbreviated STORE). STORE_TABLES saves table specifications in memory until memory is full and then stores tables in a DB file. This is faster than TABLE_SET or TABLE= because it processes the data in the tables first and then prints them. Unlike TABLE, tables are not automatically printed, so you must include a printing command in the EXECUTE block.

EX:

>CREATE_DB tabstuff

>PRINTFILE mytables

~DEFINE

TABLE_SET={one:

HEADER=: These Are My Tables }

BANNER=:

| Total Male Female

| —– —- —— }

COLUMN=: Total WITH [2^1] WITH [2^2]

}

TABLE_SET={two:

TITLE={:

How much do you like building tables? }

STUB={mystub:

3-Very Much

2-Somewhat

1-Not Much

9-Don’t Know }

ROW=: [12^3/2/1/9]

STORE=*

}

TABLE_SET={three:

TITLE={:

How much do you like Roadrunner’s Pizza? }

STUB={mystub }

ROW=: [13^3/2/1/9]

STORE=*

}

~INPUT $

~EXECUTE

TABLE_SET=one

TABLE_SET=two

TABLE_SET=three

PRINT_ALL

~END

The advantage of saving tables to the db file is that you can print tables without having to construct them again. This is useful if you have to make simple changes to the table labels (see 5.6 REPRINTING TABLES for how you can reprint tables that have been stored in a DB file from a previous run) or for printing a single table out of a large group of tables.

With either TABLE= or STORE_TABLE=, Mentor stores table elements in memory before making a pass through the data to build the tables. The number of tables that can be made in a single pass depends on the amount of memory available. This is either the default for your machine or what you set memory to on the CORE option from the command line. Refer to your Utilities manual Appendix D: CfMC CONVENTIONS, Command Line Keywords for more information on setting core memory higher to fit more tables per data pass.

Instead of using the STORE=* command in every tabset, you can use the ~SET AUTOMATIC_TABLES command. This causes Mentor to store tables every time it encounters the ROW keyword. (Be careful, if you include both STORE_TABLES or TABLE in a TABLE_SET when you have also specified SET AUTOMATIC_TABLES, two tables will be built for each ROW keyword!)

EX:

~SET AUTOMATIC_TABLES

~DEFINE

TABLE_SET={one:

HEADER=: These Are My Tables }

BANNER=:

| Total Male Female

| —– —- —— }

COLUMN=: Total WITH [2^1] WITH [2^2]

}

TABLE_SET={two:

TITLE={:

How much do you like building tables? }

STUB={mystub:

3-Very Much

2-Somewhat

1-Not Much

9-Don’t Know }

ROW=: [12^3/2/1/9]

}

TABLE_SET={three:

TITLE={:

How much do you like Roadrunner’s Pizza? }

STUB={mystub }

ROW=: [13^3/2/1/9]

}

~INPUT $

~EXECUTE

TABLE_SET=one

TABLE_SET=two

TABLE_SET=three

PRINT_ALL

~END

MAKING SEVERAL TABLES (USING MAKE_TABLES)

For a standard run (several tables, a single banner, and sequential table numbers) use the MAKE_TABLES command in the EXECUTE block. MAKE_TABLES builds and prints all of the tables defined by reading a TAB file for a list of tables and an LPR file for a list of LOAD and PRINT commands for those tables. If you use the ~SPEC_FILES command, Mentor will generate the TAB and LPR files for you automatically. (Survent users: If you used ~PREPARE COMPILE Mentor_SPECS to generate a TAB file, ~SPEC_FILES will overwrite it. If you need to keep the Survent generated TAB file, rename it or move it to another directory.)

(MAKE_TABLES actually calls the BUILD_TABLES, RESET and PRINT_RUN commands. You can use these commands separately to have more control over your run. See Mentor, Appendix B: ~EXECUTE LOAD_TABLE, STORE_TABLE, and PRINT_ALL.)

Here is a typical spec files that takes advantage of both SET AUTOMATIC_TABLES and EXECUTE MAKE_TABLES.

~SPEC_FILES

~SET AUTOMATIC_TABLES

~DEFINE

TABLE_SET={one:

HEADER=: These Are My Tables }

BANNER=:

| Total Male Female

| —– —- —— }

COLUMN=: Total WITH [2^1] WITH [2^2]

}

TABLE_SET={two:

TITLE={:

How much do you like building tables? }

STUB={mystub:

3-Very Much

2-Somewhat

1-Not Much

9-Don’t Know }

ROW=: [12^3/2/1/9]

}

TABLE_SET={three:

TITLE={:

How much do you like Roadrunner’s Pizza? }

STUB={mystub }

ROW=: [13^3/2/1/9]

}

~INPUT $

~EXECUTE MAKE_TABLES

~END

4.5 META COMMANDS

Meta (>) indicates a command that can be invoked in most CfMC software programs and across tilde blocks. They are used for general programming controls, variable data base access, and specification file control. Here is a description of some of the meta commands you are likely to use. Refer to your UTILITIES manual for definitions of all meta commands.

>DEFINE @STUDY sample >DEFINE defines a keyword that can be used as a substitution for any string. In this

case, it is used to give the name of the study at the top of a run, so it can easily

be referenced on any command requiring the study name. This allows you to use

“@STUDY” on each command line and Mentor will automatically pull the name “sample”

into the line. This format is used for other meta commands in this section.

>PRINT_FILE @STUDY~ >PRINT_FILE opens a file to be printed to for tables or procedure output. There are

also options to print to the screen, print to multiple files, or control the page

size. NOTE: The tilde mark (~) acts as a delimiter for user-defined variables. This

means you can append letters and/or numbers to the STUDY name, for example,

>PRINT_FILE @STUDY~2 would open the print file SAMPLE2.PRT.

>AllOW_INDENT Allows indentation of meta commands and &filename, otherwise, they must start in the

first column of the specification file.

>PURGE_SAME Purges existing files with the same name as any newly created file. This is useful

if you are repeating runs often and do not want several intermediate files saved.

Without >PURGE_SAME, Mentor renames the existing files by changing the first

character of the file name up one alpha character (for example drop.prt would be

renamed erop.prt). NOTE: Use >PURGE_SAME with caution, it deletes existing files

with the same name!

THE DB FILE

A DB file is a machine-readable file which allows you to store variables and tables for fast retrieval by Mentor. By default, Mentor stores variables in a “local” DB file, which disappears after the current run. To store items for a later run, you create the DB file in one spec file, and then make a reference to it in another spec file. Here are the DB commands:

>CREATE_DB @STUDY~ >CREATE_DB opens a new data base (DB) file to store any new variables or tables

made by Mentor. Later you can refer to this file to reprint built tables or rebuild

tables using variables that exist in the DB file. (See the note above about the

tilde mark (~) under >PRINT_FILE.)

>USE_DB @STUDY~ >USE_DB opens a data base (DB) file containing previously defined Mentor or Survent

variables or tables. See “4.11 SAMPLE SPECIFICATION FILES”, for an example of using

the DB file for table elements. Two ampersands (&&) followed by a name will store

the item in a data base (DB) file and then execute it. The file or data base item

can include executable program commands and syntax suitable for the current tilde

block, or it may include other tilde commands or meta commands. (See the note above

about the tilde mark (~) under >PRINT_FILE.)

4.6 DEFINING DATA

Data definitions tell Mentor where to find the data to tabulate, what type of data it is, and how it is organized. You can use data definitions to define the table’s vertical and horizontal axes, exclude respondents from a table (this is known as a base), or give more weight to some data. Use these data definitions in your COLUMN and ROW statements.

You can join two or more variables together to form expressions. Expressions create new data categories, and you can use them to: perform across-case statistical calculations; execute functions to change or manipulate the data in specific ways; or, create special kinds of tables (such as break and overlay tables).

This section covers the rules for creating simple data definitions. In 4.6.1 Summary of Rules for Defining Data, there are several examples illustrating the syntax for data field locations and category definitions. The next section, 4.7 DEFINING THE BANNER, has an example of a complex table banner using the WITH joiner. Joiners and expressions are covered in detail in section 5.1 Expressions and Joiners.

A data definition is usually enclosed in brackets [ ]. It can be assigned a name for future reference or as you saw earlier Mentor can generate default variable names derived from the TABLE_SET name and the table element keyword. The data definition can also include text that will print as a title any time the variable is referenced in a table or text to label each data category (i.e., stub labels). Optional data modifiers can be used to change how data categories are tabulated.

Variables are defined with the keyword VARIABLE, and can be used in data modification, data reporting, or tables. To create cross-case statistics or need special table building controls, use the AXIS commands to define the COLUMN, BASE, or ROW. AXIS commands can only be used on tables. Refer to 5.2 Axis Commands/Cross-Case Operations.

Syntax: VARIABLE= varname: $T=”text” &

[record/col.wid, mod type categories] joiner [record/col.wid, etc.]

VARIABLE= The ~DEFINE keyword to start a variable definition.

It is not required since it is the default keyword used by ~DEFINE.

varname The name of the variable; this is required unless you have a simple variable

that has a name on its data specification; i.e., varname[5^1]. It can be 1 to 14

alphanumeric characters starting with a letter, and may include periods (.), and

underscores (_).

: Required only if the variable definition contains any functions or joiners to form

a complex variable expression. Remember that within the TABLE_SET structure keyword=:

tells Mentor that this is a new definition and if no varname is specified then generate

the default name.

$T=”text” The title of the variable (optional). The text prints as the title of a table element

whenever the variable is referenced and another title is not provided. In a TABLE_SET,

this is the same as defining a TITLE= variable. If $T is not specified, then the varname

prints as the default title if no other title is provided.

Text can be continued onto the next line by placing a double ampersand (&&) immediately after the last

quote. Continue the text on the next line by placing it in quotes also.

& Required at the end of any line within the definition which continues to the next line.

[ ] Required around each new data element specification, but is not required if all references

are to previously named data specifications.

record The record number for the location of the data. By default CfMC programs report all data

locations in the record/col.wid format. (Data locations can be referenced by absolute

column as well.)

col.wid The starting column location and number of columns. If you don’t include a width, then one

column is assumed. You can also specify the location as column1-column2, where column1 is

the first column and column2 the last column. For a multiple column/item specification, use

commands to separate column specifications, or an ellipsis (,…,) to say ‘columns starting

here and going to there’. Multiple column specifications create a set of categories for each

single column description. Non- consecutive data locations are separated by a comma (,). See

“4.6.1 Summary of Rules for Defining Data”.

mod Refers to the variable modifier used to determine how to combine categories in variables

referencing multiple columns, or to modify numeric data references. The default is make

separate categories for all the data locations. (optional)

Multiple data column references: col1,col2,…,coln:

*F or FIRST nets the counts per category across columns (i.e., it counts only the first

mention of each category).

*L or LAST sums the counts per category across columns (i.e., it sums all mentions for each

category).

Use *F to count cases (respondents, how many) and use *L to count things in the cases (family members, how much, or how often). For example, you would use *F when you want to know how many people bought the products they were asked about, but not how much they bought. If you are asking did they buy it, use it or eat it, use *F, if you are asking how many did they buy, how much did they eat or how often did they use it, use *L.
Numeric data references:

! Return a zero (0) when the location is blank, e.g., [!5/10.2] says if record five columns

10 and 11 are blank then return a zero. Note that the exclamation (!) is prior to the

location being referenced, unlike the other modifiers.

*D# The variable contains decimals, e.g., [1.10*D1] says this variable has one decimal in the data.

If there is not one decimal, the value will be treated as ‘Missing’ (ignored). The maximum

number of decimal places is 14.

*F# This variable has implied decimals, e.g., [1.10*F2] says this variable has two implied decimals.

If there is an actual decimal in the data, that will be used instead of the implied decimals.

*RANGES=#-#,#,a=#,b,c Specifies the numeric range and exception codes of the variable. This is useful to

exclude codes in the data from future calculations, such as for Means. Exception codes can also

be assigned a value to be used in statistical calculations, otherwise they are excluded from

stats.

#-# range of values to be included in evaluation of the data.

# numeric value to be excluded from evaluation, but allowed.

a=# exception code1 to be recoded to this number (#) for evaluation.

b exception code2 to be counted, but not included in numeric evaluation.

c exception code3 same as above.

*Z The data contains leading zeros (0), e.g., [10.2*Z#1-10]. If there is no leading zero, the

location will be considered “missing”, and will be ignored.

EX: row1: [15.2#1-50/RF/DK &

$[MEAN,STD,SE] [15.2*RANGES=1-50,,RF=0]

row1 The variable name

: Required for a complex variable or axis definition

[ Defines the start of a data reference

15.2 The data location, columns 15 and 16

# Specifies the type of data, ASCII or numeric

1-50 The range of responses allowed for this data category

RF The literal allowed for this category

DK Another allowed literal

& Ampersand continues the definition to the next line

$[MEAN,STD,SE] The statistical tests that will be performed on the data (mean, standard deviation,

and standard error) For more information, see “5.2 Axis Commands/Cross-Case Operations” and

Appendix B: TILDE COMMANDS, ~DEFINE AXIS=.

[15.2*RANGES=1-50,,RF=0] Defines which columns will be tested (15.2) and which values will be included

in the evaluation. A value has been assigned to the exception code RF.

Modifiers can be combined in the same variable where it makes sense to do so. Specify only one asterisk (*) when you combine options.

EX: [5.4*ZD2]

This variable contains leading zeros and two decimals.
DATA TYPES

type The type of data variable, either punch or ASCII. Data type is identified by one of two symbols:

caret (^) indicating punch binary codes, pound sign (#) indicating either numeric ranges or

ASCII characters. If no type is specified (i.e., just a data location is given with no categories),

then data type defaults to numeric and must be a valid number that is right-justified in the field.
Punch Data

Punch Data (^) is stored as 12 punches per column, 1-9, 0, X, and Y. (You can substitute 10, 11, and 12 for 0, X, and Y.) Survent CAT questions return punch data. This example represents punch data found in record 1, column 5, a width of one column, punches 1 and 2:

[1/5^1/2]

Punch data can be any width. For categories wider than one column, punches are represented as their position relative to the first punch of the first column in the data field. For example, the third punch in the second column of a data field would be referenced as 15:

[1/6.2^15]

This example represents punch data found in record 1, column seven, a width of two columns, the third punch:

[1/7.2^3]

You can precede any punch with the letter N to mean “is not these punches,” the letter B to mean “is blank” (no punch), or the letter A to mean “has all these punches.” You can combine N with B to mean “is not blank,” and N with A to mean “is not all of these punches.”

[10^A1,2/N3,4/AN5,6]

This example creates three categories. The first will contain records which have both 1 and 2 punched. The second category will contain records which have neither 3 or 4 punched. The third category will contain records which do not have both 5 and 6 punched.
ASCII data (#)

Can be alphabetic, numeric, or special characters (enclosed in quotes), or some combination. The maximum data field width for numbers is 20 and 9 for alphabetic characters. Survent FLD and NUM question types return ASCII data.

[1/55.2#0-3/4-5/6-10/RF]

0-3/4-5/6-10/RF represent the numeric ranges for each data category. RF is an exception code. Codes are not case-sensitive, and quotes are not required.

Quotes are necessary when you want to match special characters (i.e., ? / *) or blanks. Quotes are also necessary if you want to have Mentor treat numbers as ASCII characters, meaning they must be an exact match (for example, left- justified in the field).

[1/5.4#99]

In this example, 99 is treated as a number and must be right-justified in the field (columns 7 and 8) to match this definition. That means it could be blank or zero- filled in columns 5 and 6 to match ( 99) or (0099).

[1/5.4#”99″]

In this example, “99” will be treated like all other ASCII characters and must be left-justified in the field to match the definition (99 ).
USING PUNCTUATION TO CREATE CATEGORIES

4.6.1 Summary of Rules for Defining Data

The next few pages provide several examples of how you can define data in Mentor. The first column is a sample data definition and the second and third columns show the actual locations the definition refers to.

SAMPLES OF DATA FIELD LOCATIONS

RECORD COLUMN

NUMBER NUMBER(S) REFERENCED

—— ——————–

1. Single Column Locations

[1/5] 1 5

[5] (defaults to 1) 5

[7/48] 7 48

2. Locations Wider than 1 Column

[1/5-9] 1 5, 6, 7, 8, and 9

[5-9] (defaults to 1) 5, 6, 7, 8, and 9

[1/2.5] 1 2, 3, 4, 5, and 6

[4/1.3] 4 1, 2, and 3

3. Multiple Locations

[1/8,1/9] 1 8 and 9

[4/32,4/35,4/46] 4 32, 35, and 46

[1/16,…,1/20] 1 16, 17, 18, 19, and 20

[5/32,…,5/27] 5 32, 31, 30, 29, 28, and 27

[2/17-18,…,2/25-26] 2 17 & 18; 19 & 20; 21 & 22; 23 & 24; 25& 26

(i.e., five fields, each two columns wide)

[1/24.3,…,1/33.3] 1 24 & 25 & 26; 27 & 28 & 29; 30 & 31 & 32;

33 & 34 & 35; (i.e., four sets of three columns)

NOTE: The last “.3” is not required since once a width is stated, either explicitly (24.3) or

by default (8 implies 8.1), it stays in effect for all locations in the same set of brackets.
PUNCTUATION USED IN REFERENCING DATA FIELD LOCATIONS

Single Slash (/): Used to separate the record number from column number(s).

Period (.): Used after the leftmost column number of a data field, and followed by a

number giving the width of the field (in number of columns).

Comma (,): Used after a data field location reference to indicate that multiple

column fields are being specified.

Ellipsis (…): Used after a column number in a data field location to abbreviate the listing of a

sequence of consecutive locations when multiple column locations are specified.

Square Brackets ([ ]): Used to enclose a variable definition.
CATEGORY DEFINITIONS USING CARET (^) FOR PUNCH DATA

NUMBER OF PUNCH CODES

CATEGORIES TO CREATE USING THESE PUNCHES

——————– ——————-

EXAMPLE SET A: For Separate Punch Position Categories

1/12 2 1 and Y

1//12 12 1,2,3,4,5,6,7,8,9,0,X, and Y

1/2/3/11 4 1,2,3, and X

12/11/10/9/8/7/6/5 8 Y,X,0,9,8,7,6, and 5

11//7 5 X,0,9,8, and 7

1/4//9/12 8 1,4,5,6,7,8,9, and Y

13//24 12 1,2,3,4,5,6,7,8,9,0,X, and Y in the second

column of the field

1,4.9/12 2 “1,4,5,6,7,8,9”, and Y

EXAMPLE SET B: For Netted Punch Position Categories

1,2,3 1 “1,2,3” (A new, single netted category)

1,2/3/12 3 “1,2”,3, and Y

5-12 1 “5,6,7,8,9,0,X,Y”

1/3/4.6/7//12 9 1,3,”4,5,6″,7,8,9,0,X, and Y

1-12 1 “1,2,3,4,5,6,7,8,9,0,X,Y”

12-1 1 “Y,X,0,9,8,7,6,5,4,3,2,1”

1,13,25 1 A new single netted category of the 1

punches in first 3 columns of the field.

EXAMPLE SET C: For Negative Punch Position Categories

B 1 Absence of all codes 1-Y

N1 1 Not 1

N1/3/7/9 4 “Not 1”,3,7, and 9

6//9/N1-5 5 6,7,8,9, and “NOT 1-5”

NB 1 “1,2,3,4,5,6,7,8,9,0,X,Y” (same as 1-Y)

EXAMPLE SET D: Specifying Locations and Categories for Punch Data

RECORD COLUMN NUMBER OF PUNCH CODES

NUMBER NUMBERS CATEGORIES REFERENCED

—— ——- ———- ———–

[1/5^1/2/12] 1 5 3 1,2, and Y

[3/7^1//6] 3 7 6 1,2,3,4,5, and 6

[5^11/7/2/1] 1 5 4 X,7,2, and 1

[5/5.2^01//24] 5 5-6 24 1,2,3,4,5,6,7,8,9,0,X,Y in

column 5 and

1,2,3,4,5,6,7,8,9, 0,X,Y

in column 6

PUNCTUATION USED IN DEFINING PUNCH DATA

Comma (,): Used to create a single netted category of the punches’ positions listed.

Dash (-): Used to indicate the net of all consecutive punch positions between the first

punch position specified, and the last punch position specified. (same as period)

Caret (^): Indicates punch type data, single or multi-column punch field. Note that you can

specify the punch codes as a position relative to the first column in the field,

e.g.,12 or the actual code Y.

Period (.): Used to indicate the net of all consecutive punch positions between the first

punch position specified, and the last punch position specified. (same as dash)

Slash (/): Used to indicate separate punch code categories.

Double Slash (//): Used to indicate a set of separate but consecutive punch code categories.

Square Brackets ([ ]): Used to enclose a data variable definition.
CATEGORY DEFINITIONS USING POUND SIGN (#) FOR ASCII AND NUMERIC DATA

Record Column Number

Number Number of Cats. Values

—— —— ——– ——

EXAMPLE SET A: ASCII CATEGORY DEFINITIONS

[8/4.2#17/26/AA/ZZ] 8 4-5 4 17, 26, AA,ZZ

[2/2.3#ABC/999/&&&] 2 2-4 3 ABC, 999,&&&

[6/38.3#190/B27/321/55D] 6 38-40 4 190,B27,321, 55D

EXAMPLE SET B: NUMERIC CATEGORY DEFINITIONS

[3/7.3#157/305/872] 3 7-9 3 157, 305,872

[1/1.2#28/77/93,94] 1 1-2 3 28, 77, “93 or 94”

[4/27.2#1//99] 4 27-28 99 99 separate categories

[1/37.2#1-10/11-20/31-40] 1 37-38 3 The range 1-10, the range 11-20,

the range 31-40.

[1/10.5#1.99-10.99/RF] 1 10-14 2 The range 1.99 – 10.99, the

exception code RF.

[1/5.2] 1 5-6 1 All real numbers in this location, meaning

any positive, negative, or decimal number.
PUNCTUATION USED IN DEFINING ASCII AND NUMERIC DATA

Pound Sign (#): Used to indicate Numeric or ASCII type data.

Dash (-): Used as in “n-m”, to represent a range of values from n to m.

Comma (,): Used within a category definition to separate alternative values.

Quotation Marks (“”): Used to set off and identify special characters such as

literals, including blank spaces.

4.7 DEFINING THE BANNER

Printed tables have two main elements, a banner and a stub. Since a banner normally includes the variable(s) you want on all of your tables, you can make one banner definition and just change the stubs. Generally you will use one TABLE_SET to combine the elements of each banner (including the banner text, the column variable, the table printing (EDIT) options), and one TABLE_SET for each of the stubs (including the titles, stub labels, bases, and row variables).

The banner TABLE_SET can also include an overall filter variable for the set of tables (BASE or FILTER), a definition to control what prints at the top or bottom of each table (EDIT STUB_PREFACE or STUB_SUFFIX), a weight variable to give weights to the cases included in the tables, or specifications to choose the type of statistics to do and which columns to be included in the comparisons (see Appendix B: TILDE COMMANDS, ~DEFINE STATISTICS and ~EXECUTE COLUMN_WEIGHT).

Stub TABLE_SETs can include items to control specific table printing needs (LOCAL_EDIT), a variable to filter respondents (BASE), base titling (TITLE_4), and row weighting (ROW_WEIGHT). You can use the SET command to turn on or off certain production controls to affect groups of tables, such as whether to drop items after one table, or how to assign table names.

If you have more than one banner definition, then you can use a global TABLE_SET to define such things as the header and footer to print on the tables, global SET commands, or a main EDIT statement for table building and printing controls. Here is a typical TABLE_SET for a banner:

TABLE_SET={BAN1:

STUB_PREFACE=ONLY_AR1

EDIT={: -COLUMN_TNA

COLUMN_WIDTH=7,STUB_WIDTH=21,

COLUMN_INFO=(C=8 W=7/C=9 W=7/C=10 W=7),

VERTICAL_PERCENT=AR,PERCENT_DECIMALS=1,-PERCENT_SIGN,

STAR_PERCENT=0,STATISTICS_DECIMALS=2,PUT_CHARACTERS=—,

CALL_TABLE=””, RUNNING_LINES=1,

TCON=(-TABLE_NAMES,PRINT_PAGE_NUMBERS,-TITLE_2)

}

BANNER={:

| CITY SEX AGE Q1. BEST NAME

| =========== =========== ============ ====================

| DEN- DAL- FE-

| TOTAL VER LAS MALE MALE 18-34 35+ CHOICE SELECT SOURCE

| —– —– —- —- —- —– —– —— —— ——

}

COLUMN=: TOTAL WITH &

[5^1/2] WITH & ”city

[6#M/F] WITH & ”sex

[65^1,2/3,4] WITH & ”age

[16^1//3] ”q1

}

The Stub_Preface above controls format and printing of rows at the top of the table, which are often system generated rows (i.e., Total, No Answer, Any Response). The variable ONLY_AR was previously defined with the keyword STUB= and then assigned to this table element:

STUB={ONLY_AR:

[SUPPRESS] TOTAL

[SUPPRESS] NO ANSWER

[PRINT_ROW=AR] ANY RESPONSE }

Table edit and text elements such as BANNER= and EDIT, require a closing right brace (}). The matching open left brace ({ ) is optional. Refer to the list of keywords under the heading Default Varname Generation for a list of which elements require a closing brace.

Other EDIT options that you can use in the banner TABLE_SET are:

BOTTOM_MARGIN= PAGE_WIDTH=

CONTINUED= PREFIX=

CUMULATIVE_PERCENT PRINT_ALPHA_TABLE_NAMES

DATA_INDENT= RANK_COLUMN_BASE=

EMPTY_CELLS= RANK_IF_INDICATED

FREQUENCY RANK_LEVEL=#

FREQUENCY_DECIMALS= RANK_ORDER=

FREQUENCY_ONLY SKIP_LINES=

HORIZONTAL_PERCENT= STUB_INDENT=

INDENT= STUB_RANK_INDENT=

MINIMUM_BASE= STUB_WRAP_INDENT=

MINIMUM_FREQUENCY= SUFFIX=

MINIMUM_PERCENT= SUPPRESS_ROWS_BASE=

NUMBER_OF_CASES TFRP

PAGE_LENGTH= TOP_MARGIN=

Other EDIT options relating to statistical testing that could logically be stored with the banner TABLE_SET include:

ALL_POSSIBLE_PAIRS_TEST

CHI_SQUARE_ANOVA_FORMAT

NEWMAN_KEULS_TEST

TABLE_TESTS=<region>

These EXECUTE elements are also typically associated with a banner:

COLUMN_WEIGHT=

COLUMN_SHORT_WEIGHT=

STATISTICS=

All of the EDIT options are defined in Appendix B: TILDE COMMANDS, ~DEFINE EDIT=. See also 5.3 Changing Table Specifications.

4.8 FORMATTING BANNER TEXT

To create a banner for a table you need to define a variable that specifies the exact text, spacing, underlining, headings, etc. for each data column or banner point. To print a table with a user-defined banner it must either be assigned to the table building keyword ~EXECUTE BANNER=varname or be defined in a ~DEFINE TABLE_SET= with the keyword BANNER=.

The BANNER keyword only defines text; it does not affect the data printed under the column labels.

In designing a banner you need to consider the number of banner points you want, the width of the widest label, and the width of the stub(row) labels. Remember that the wider the banner the less room will be available for the stub labels. Most wide carriage printers allow a maximum of 132 columns with a regular font and up to 250 columns with a compressed font.

This example uses the default column width of eight spaces, suppress the default Total summary and the No Answer columns, and creates its own Total summary column. The banner has seven banner points at eight columns each for a total of 56 columns. If you are printing a percent sign (%) for either the vertical or horizontal percents this adds one more column to the total table width. The percent sign prints one character to the right of the frequency printed above it. Stub labels default to 20 spaces making a total table width of 77 columns. An easy way to get started on the definition is to lay out the total columns needed for all the labels using some sort of spacing guide to follow for each label.

EX: 7 banner points, each 8 columns wide

——- ——- ——- ——- ——- ——- ——-

Starting with the Total column, this guide lines up each of the banner points over the data that will print below it. Frequencies, by default, will be right-justified within the column width. The text for each label can be placed over these guides. Vertical bar ( | ) marks the start of text including any blank spaces. Lines will be indented depending on where you place the vertical bar.

BANNER=:

| <—SEX—-> <———–AGE————->

| Don’t

| Under Over know/

| Total Male Female 35 35-54 54 Refused

| —– —- —— —– —– —- ——- }

This banner definition specifies headings for the two groups of banner points, a blank line, and labels for each data column. The last line uses dashes to underline each label. Blank spaces preceding each label count as part of the total column width of eight.

Since this banner definition is inside a TABLE_SET= structure, you must use the BANNER keyword to define banner text and assign it to a table element. Unlike other table text, banner labels must be defined with the BANNER keyword and, once defined, the banner is not interchangeable with other text elements.
SAMPLE SPECIFICATIONS AND TABLE

Here is a sample specification file that includes a banner TABLE_SET and calls in the stub TABLE_SET from another file. With this structure, you have Survent build the stub TABLE_SETs for you.

>PURGE_SAME

>DEFINE @STUDY rrunr

>PRINT_FILE @STUDY~

~SPEC_FILE @STUDY~

~DEFINE TABLE_SET=tabtop:

SET AUTOMATIC_TABLES

EDIT=: -COLUMN_TNA,-ROW_NA,RUNNING_LINES=1,TCON}

BANNER=:

| <—SEX—-> <———–AGE————->

| Don’t

| Under Over know/

| Total Male Female 35 35-54 54 Refused

| —– —- —— —– —– —- ——- }

COLUMN=:TOTAL WITH [1/57^1/2] WITH [1/51^1,2/3,4/5,6/7]

}

&@STUDY~^DEF

~INPUT @STUDY~

~EXECUTE

MAKE_TABLES

~END
THE STUB TABLE_SET

Here is the contents of the rrunr.def file:

TABLE_SET= { qn1_z:

TITLE=:

Q1. How much do you agree with the following

statement: The fast food at Road Runners is worth what I pay for it.}

STUB=:

(5) Completely agree

(4) Somewhat agree

(3) Neither agree nor disagree

(2) Somewhat disagree

(1) Completely disagree

Don’t Know/Refused to answer }

ROW=: [1/6^5//1/10]

}

And here is the table:

TABLE 001

Q1. How much do you agree with the following statement: The fast food at Road Runners is worth what I

pay for it.

<—-SEX—> <————AGE————>

Don’t

Under Over know/

Total Male Female 35 35-54 54 Refused

—– —- —— —– —– —- ——-

Total 500 263 237 141 140 143 76

100.0% 100.0% 100.0% 100.0% 100.0% 100.0% 100.0%

(5) Completely agree 88 49 39 21 29 23 15

17.6% 18.6% 16.5% 14.9% 20.7% 16.1% 19.7%

(4) Somewhat agree 92 43 49 26 27 27 12

18.4% 16.4% 20.7% 18.4% 19.3% 18.9% 15.8%

(3) Neither agree 86 48 38 23 26 24 13

nor disagree 17.2% 18.3% 16.0% 16.3% 18.6% 16.8% 17.1%

(2) Somewhat 73 36 37 13 23 21 16

disagree 14.6% 13.7% 15.6% 9.2% 16.4% 14.7% 21.1%

(1) Completely 86 43 43 29 17 26 14

disagree 17.2% 16.4% 18.1% 20.6% 12.1% 18.2% 18.4%

Don’t Know/Refused 75 44 31 29 18 22 6

to answer 15.0% 16.7% 13.1% 20.6% 12.9% 15.4% 7.9%

When defining your own banners, we recommend you always define your own Total column in the TABLE_SET and in the column variable expression(TOTAL WITH variable…), then suppress the System Total/No Answer columns on the EDIT statement with -COLUMN_TNA. This will ensure that operations like statistical testing are calculated off of the values you have defined for the Total column and not the system generated Total column, which only reflects a count of the number of cases that satisfy conditions for inclusion in this table.
FORMATTING A BANNER WIDER THAN 80 COLUMNS

If your editor does not allow you to type beyond column 80, you will have to format banners wider than 80 columns a little differently.

For this example uses the vector joiner WITH, which appends the categories for respondent income to the categories for marital status to form a single expression.

EX: TOTAL WITH [1/52^1/2,3/4,5/6/9] WITH [1/54^1//6]

The income categories are 1, 2 or 3, 4 or 5, 6, and 9. Notice that categories 2 and 3, and 4 and 5 uses a comma, so respondents who answered either 2 or 3 (or 4 or 5) on the income question will be counted as a single category.

NOTE: The second variable uses the double slash (//) to say six categories which are punches 1,2,3,4,5, and 6 instead of specifying each category separated by a single slash (/).

The joiner WITH creates twelve categories, one for the total, five income categories, and six marital status categories.

The width for this table is 117: 12 eight column banner points (plus one column if you are printing the percent sign, see previous example), for a total of 97 columns in the banner and 20 spaces for the stub labels.

EX: 12 banner points, each 8 columns wide

| ——- ——- ——- ——- ——- ——-&

| ——- ——- ——- ——- ——- ——-

Starting with the Total column, this guide lines up each of the banner points over the data that will print below it. The text for each label can be placed over these guides. Vertical bar ( | ) marks the start of text including any blank spaces. Lines will be indented depending on which column you place the vertical bar in. Ampersand (&) at end of a line means print the following line on the same line with this one. Again, you only need to do this if your editor cannot go beyond 80 columns. If you have left spaces before the & on the first line, you do not need to use the vertical bar ( | ) on the second; it will use the spaces between the last character on the first line and the & when it makes the banner. If you do use the vertical bar on the second line, you will have as many spaces between the sixth set of underlines and the seventh as you have between the sixth set and the & plus the second vertical bar and the seventh set.

EX:

BANNER=:

| <—————-INCOME—————>&

| <—————-MARITAL STATUS—————->

| $15,000 $35,000 &

| Single Living

| Under to to $50,000 &

| Di- never To-

| Total $15,000 $34,999 $49,999 or more Refused&

| Married vorced Widowed Married gether Refused

| —– ——- ——- ——- ——- ——-&

| ——- —— —— ——- —— ——-}

The first two lines are headings for the two groups of banner points, then the labels for each data column. The last two lines will underscore each label. Labels Divorced and Together are longer than the default column width, so are hyphenated and placed on two lines to fit the column width.

Note: In writing a banner this way, it is easier to write each half separately, seeing if things line up, then alternating the rows to make them print correctly. Also note that all of the marital statuses are together on one line – even though one of them might have fit on the Income lines, it again is simpler to keep all categories together.

And here is the table:

TABLE 001

Q1. How much do you agree with the following statement: The fast food at Road Runners is worth what

I pay for it.

<—————–INCOME————–> <—————-MARITAL STATUS—————>

$15,000 $35,000 Single Living

Under to to $50,000 Di- never To-

Total $15,000 $34,999 $49,999 or more Refused Married vorced Widowed Married gether Refused

—– ——- ——- ——- ——- ——- ——- —— ——- ——- —— ——-

Total 500 74 148 145 70 63 85 83 96 74 80 82

100.0% 100.0% 100.0% 100.0% 100.0% 100.0% 100.0% 100.0% 100.0% 100.0% 100.0% 100.0%

(5) Completely agree 88 10 30 21 15 12 17 12 17 14 14 14

17.6% 13.5% 20.3% 14.5% 21.4% 19.0% 20.0% 14.5% 17.7% 18.9% 17.5% 17.1%

(4) Somewhat agree 92 14 30 28 7 13 10 16 17 17 20 12

18.4% 18.9% 20.3% 19.3% 10.0% 20.6% 11.8% 19.3% 17.7% 23.0% 25.0% 14.6%

(3) Neither agree 86 13 22 36 9 6 14 19 14 17 11 11

nor disagree 17.2% 17.6% 14.9% 24.8% 12.9% 9.5% 16.5% 22.9% 14.6% 23.0% 13.8% 13.4%

(2) Somewhat 73 13 21 17 16 6 11 10 17 9 11 15

disagree 14.6% 17.6% 14.2% 11.7% 22.9% 9.5% 12.9% 12.0% 17.7% 12.2% 13.8% 18.3%

(1) Completely 86 8 27 23 14 14 22 16 16 12 9 11

disagree 17.2% 10.8% 18.2% 15.9% 20.0% 22.2% 25.9% 19.3% 16.7% 16.2% 11.3% 13.4%

Don’t Know/Refused 75 16 18 20 9 12 11 10 15 5 15 19

to answer 15.0% 21.6% 12.2% 13.8% 12.9% 19.0% 12.9% 12.0% 15.6% 6.8% 18.8% 23.2%

Note: Usually with banners wider than 80 columns, it is much easier to write them as shown in the next section, 4.9 GENERATING BANNER SPECS.
EDITING THE BANNER

The text element banner_title follows the same rules as the other title elements and when present appears after the title and before the title_4. There is a corresponding edit option, drop_banner_title, which follows the same rules as the other options in the “drop” family.

You can use an asterisk ( * ) in a STATS=: statement in order to indicate the last column of the banner. This feature allows a user to run stats in a job that has many different banners of varying lengths. It was introduced, in part, to allow stats to be run in a job setup to allow every question of a questionnaire to be a potential banner.

EX: STATS=:A-C,G-*

Also, since the number of banner points in WebTables is not constrained by the size of a piece of paper, this feature can ease the writing of stats on extremely wide banners. A STATS statement that uses “*” behaves no differently than one where the actual last column letter of the banner was specified explicitly.

For example, if you only have three banner points and you specify STATS=:C-* or STATS=:D-* you will get errors. See Chapter 8: Statistics (Significance Testing) for more information on this.

4.9 GENERATING BANNER SPECS

Mentor provides an improved way of writing banners that is designed:

to simplify the process of writing banners
to consolidate everything so that you have one set of banner specs that generate a print banner, a delimited banner, and an html banner.

This new style of writing uses banner element keywords, such as the options used with the EDIT statement and “banner front” keywords, which is similar to the way “stub fronts” are used.

New “banner front” keywords (only level is required):

level=# – this specifies what banner level you are describing

NOTE: Auto_colspan is the default keyword.

Typically text associated with level 1 would be total, male, female and level 2 items would be age, income, etc. Every level 1 banner point needs a corresponding description in the column element.

colspan=# – used to specify how many levels are “spanned” by this banner text and associated underlining characters.

justify=option – used to specify the justification for this banner text.

The default justification for level 1 is right and the default justification for all other levels is center. The justification only applies to the print banner and the html banner. No justification is used for the delimited banner.

underline=character – used to specify the character to use for underling this text

The default underlining character for level 1 is a dash and the default underlining character for all other levels is an equal sign. The underline character only applies to the print banner. No underlining is used in the delimited or html banners.
New banner element keywords (only make_banner is required):

make_banner=option – is used to generate banner specs for a print banner, a delimited banner, and an html banner.

where options are:

• \k(p,h,d) generate all 3 types of banners (this is the default)

• \k(p) generate only a print banner

• \k(h) generate only an html banner

• \k(d) generate only a delimited banner

• any combination of the above types

justify_level(#)=option – is used to specify the justification for the banner text.

where # matches the “banner front” level, and options are center, right or left.

The default justification for level 1 is right and the default justification for all other levels is center. The justification options only apply to the print banner and the html banner. No justification is used for the delimited banner.

underline_level(#)=character – is used to specify the character to use for underlining the banner text.

where # matches the “banner front” level.

auto_colspan – is used when you want the banner level text and underlining characters to “span” columns until:

• another banner front for the same level is seen • there are no more level 1 items in the banner • stopped by banner front option of colspan

Auto_colspan is the default.

fill_to_level=# – is used to have Mentor “fill-in” missing levels above level 1. If any lower level banner item has a level above it then all items on the lower level must have a level above them. This option allows Mentor to fill-in the missing levels so the user doesn’t need to provide “place holders”.

total_lines=# – is used to specify the height of the banner in lines.

If you have multiple print banners and you want each banner to be exactly the same height, you can use this option to have Mentor fill the banner with additional blank lines at the top until it reaches the number of total lines specified. This option only affects print banners.

Banner element keywords are overridden by banner front keywords.

The simplest example of using this technique in a tabset with an EDIT and COLUMN statement would be:

TABSET={ban1:

EDIT={:

-COL_TNA

}

BANNER={: MAKE_BANNER

[LEVEL=1] Total

[LEVEL=1] Male

[LEVEL=1] Female

}

COL=: TOTAL with [396^1/2]

}

This would create a print banner using the default column width (if none was specified) and the default level 1 underlining character (dash) and default level 1 text justification (right):

Total Male Female

——- ——- ——-

If you have a ~SPECFILE statement, the banner specs that are created are saved into a file named <specfilename>.ban and look like this:

BANNER=ban1_bn:

\k(p)

| Total Male Female

| ——- ——- ——-

\k(d)

,”Total”,”Male”,”Female”

\k(h)

<tr>

<td colspan=”1″ align=”right”> Total

<td colspan=”1″ align=”right”> Male

<td colspan=”1″ align=”right”> Female

</tr>

}

The default for the make_banner option is to make all three types of banners. If you only want a print banner, you can use MAKE_BANNER= \k(p) or any combination of \k(h) or \k(d) to get exactly what you want.

If you want to print the automatic total column and/or the automatic na column then you must provide your own banner text for those columns.

The MAKE_BANNER option uses features (COLUMN_WIDTH, etc.) set in the GLOBAL_EDIT, EDIT, LOCAL_EDIT and COL_INFO statements.

An example of a two level print banner would be:

Gender

===============

Male Female

——- ——-

This banner was created using the default column width (if none was specified) and the default level 2 underlining character (equal sign) and default level 2 text justification (center). The specs to create this banner look like this:

BANNER={: MAKE_BANNER

[LEVEL=2 COLSPAN=2] Gender

[LEVEL=1] Male

[LEVEL=1] Female

}

The COLSPAN option says this banner text (Gender) and it’s associated underlining characters will span the next two level 1 items.

An example of a three level print banner would be:

Denver

===============================

Age

Gender ===============

=============== Under 30 and

Male Female 30 over

——- ——- ——- ——-

And the specs to create it look like:

BANNER={: MAKE_BANNER

[LEVEL=3 COLSPAN=4] Denver

[LEVEL=2 COLSPAN=2] Gender

[LEVEL=1] Male

[LEVEL=1] Female

[LEVEL=2 COLSPAN=2] Age

[LEVEL=1] Under 30

[LEVEL=1] 30 and over

}

You could write all level 3’s, followed by all the level 2’s, followed by all the level 1’s:

BANNER={: MAKE_BANNER

[LEVEL=3 COLSPAN=4] Denver

[LEVEL=2 COLSPAN=2] Gender

[LEVEL=2 COLSPAN=2] Age

[LEVEL=1] Male

[LEVEL=1] Female

[LEVEL=1] Under 30

[LEVEL=1] 30 and over

}

The level 3 banner text (Denver) spans all four level 1 items. The level 2 banner text (Gender) spans the next two level 1 items and the level 2 banner text (Age) spans the remaining two level 1 items.

Using the additional banner element keyword of AUTO_COLSPAN , these specs would produce the same print banner:

BANNER={: MAKE_BANNER AUTO_COLSPAN

[LEVEL=3] Denver

[LEVEL=2] Gender

[LEVEL=1] Male

[LEVEL=1] Female

[LEVEL=2] Age

[LEVEL=1] Under 30

[LEVEL=1] 30 and over

}

If you write all level 3’s, followed by all the level 2’s, followed by all the level 1’s, you must use the banner front COLSPAN option to specify how many levels are spanned and you can’t use the AUTO_COLSPAN option.

If you had a single item that was included in level 3 but not under level 2 as in the following example:

Denver

========================================

Age

Gender ============== Income

=============== Under 30 and over

Male Female 30 over $50K

——- ——- ——- ——- ——-

You would need to add a level 2 (without any text) in the banner specs before “Income over $50K” as a COLSPAN stopper:

BANNER={: MAKE_BANNER AUTO_COLSPAN

[LEVEL=3] Denver

[LEVEL=2] Gender

[LEVEL=1] Male

[LEVEL=1] Female

[LEVEL=2] Age

[LEVEL=1] Under 30

[LEVEL=1] 30 and over

[LEVEL=2] ”place holder

[LEVEL=1] Income over $50K

}

Or you could write this banner without using AUTO_COLSPAN and add your own banner front COLSPAN items as in:

BANNER={:MAKE_BANNER

[LEVEL=3 COLSPAN=5] Denver

[LEVEL=2 COLSPAN=2] Gender

[LEVEL=1] Male

[LEVEL=1] Female

[LEVEL=2 COLSPAN=2] Age

[LEVEL=1] Under 30

[LEVEL=1] 30 and over

[LEVEL=2 COLSPAN=1] ”place holder

[LEVEL=1] Income over $50K

}

To add a total column to a banner, without any level 2 text, there is a rule for banner levels to be followed.

If any lower level banner item (Male, Female) has a level above it (Gender), then all items on the lower level (Total) must have a level above them. In other words, if there is ever a level 2, then every level 1 must have a level 2. If there is ever a level 3, then every level 1 must have a level 3, and so on.

Gender

===============

Total Male Female

——- ——- ——-

A level 2 place holder needs to be added for the total column:

BANNER={: MAKE_BANNER AUTO_COLSPAN

[LEVEL=2] ”place holder

[LEVEL=1] Total

[LEVEL=2] Gender

[LEVEL=1] Male

[LEVEL=1] Female

}

Or, an additional banner element option of FILL_TO_LEVEL=# could be used. This says if there is ever an unspecified upper level, fill it in. The same print banner could be created by using:

BANNER={: MAKE_BANNER AUTO_COLSPAN FILL_TO_LEVEL=2

[LEVEL=1] Total

[LEVEL=2] Gender

[LEVEL=1] Male

[LEVEL=1] Female

}

This is an example of a three level banner with a total column:

Denver

=======================================

Age

Gender ============== Income

============== Under 30 and over

Total Male Female 30 over $50K

——- ——- ——- ——- ——- ——-

One way to write the specs for this banner would be:

BANNER={: MAKE_BANNER AUTO_COLSPAN FILL_TO_LEVEL=3

[LEVEL=1] Total

[LEVEL=3] Denver

[LEVEL=2] Gender

[LEVEL=1] Male

[LEVEL=1] Female

[LEVEL=2 COLSPAN=2] Age

[LEVEL=1] Under 30

[LEVEL=1] 30 and over

[LEVEL=1] Income over $50K

}

HOW TO CREATE A BANNER USING MAKE_BANNER FORMAT

This section describes the steps on how you would write a banner using the MAKE_BANNER format.

1) This is the banner request from the client:

Q.B Male / Female

Q.24 25-34 / 35-54 / 55+

Q.21 High school grad or less / Some college, trade school / College grad+ Q.26 Hispanic – Yes / No

Q.22 Conservative / Middle-of-the-road / Liberal

Q.28 Party – Republican / Democrat / Independent

Q.29 Voter History – Newly registered / Repeat voter

2) Edit (or cut and paste) the banner request to get each item on a separate line.

Q.B Male

Female

Q.24

25-34

35-54

55+ Q.21

High school grad or less

Some college, trade school

College grad+ Q.26 Hispanic Yes

Q.22

Conservative

Middle-of-the-road

Liberal Q.28 Party Republican Democrat Independent

Q.29 Voter History Newly registered Repeat voter

3) Add a total column, change question numbers into question text, add level designators. Level 2’s provide the titles that span across level 1 banner points.

[LEVEL=1] Total

[LEVEL=2] Gender

[LEVEL=1] Male

[LEVEL=1] Female

[LEVEL=2] Age

[LEVEL=1] 25-34

[LEVEL=1] 35-54

[LEVEL=1] 55+

[LEVEL=2] Education

[LEVEL=1] High school grad or less

[LEVEL=1] Some college, trade school

[LEVEL=1] College grad+

[LEVEL=2] Hispanic

[LEVEL=1] Yes

[LEVEL=1] No

[LEVEL=2] Think of Yourself As…

[LEVEL=1] Conservative

[LEVEL=1] Middle-of-the-road

[LEVEL=1] Liberal

[LEVEL=2] Party

[LEVEL=1] Republican

[LEVEL=1] Democrat

[LEVEL=1] Independent

[LEVEL=2] Voter History

[LEVEL=1] Newly registered

[LEVEL=1] Repeat voter

4) (Optional) Count the level 1 items. This is used to confirm the number of banner points and to determine the column_width, stub_width and page_width.

[LEVEL=1] Total ” 01

[LEVEL=2] Gender

[LEVEL=1] Male ” 02

[LEVEL=1] Female ” 03

[LEVEL=2] Age

[LEVEL=1] 25-34 ” 04

[LEVEL=1] 35-54 ” 05

[LEVEL=1] 55+ ” 06

[LEVEL=2] Education

[LEVEL=1] High school grad or less ” 07

[LEVEL=1] Some college, trade school ” 08

[LEVEL=1] College grad+ ” 09

[LEVEL=2] Hispanic

[LEVEL=1] Yes ” 10

[LEVEL=1] No ” 11

[LEVEL=2] Think of Yourself As…

[LEVEL=1] Conservative ” 12

[LEVEL=1] Middle-of-the-road ” 13

[LEVEL=1] Liberal ” 14

[LEVEL=2] Party

[LEVEL=1] Republican ” 15

[LEVEL=1] Democrat ” 16

[LEVEL=1] Independent ” 17

[LEVEL=2] Voter History

[LEVEL=1] Newly registered ” 18

[LEVEL=1] Repeat voter ” 19

5) Put these lines in a banner tabset adding appropriate tabset items like:

an edit statement specifying -coltna, a column width and a stub width

a column statement (where every level 1 item has a corresponding column and response description)

Use these banner options:

MAKE_BANNER (make a banner for me)

FILL_TO_LEVEL=2 (this is a two level banner)

AUTO_COLSPAN (span each level 1 with the specified level 2)

Run this setup using the ~SET PREVIEW_TITLES option.

6) Look at the print file created and make any adjustments necessary to the banner tabset specs. For example, use \n to force word breaks. Note that \n only forces word breaks in the print file and not the html file or delimited file.

[LEVEL=1] Total ”01

[LEVEL=2] Gender

[LEVEL=1] Male ”02

[LEVEL=1] Female ”03

[LEVEL=2] Age

[LEVEL=1] 25-34 ”04

[LEVEL=1] 35-54 ”05

[LEVEL=1] 55+ ”06

[LEVEL=2] Education

[LEVEL=1] High school grad or less ”07

[LEVEL=1] Some col\nlege, trade school ”08

[LEVEL=1] Col\nlege grad+ ”09

[LEVEL=2] Hispanic

[LEVEL=1] Yes ”10

[LEVEL=1] No ”11

[LEVEL=2] Think of Yourself As…

[LEVEL=1] Con\nserva\ntive ”12

[LEVEL=1] Middle\n-of-\nthe-\nroad ”13

[LEVEL=1] Lib\neral ”14

[LEVEL=2] Party

[LEVEL=1] Repub\nlican ”15

[LEVEL=1] Demo\ncrat ”16

[LEVEL=1] Inde\npen\ndent ”17

[LEVEL=2] Voter History

[LEVEL=1] Newly regis\ntered ”18

[LEVEL=1] Repeat voter ”19

7) Look at the print file created and add dashes to hyphenate words in the banner where desired.

[LEVEL=1] Total ”01

[LEVEL=2] Gender

[LEVEL=1] Male ”02

[LEVEL=1] Female ”03

[LEVEL=2] Age

[LEVEL=1] 25-34 ”04

[LEVEL=1] 35-54 ”05

[LEVEL=1] 55+ ”06

[LEVEL=2] Education

[LEVEL=1] High school grad or less ”07

[LEVEL=1] Some col-\nlege, trade school ”08

[LEVEL=1] Col-\nlege grad+ ”09

[LEVEL=2] Hispanic

[LEVEL=1] Yes ”10

[LEVEL=1] No ”11

[LEVEL=2] Think of Yourself As…

[LEVEL=1] Con-\nserva-\ntive ”12

[LEVEL=1] Middle\n-of-\nthe-\nroad ”13

[LEVEL=1] Lib-\neral ”14

[LEVEL=2] Party

[LEVEL=1] Repub-\nlican ”15

[LEVEL=1] Demo-\ncrat ”16

[LEVEL=1] Inde-\npen-\ndent ”17

[LEVEL=2] Voter History

[LEVEL=1] Newly regis-\ntered ”18

[LEVEL=1] Repeat voter ”19

8) (Optional) Add stats letters to level 1 items. This is used to assign stats= values for stats testing.

[LEVEL=1] Total ”01 A

[LEVEL=2] Gender

[LEVEL=1] Male ”02 B

[LEVEL=1] Female ”03 C

[LEVEL=2] Age

[LEVEL=1] 25-34 ”04 D

[LEVEL=1] 35-54 ”05 E

[LEVEL=1] 55+ ”06 F

[LEVEL=2] Education

[LEVEL=1] High school grad or less ”07 G

[LEVEL=1] Some col-\nlege, trade school ”08 H

[LEVEL=1] Col-\nlege grad+ ”09 I

[LEVEL=2] Hispanic

[LEVEL=1] Yes ”10 J

[LEVEL=1] No ”11 K

[LEVEL=2] Think of Yourself As…

[LEVEL=1] Con-\nserva-\ntive ”12 L

[LEVEL=1] Middle\n-of-\nthe-\nroad ”13 M

[LEVEL=1] Lib-\neral ”14 N

[LEVEL=2] Party

[LEVEL=1] Repub-\nlican ”15 O

[LEVEL=1] Demo-\ncrat ”16 P

[LEVEL=1] Inde-\npen-\ndent ”17 Q

[LEVEL=2] Voter History

[LEVEL=1] Newly regis-\ntered ”18 R

[LEVEL=1] Repeat voter ”19 S

9) Add remaining banner tabset items like:

statistics weights

10) (Optional) Add ~SET statements to create a delimited and an html file.

11) If you use dashes to hyphenate words in the banner, then those dashes also go to the delimited file and the html file.

If you are creating a delimited file and an html file from these same banner specs then use \k(p) to add dashes to the print file only. Use \k(p,h,d) to resume sending characters to all 3 files.

[LEVEL=1] Total ”01

[LEVEL=2] Gender

[LEVEL=1] Male ”02

[LEVEL=1] Female ”03

[LEVEL=2] Age

[LEVEL=1] 25-34 ”04

[LEVEL=1] 35-54 ”05

[LEVEL=1] 55+ ”06

[LEVEL=2] Education

[LEVEL=1] High school grad or less ”07

[LEVEL=1] Some col\k(p)-\k(p,h,d)\nlege, trade school ”08

[LEVEL=1] Col\k(p)-\k(p,h,d)\nlege grad+ ”09

[LEVEL=2] Hispanic

[LEVEL=1] Yes ”10

[LEVEL=1] No ”11

[LEVEL=2] Think of Yourself As…

[LEVEL=1] Con\k(p)-\k(p,h,d)\nserva\k(p)-\k(p,h,d)\ntive ”12

[LEVEL=1] Middle\n-of-\nthe-\nroad ”13

[LEVEL=1] Lib\k(p)-\k(p,h,d)\neral ”14

[LEVEL=2] Party

[LEVEL=1] Repub\k(p)-\k(p,h,d)\nlican ”15

[LEVEL=1] Demo\k(p)-\k(p,h,d)\ncrat ”16

[LEVEL=1] Inde\k(p)-\k(p,h,d)\npen\k(p)-\k(p,h,d)\ndent ”17

[LEVEL=2] Voter History

[LEVEL=1] Newly regis\k(p)-\k(p,h,d)\ntered ”18

[LEVEL=1] Repeat voter ”19

12) (Optional) Or use >define @d \k(p)-\k(p,h,d).

[LEVEL=1] Total ”01

[LEVEL=2] Gender

[LEVEL=1] Male ”02

[LEVEL=1] Female ”03

[LEVEL=2] Age

[LEVEL=1] 25-34 ”04

[LEVEL=1] 35-54 ”05

[LEVEL=1] 55+ ”06

[LEVEL=2] Education

[LEVEL=1] High school grad or less ”07

[LEVEL=1] Some col@d\nlege, trade school ”08

[LEVEL=1] Col@d\nlege grad+ ”09

[LEVEL=2] Hispanic

[LEVEL=1] Yes ”10

[LEVEL=1] No ”11

[LEVEL=2] Think of Yourself As…

[LEVEL=1] Con@d\nserva@d\ntive ”12

[LEVEL=1] Middle\n-of-\nthe-\nroad ”13

[LEVEL=1] Lib@d\neral ”14

[LEVEL=2] Party

[LEVEL=1] Repub@d\nlican ”15

[LEVEL=1] Demo@d\ncrat ”16

[LEVEL=1] Inde@d\npen@d\ndent ”17

[LEVEL=2] Voter History

[LEVEL=1] Newly regis@d\ntered ”18

[LEVEL=1] Repeat voter ”19

The MAKE_BANNER option uses features (background color, font size, font type, font color) set in a WEB_FORMAT_BANNER statement to affect the appearance of the html file.

The MAKE_BANNEWR option uses features (background color, font size, font type, font color) set in a style sheet file and referenced by a class statement associated with the banner to affect the appearance of the html file.

13) (Optional) Add any extra desired banner features like:

UNDERLINE_LEVEL(1)== (change level one underlining to equal signs)

UNDERLINE_LEVEL(2)=- (change level two underlining to dashes)

JUSTIFY_LEVEL(1)=LEFT (left-justify level one items)

JUSTIFY_LEVEL(2)=RIGHT (right-justify level two items)

14) After final review of print the banner, delimited banner and html banner, remove ~SET PREVIEW_TITLES. Add the name of the .tr and the .def file when available.

4.10 DEFINING INDIVIDUAL TABLES

Stub table sets include definitions for the table title, stub labels, data row variable, and EDIT statements. It can also include LOCAL_EDIT statements, a base, base title, and possibly SET commands for additional control.

Here is an simple stub table set:

TABLE_SET= {Q1:

TITLE={:

Q1. What is your favorite month of the year?

}

STUB={:

January

February

March

April

May

June

July

August

September

October

November

December

}

ROW=: [6^1//12]

}

Here is a more detailed explanation of the table elements defined in this example.

TITLE= Instructs Mentor to print this text as the main table title. It prints below the table name

and prior to the banner text. The EDIT keyword, RUNNING_LINES, controls how this text will

print across the top of the page. The default is to print text as written. RUNNING_LINES=1

will print as much text can be fit across the page before going to a new line. See “5.3

CHANGING TABLE SPECIFICATIONS, Print Options” for more on RUNNING_LINES. An example table

in that section shows the print positions for other table titling.

Table titling elements follow the same rules and have the same options as ~DEFINE LINES.

Within the TABLE_SET they are assigned to a specific table element with the appropriate

keyword.

STUB= Defines the stub labels for each data row printed on your table. Excluding stubs marked as

[COMMENT] or [PRINT_ROW] labels, the number of labels must match the number of data

categories defined in your row variable. (see “Appendix B: TILDE COMMANDS, ~DEFINE EDIT”

options EXTRA_STUBS_OK and EXTRA_ROWS_OK and ~SET TABLE_SET_MATCH_ERROR/WARN).

ROW= Assigns an axis or data variable definition as the table row. See “4.6 DEFINING DATA” for

the rules on defining data variables. These rules will apply to any data variable

regardless of what table element you will assign it to, i.e., COLUMN, BASE, FILTER,

ROW_WEIGHT. See “Appendix B: TILDE COMMANDS, ~DEFINE AXIS” for the additional rules

regarding axis definition for COLUMN= and ROW= specification or axis-only definitions.

HOW TO ADD RANKING TO A TABLE

If you want to rank a table so the stub items are ranked from high to low, then add the KEEP_RANK option (abbreviated KR) to the STUB keyword, as follows:

TABLE_SET= {Q1:

TITLE={:

Q1. What is your favorite month of the year?

}

STUB={:

[KR=1] January

February

March

April

May

June

July

August

September

October

November

December

}

ROW=: [6^1//12]

}

KR=1 (or KEEP_RANK=1) means to rank this and subsequent stubs at a rank level of one (until a new

rank level is indicated). You use up to ten rank levels (0-9), and the default is to rank

from high to low.

To rank tables, you must also add the RANK_IF_INDICATED option to your EDIT statement.

HOW TO ADD A BASE TO A TABLE

A base is a way to include only a subset of a sample. For example:

TABLE_SET= {Q1:

BASE=: [5^3]

TITLE_4={: BASE: Respondents who own dogs

}

TITLE={: Q1. What is your favorite month of the year?

}

STUB={:

[KR=1] January

February

March

April

May

June

July

August

September

October

November

December

}

ROW=: [6^1//12]

}

Here are the new elements:

BASE= Defines a base for this table. Only those respondents meeting the data criteria defined

here will be included in this table. In this example, only those respondents who had a

three punch in column five are included in the table. You can also use FILTER to describe

an additional data criteria for a set of tables.

TITLE_4= Prints below the text defined on TITLE=, is often used to describe a base or additional

considerations on a table.

HOW TO ADD SUMMARY STATISTICS TO A TABLE

Mentor makes it easy to add summary statistics, such as means, standard deviations, and standard errors to your tables. It requires adding the STATISTICS_ROW option to the stub command, and having the statistic defined as a part of the row variable.

Here is a simple example:

TABLE_SET= {Q5:

TITLE={:

Q5. ALL THINGS CONSIDERED, HOW SATISFIED OR

DISSATISFIED WERE YOU WITH THE WAY COMMUNITY GENERAL HANDLED YOUR STAY THERE?

WOULD YOU SAY YOU WERE VERY SATISFIED, SOMEWHAT SATISFIED, SOMEWHAT DISSATISFIED OR VERY DISSATISFIED?\N

}

STUB={:

4-VERY SATISFIED

3-SOMEWHAT SATISFIED

2-SOMEWHAT DISSATISFIED

1-VERY DISSATISFIED

DON’T KNOW/REFUSED

[STAT] MEAN

[STAT] STANDARD DEVIATION

}

ROW=: [47^4/3/2/1/0] $[MEAN,STD] [47*RANGES=1-4]

}

STAT (or STATISTICS_ROW) Controls printing on the row. This identifies this as a statistics

row, so it will print only the frequencies and not percentages. (To control the number

of decimals on the frequencies, use the EDIT option STATISTICS_DECIMALS.) Various stub

options are covered in “5.3 CHANGING TABLE SPECIFICATIONS, Row Print Options”. A complete

list can be found in Appendix B: TILDE COMMANDS,~DEFINE STUB=”.

$[MEAN,STD] The list of statistics you want to include in the row.

[47*RANGES=1-4] If all the answers to the question were numeric, you could just put the column location

[47] as the row definition. But in this case, the Don’t Know/Refused answer was coded as a

number, so including it will make the mean wrong (the mean will be much too high if the

Don’t Know/Refused was coded as a 99!). Using the RANGES modifier only includes answers one

through four, and therefore eliminates the Don’t Know/Refused answer from the mean.

For more information, Chapter 6 has several examples of how to add means and medians to your tables and Chapter 7 shows you how to do tests dealing with statistical significance, such as T-tests, chi square tests, and ANOVA tests.

4.11 SAMPLE SPECIFICATION FILES

What follows are sample specification files. First is an example of how to save elements to a DB file, then “real world” specs from the Roadrunner’s Pizza study, and then, finally, specs that can make tables with complex banners process more quickly.

USING THE DB FILE

When you have job specifications that will be used in several jobs, or a job with multiple sections that have common elements, you may wish to store the common elements in a DB file. You can then call these elements by name in a later run. For instance, if your project calls for multiple banners, the EDIT statement associated with each banner can be simplified by storing those parts of the EDIT statement that will remain constant to a DB file. You can then reference that DB file entry in each banner TABLE_SET. In this way, EDITs can be developed for different clients or different presentation requirements, stored, and called in when needed.

When Mentor creates tables, the program automatically creates and stores elements in a local database file that is automatically removed at the end of a run. If you want to have your own permanent database file, you can write a small spec file to create DB elements, or include these commands in your larger spec file. First, you must create a DB file with the meta command >CREATE_DB. Enter:

>CREATE_DB edit1

Use the >FILE_TO_DB meta command to put items from the EDIT statement into the DB file. The basic syntax is:

>FILE_TO_DB name #

“Name” can be any string up to 14 characters, including underscores (_) and periods (.). The pound sign (#) means to read all the items until Mentor encounters an >END_OF_FILE command.

EX:

>FILE_TO_DB edit_standard #

-COLUMN_TNA

-VERTICAL_PERCENT=AR

-PERCENT_DECIMALS=1

-PERCENT_SIGN

-STATISTICS_DECIMALS=2

CALL_TABLE=””

RUNNING_LINES=1

STAR_PERCENT=0

TCON=(-TABLE_NAMES,PRINT_PAGE_NUMBERS,

-TCON_PAGE_NUMBERS,-TITLE_2)

PUT_CHARACTERS=—

>END_OF_FILE

Now, “edit_standard” is a DB item stored in the DB file called edit1. You can access “edit_standard” for any banner by first opening the DB file and then accessing the db item on the EDIT keyword in the TABLE_SET.

>USE_DB edit1 ”meta command that opens the DB

”file created earlier

TABLE_SET= {BAN1:

EDIT={:

COLUMN_WIDTH=6

STUB_WIDTH=21

COLUMN_INFO=(C=8 W=7/C=9 W=7/C=10 W=7)

&&EDITSTANDARD ”double ampersand (&&) gets

”item from DB file

}

BANNER={:

| CITY SEX

| =========== ========== AGE Q1. BEST NAME

| DEN- DAL- FE- =========== ====================

| TOTAL VER LAS MALE MALE 18-34 35+ CHOICE SELECT SOURCE

| —– —- —- —- —- —– —– —— —— ——

}

COLUMN=: TOTAL WITH &

[5^1/2] WITH & ”city

[6#M/F] WITH & ”sex

[65^1,2/3,4] WITH & ”age

[16^1//3] ”q1

}

NOTE: COLUMN_WIDTH, STUB_WIDTH, and COLUMN_INFO have been specified separately in the EDIT statement since these items would typically change for each banner. Remember, the last occurrence of an option in the EDIT statement supersedes any prior occurrence of the same option.

PUTTING IT ALL TOGETHER

So far in this chapter, we have covered the parts of table, how to define data variables, banner tabset, and stub tabsets. Now, let’s put all that knowledge together. First, let’s take advantage of Mentor’s ability to “call in” one file from another. In the main spec file (which we’ll give the extension SPX), we’ll put the META commands, the SET commands, the banner tab set, the INPUT command, and EXECUTE commands, and call a separate file that contains all the individual question information (the stub tab sets). Below is a sample SPX file, a sample DEF file, and the tables they create.

To have Mentor call in the specs from another file, put an ampersand in front of the file name. To read a file that has the DEF extension, you could put in the line

&filename.DEF

If your DEF file is the name of your study and you have defined the study name with the >DEFINE command, then you can use:

&@STUDY~^DEF

This reads in a file, in this case the file containing your table definitions. If you have Survent, the DEF file has already been generated for you based on your Survent questionnaire specifications.

NOTE: When you use a caret (^) before the file extension, Mentor reads this as a period (.) on DOS or UNIX platforms, and as nothing in MPE, so you could use your specification file on DOS, UNIX or MPE without modifying it. The tilde mark (~) acts as a delimiter for user-defined variables. This means you can append letters and/or numbers to the STUDY name, for example, with the STUDY variable defined as “sample”, &@STUDY~2^DEF would open the file SAMPLE2.DEF.

Sample specification files are provided with your Mentor software to run the example tables discussed in this section. The files are located in either \CFMC\Mentor\ROADRUNR (DOS and UNIX ) or ROADRUNR.CFMC (MPE). Following is the entire TABS.SPX file:

>ALLOW_INDENT

>PURGE_SAME

>DEFINE @STUDY rrunr

~INPUT @STUDY~,ALLOW_UPDATE,MAYBE_BACKUP,DOTS=100

>PRINT_FILE @STUDY~

>CREATE_DB @STUDY~1,DUPLICATE=WARN

~COMMENT

This is part of the Road Runner Study.

~SPEC_FILES @STUDY~

~DEFINE

TABLE_SET={global:

SET AUTOMATIC_TABLES

HEADER={: =Road Runner Fast Food Test Tables

Prepared on #date# }

FOOTER{: =Tables prepared by Computers for Marketing Corp.

Page #page_number# }

}

TABLE_SET={banner1:

SET AUTOMATIC_TABLES

HEADER=: =Road Runner Fast Food Sample Tables

Prepared on #date# }

FOOTER=: =Tables prepared by Computers for Marketing Corp.

Page #page_number# }

EDIT=: -COLUMN_TNA, -ROW_NA, PERCENT_DECIMALS=0,

STATISTICS_DECIMALS=2,

COLUMN_WIDTH=7, STUB_WIDTH=40,

RUNNING_LINES=1,

TCON=(-TABLE_NAMES,PRINT_PAGE_NUMBERS, &

-TCON_PAGE_NUMBERS, -FOOTER)

BANNER=:

| <——-AGE——-> <—–INCOME——> <–RATING–>

| Neu-

| Under Over Under $15- Over tral/

| Total 35 35-54 54 $15k $35k $35k Good Poor

| —– —– —– —- —– —– —- —– —- }

COLUMN=: TOTAL WITH & [1/51^1,2/3,4/5,6] WITH &

[1/52^1/2,3/4,5,6] WITH &

[1/47^4,5/1,2,3]

}

&@STUDY^DEF

~INPUT @STUDY~

~EXECUTE

MAKE_TABLES

~END

Here are each of the lines of the spec file explained:

>PURGE_SAME

Purges same-named files. The default is to alpha-kick the first letter of the file name of the older file.

>ALLOW_INDENT

Allows indentation of meta commands; by default they must start in column 1 of the specification file.

>DEFINE @STUDY rrunr

Allows you to create user-defined variables to substitute a file name or to execute a command. In this case >DEFINE assigns the variable, @STUDY, to the file name, RRUNR. Wherever the file name RRUNR would normally appear, @STUDY is substituted. By replacing references to a particular file name with a variable, we can substitute a different file name for the same variable throughout a standardized specification file by specifying a new name on this line. We will make use of this command in the TABS.SPX file.

~INPUT @STUDY~,ALLOW_UPDATE,MAYBE_BACKUP,DOT=100

Loads the data file but allows you to modify it with the keyword ALLOW_UPDATE. MAYBE_BACKUP creates a copy (TRX) if one does not exist, preserving the original data file. DOT=100 will print a dot to the screen for every 100 cases read. We will be generating and storing new data for the banner. The tilde mark (~) acts as a delimiter between user-defined keywords.

>CREATE_DB @STUDY~1,DUPLICATE=WARN

This line creates the db file. We are calling the DB file “study1” to make sure it doesn’t write over an existing DB file that could have been generated from a Survent compile. Everything defined in the ~DEFINE block and all the tables built in the ~EXECUTE block will be stored in this DB file. The tilde character (~) after @STUDY~ is a delimiter. The tilde delimiter allows you to include options after the defined keyword name. DUPLICATE=WARN prints a warning every time an existing item is replaced in the file.

The DB file is a machine readable file, which means you cannot view or edit it in a word processing program. (Use the utility DBUTIL to look at the items in a DB file; see the Utilities manual.) It is an efficient way to store items generated by Mentor that you might want to use again. For instance, tables can be stored in a DB file. If you needed to reprint some or all of them to change the format, correct an error in the text, or add statistics rows you could instruct Mentor to look up the tables in the DB file and reprint them, without forcing the program to process the data file again for each table.

Table components such as stub labels, other text, and print options are already stored as a single entry in the DB file that Mentor can retrieve easily.

DB files are NOT REQUIRED for you to tabulate your data, but they do provide a way to store items that you might want to use again.

~COMMENT

Any text following this tilde command is considered a spec file comment and is not executed by Mentor. Everything is ignored until the next tilde command.

~SPEC_FILES @STUDY~

This creates Mentor-generated TAB and LPR files.

~DEFINE TABLE_SET={global:

Defines the initial TABLE_SET. As you saw in 4.3 DEFINING TABLE ELEMENTS, the TABLE_SET structure can be used to define table elements that will control all the tables in a particular run such as SET commands, headers, footers, edit statement, banner text, and the column variable. You could define these individually, but this would require re-specifying each varname on its corresponding ~EXECUTE keyword. By defining them inside a TABLE_SET you eliminate this extra step since TABLE_SET= automatically causes the correct ~EXECUTE specification to be written to the program-generated TAB file (see ~SPEC_FILES).

The global and banner TABLE_SETs are defined before the file containing the stub TABLE_SETs (RRUNR^DEF) is read in. That is because we want them in effect for all the tables made.

SET AUTOMATIC_TABLES

Tells program to make tables from the elements specified whenever a ROW variable is seen.

HEADER={ :=Road Runner Fast Food Test
Tables Prepared on #date# }

Defines the text that will print as the header on each table. The equal sig (=) n centers the text, #date# prints the date in the format MM DD 19YY. (see Appendix B: TILDE COMMANDS, ~DEFINE LINES= to print system #time# or #table_name# anywhere in the table titling). The lines will print centered for the page width. RUNNING_LINES=1 will not affect these titles, so two lines will print.

FOOTER{ :=Tables prepared by Computers for Marketing Corp.
Page #page_number# }

Defines the text that will print as the footer on each table. The equal sign (=) centers the text, #page_number# prints the page number.

}

Ends this TABLE_SET definition.

EDIT={: -COLUMN_TNA -ROW_NA PERCENT_DECIMALS=0
STATISTICS_DECIMALS=2
COLUMN_WIDTH=7 STUB_WIDTH=40
RUNNING_LINES=2
TCON=(-TABLE_NAMES,PRINT_PAGE_NUMBERS, &
-TCON_PAGE_NUMBERS, -FOOTER)

This is the main EDIT statement that will control the format of the printed tables. There are several new keywords not previously mentioned:

-COLUMN_TNA

Suppresses printing of the default system-generated Total and No Answer summary columns.

-ROW_NA

Suppresses printing of the default system-generated No Answer summary row.

PERCENT_DECIMALS=0

Prints percents with zero decimal places. The default is one decimal place.

STATISTICS_DECIMALS=2

Prints two decimal places on statistics rows. The default is one decimal place. This sample table run utilizes the DEF file made from PREPARE question specifications compiled with ~PREPARE COMPILE Mentor_SPECS. The default is to generate statistics specifications for NUM questions. See 5.1 Expressions and Joiners for details on defining expressions.

COLUMN_WIDTH=7

Controls the width of table columns; the default is eight.

STUB_WIDTH=40

Controls the width of table stubs; the default is 20.

RUNNING_LINES=2

Controls how the table titles, header, and footer will print. The default is RUNNING_LINES=0, which prints the lines exactly as defined. RUNNING_LINES=1 will wrap the lines according to the PAGE_WIDTH setting (or default) and any INDENT (indents the whole table either by number specified (greater than 0) or the keyword CENTER). RUNNING_LINES=2 means print the first line like RUNNING_LINES=1, then indent the second and subsequent lines by the length of the first word (from the first line) and any blanks immediately following, in addition to any INDENT specified. This keyword is useful when you want to set the question number off from the rest of the title text.

RUNNING_LINES=1 or 2 is overridden if you specify a position character before the text: = to center, > to right-justify, or < to left-justify (default) all lines of text. See the definitions for HEADER= and FOOTER= for examples.

TCON

Prints a table of contents at the end of the print file. You can control what prints in the table of contents. Headers, footers, and all titles except TITLE_5 print by default; you can suppress any of these. You can indent text with the keyword INDENT=#; the default is zero (0), do not indent. You must use an ampersand (&) to continue the TCON= specification to another line. Justification commands (< to left-justify; > to right-justify; and = to center) specified in titling do not affect how text is printed in the table of contents.

-TABLE_NAMES Suppresses printing of the table name, e.g., T0002.

PRINT_PAGE_NUMBERS Prints the page number.

-TCON_PAGE_NUMBERS Suppresses the table of contents page number that prints at the top of

each table of contents page.

-FOOTER Suppresses printing of the footer in the table of contents.

BANNER=:

| <——-AGE——-> <—–INCOME——> <–RATING–>

| Neu-

| Under Over Under $15- Over tral/

| Total 35 35-54 54 $15k $35k $35k Good Poor

| —– —– —– —– —- —- —- —– —- }

BANNER= defines the banner labels. Banner text formatting controls were explained in 4.8 FORMATTING BANNER TEXT.

&@STUDY~^DEF

Reads in the table definitions file either generated when PREPARE specifi- cations were compiled with ~PREPARE COMPILE Mentor_SPECS or written by you.

EDIT_DUMP

A debugging tool, prints the edit options in effect for each table.

MULTIPLE_WEIGHT_STATISTICS

Allows T-tests using the STATISTICS= keyword on tables that have different weights on some columns.

STATISTICS_BASE_AR

Sets the standard base for the T-tests executed by the table using the STA- TISTICS keyword to be the Any Response System row, rather than the Total row (the default).

~INPUT @STUDY~

Opens the data file RRUNR^TR.

~EXECUTE

This is the block where you execute tables or procedures against the data file.

MAKE_TABLES

This option builds and prints the tables. As explained earlier in 4.4 TABLE BUILDING, when you use SET AUTOMATIC_TABLES, Mentor table building is triggered by the ROW= command. All of the table elements either specified before the ROW= variable or defined in the same TABLE_SET are in effect for that table. The EXECUTE command MAKE_TABLES builds and prints each table. MAKE_TABLES actually executes three separate commands: BUILD_TABLES, RESET, and PRINT_RUN, These commands utilize program-generated files created with the ~SPEC_FILES command to read and store each TABLE_SET definition, reset all table elements, then print the tables either to the open print file or list file.

SAMPLE TABLE

Road Runner Fast Food Sample Tables

Prepared on 18 MAR 2012

TABLE 001

Q1. How much do you agree with the following statement:

The fast food at Road Runners is worth what I pay for it.

<——-AGE——-> <——INCOME—–> <–RATING–>

Neu-

Under Over Under $15- Over tral/

Total 35 35-54 54 $15k $35k $35k Good Poor

—– —– —– —- —– —– —- —- —-

Total 500 141 140 143 74 148 214 166 247

100% 100% 100% 100% 100% 100% 100% 100% 100%

(5) Completely agree 88 21 29 23 10 30 36 26 51

18% 15% 21% 16% 14% 20% 17% 16% 21%

(4) Somewhat agree 92 26 27 27 14 30 35 29 42

18% 18% 19% 19% 19% 20% 16% 17% 17%

(3) Neither agree nor 86 23 26 24 13 22 45 27 42

disagree 17% 16% 19% 17% 18% 15% 21% 16% 17%

(2) Somewhat disagree 73 13 23 21 13 21 33 27 34

15% 9% 16% 15% 18% 14% 15% 16% 14%

(1) Completely disagree 86 29 17 26 8 27 37 22 49

17% 21% 12% 18% 11% 18% 17% 13% 20%

Don’t Know/Refused to 75 29 18 22 16 18 29 35 29

answer 15% 21% 13% 15% 22% 12% 13% 21% 12%

Mean 3.05 2.97 3.23 3.00 3.09 3.12 3.00 3.08 3.06

Standard deviation 1.42 1.47 1.37 1.43 1.32 1.47 1.40 1.38 1.48

Standard error 0.07 0.14 0.12 0.13 0.17 0.13 0.10 0.12 0.10

Tables prepared by Computers for Marketing Corp.

Page 1

Road Runner Fast Food Test Tables

Prepared on 18 MAR 2012

T A B L E O F C O N T E N T S

P. 1 Q1. How much do you agree with the following statement:

The fast food at Road Runners is worth what I pay for it.

DEFINING A PROCEDURE FOR COMPLEX BANNERS

The most basic use of the DEFINE command is to define variables, for example:

~DEFINE

Banvar[1/80^1//9]

Then you can reference the variable later in the same spec file:

COLUMN=Banvar

As you saw in the cleaning chapter, you can also use the DEFINE statement to define procedures. You can use this capability to define elements when you have complex tables. For example, you can use DEFINE to generate and store banner data under a simple punch data variable. This is effective if you have a very complex banner or many rows. If you define the column variable or expression with TABLE_SET, Mentor will have to generate the horizontal axis for each table during the build and print phase. Using DEFINE will speed processing of the data file. Here are lines we would add to the previous Roadrunner spec file:

~DEFINE

Age[1/51^1,2/3,4/5,6]

Income[1/52^1/2,3/4,5,6]

Rating[1/47^4,5/1,2,3]

Banexpr: TOTAL WITH Age WITH Income WITH Rating

Banvar[1/80^1//9]

PROCEDURE= {make_ban:

MODIFY banvar = banexpr

DO_TABLES }

And later, in the EXECUTE block:

~EXECUTE

READ_PROCEDURE=MAKE_BAN

Here we defined the three data variables that will form an expression for the tables’ column variable.

NOTE: No colon is needed after the varname since these are simple variables containing no joiners or functions. It is not necessary for you to pre-define the variable components of an expression, but it is easier to reference them later by their variable names rather than retyping the definition. Here is each line described in detail:

Banexpr: TOTAL WITH Age WITH Income WITH Rating

Defines an expression connecting all the categories from the data variables referenced by AGE, INCOME, and RATING. In BANEXPR a user-defined Total column is created with the Mentor constant, TOTAL. Program-generated Total and No Answer columns will be suppressed at print time and replaced by this total. Since we want Total to be the first column printed in the table banner, it is specified at the beginning of the expression.

Banvar[1/80^1//0]

Defines a new data variable for the nine categories created by BANEXPR: 1 for Total, 3 for Age, 3 for Income and 2 for Rating. The data will be stored in column 80 of record 1 of the RRUNR data file (TR) which is currently blank. Note that BANVAR is defined as a punch data variable. Two slashes (//) define nine separate but consecutive categories.

PROCEDURE=

The ~DEFINE block keyword that allows you to perform some operation on every case in the data file or specified subset.

{make_ban:

The name of the procedure.

MODIFY banvar = banexpr

A CLEANER command that modifies data. In this case the result of the expression BANEXPR will replace the data in BANVAR, blanking the categories first. See Mentor Appendix B: TILDE COMMANDS, ~CLEANER for more information.

DO_TABLES

Another ~CLEANER command. DO_TABLES allows you to make data modifications for the printed tables without changing the input data file. This way, Mentor only has to check in one place to read a complicated expression, and it speeds processing. A DO_TABLES procedure is executed with the ~EXECUTE keyword READ_PROCEDURE.

}

Ends the procedure.

READ_PROCEDURE=MAKE_BAN

This keyword will execute the DO_TABLES procedure defined above.

4.12 USING Survent TO GENERATE Mentor SPECIFICATION FILES

You can use Survent questionnaire specifications to produce two table building specification files, ready to be used by Mentor, called the DEF file and the TAB file. You can use the ~PREPARE COMPILE Mentor_SPECS command or CfMC’s menu-assisted EZWriter application to create these files. The DEF file contains the syntax to define a table for each question and the TAB file contains the commands to build the tables defined in the DEF file. The DEF file can also be edited to add basing, weights, statistics, print format controls, etc. The TAB file can be remade by Mentor to reflect any changes to the DEF file. Refer to 4.11 SAMPLE SPECIFICATION FILES for details on using these files to make tables. All examples refer to the RRUNR sample specification files included with your Mentor software.

Refer to 2.2.1 FILES CREATED BY Survent in your Survent manual for more information on the DEF and TAB files.

Here is a basic specification file followed by examples of the DEF, TAB and LPR files, and then the table they created. For the purposes of this example we used a converted Survent variable stored in the DB file, RRUNR.DB. In 4.6 DEFINING DATA, you can see the rules to define data variables in general and how to join data variables to form a complex banner. 4.8 FORMATTING BANNER TEXT covers how to format the banner text.

>PURGE_SAME

>DEFINE @STUDY rrunr

>PRINT_FILE @STUDY~

>USE_DB @STUDY~ ”opens the DB file for access to a converted Survent variable.

~SET AUTOMATIC_TABLES

~SPEC_FILES @STUDY~

~DEFINE

EDIT={defedt: -COLUMN_NA, -ROW_NA, COLUMN_WIDTH=8,

RUNNING_LINES=1, TCON

}

&@STUDY~^DEF ”this calls in the RRUNR.DEF file

~INPUT @STUDY~

~EXECUTE

COLUMN=qn21 ”is the converted Survent variable for respondent sex assigned as the

”table column. Mentor will generate banner labels from this variable’s text.

EDIT=defedt

MAKE_TABLES

~END

&@STUDY~^DEF reads in RRUNR^DEF which contains the definitions for each table. Here is the section of the definition file for the example table printed below. See 4.3 DEFINING TABLE ELEMENTS and 4.6 DEFINING DATA for details on defining tables and data variables.

TABLE_SET= { qn1_z:

TITLE=:

Q1. How much do you agree with the following statement:

The fast food at Road Runners is worth what I pay for it.}

STUB=:

(5) Completely agree

(4) Somewhat agree

(3) Neither agree nor disagree

(2) Somewhat disagree

(1) Completely disagree

Don’t Know/Refused to answer }

ROW=: [1/6^5//1/10]

}

MAKE_TABLES reads in the RRUNR^TAB and the RRUNR^LPR files. RRUNR.TAB has a list of tabsets and triggers table building, for this example it would have one line:

TABSET qn1_Z

RRUNR^LPR has load and print statements for each table. For this example, it would have one line:

LOAD T001 PRINT

TABLE 001

Q1. How much do you agree with the following statement:

The fast food at Road Runners is worth what I pay for it.

Total Male Female

Total 500 263 237

100.0% 100.0% 100.0%

(5) Completely agree 88 49 39

17.6% 18.6% 16.5%

(4) Somewhat agree 92 43 49

18.4% 16.4% 20.7%

(3) Neither agree 86 48 38

nor disagree 17.2% 18.3% 16.0%

(2) Somewhat 73 36 37

disagree 14.6% 13.7% 15.6%

(1) Completely 86 43 43

disagree 17.2% 16.4% 18.1%

Don’t Know/Refused 75 44 31

to answer 15.0% 16.7% 13.1%

T A B L E O F C O N T E N T S

PAGE 1

P.1 Q1. How much do you agree with the following statement:

The fast food at Road Runners is worth what I pay for it.

Here is a list of what Mentor table building components are generated from Survent:

question label Generates the variable name for that table’s definition.

question text Generates the table title.

question type Determines the row data type.

numeric range Generates the stub label set, the row data categories and default statistics

for NUM questions.

response codes Generates the row data categories for CAT and FLD questions.

response text Generates the stub label set for CAT and FLD questions.

Here are examples of Survent specs and the Mentor tabsets Survent generates for the basic question types (CAT, NUM, FLD).

CAT QUESTION

Survent specs Mentor tabset

{ QN21: 1/57 TABSET={ qn21_z:

Q21. Respondent Sex TITLE=: Q21. Respondent Sex}

! CAT STUB=:

1 Male Male

2 Female Female }

} ”qn21(1/2)

ROW=: [1/57.1^1/2] }

For CAT questions the comment line ”qn21(1/2) indicates the Survent response codes which might differ from the corresponding punch codes found in the data for that question.

FLD QUESTION

Survent specs Mentor tabset

{status: 1/5 TABSET= { status_z:

Marital status TITLE=: Marital status}

!FLD STUB=:

M Married Married

S Single Single

W Widowed Widowed }

} ROW=: [1/5.1#M/D/S/W] }

For FLD questions, the row variable for multiple-response FLD questions defaults to the *F modifier, meaning net all responses across columns.

SURVENT SPECS

{QN11: 1/8.20

Which brands are you aware of?

!FLD,,10

01 COKE

02 COCA-COLA CLASSIC

03 NEW COKE

04 DIET COKE

05 CHERRY COKE

06 CAFFEINE FREE COKE

07 DR. PEPPER

08 REGULAR DR. PEPPER

09 DIET DR. PEPPER

10 GATORADE

11 MELLO YELLOW

12 REGULAR MELLOW YELLOW

13 OTHERS

99 DON’T KNOW }

MENTOR TABSET

TABSET= { qn11_z:

TITLE=:

Which brands are you aware of?}

STUB=:

COKE

COCA-COLA CLASSIC

NEW COKE

DIET COKE

CHERRY COKE

CAFFEINE FREE COKE

DR. PEPPER

REGULAR DR. PEPPER

DIET DR. PEPPER

GATORADE

MELLO YELLOW

REGULAR MELLOW YELLOW

OTHERS

DON’T KNOW}

”qn11(01/02/03/04/05/06/07/08/09/10/11/12/13/99)

ROW=: [1/8.2, 1/10, 1/12, 1/14, 1/16, 1/18, 1/20, 1/22,&

1/24,1/26 *f#01/02/03/04/05/06/07/08/09/10/11/12/13/99]

}

If you specify a recode table to be [SAMEAS label] or do the same in Script Composer by going to the F5 screen and filling in “Use the recode table from question__”, the DEF file will reflect that by automatically assigning that table element’s variable name to mean ‘the same as’.

MENTOR TABSET

TABSET= { qn2b_z:

TITLE=:

Q2B. Please rate the following characteristics: The quality of service.}

STUB= qn2a_s <– means use the stub variable qn2a_s.

”qn2b(5/4/3/2/1/0)

ROW=: [1/8.1^5/4/3/2/1/10]

}

NUM QUESTION

Survent specs

{ QN20: 1/55.2

Q20. How many children are in your household?

!NUM,,,0,10,,RF

}

MENTOR TABSET

TABSET= { qn20_z:

TITLE=:

Q20. How many children are in your household?}

STUB=:

0-3

4-5

6-10

[STAT] Mean

[STAT] Standard deviation

[STAT] Standard error}

ROW=: [1/55.2#0-3/4-5/6-10/”RF” ] &

$[MEAN,STD,SE] [1/55.2 *RANGES=0,10,,RF,,]

}

By default, minimum and maximum allowable values for NUM questions are broken out into one to five categories of numeric values in the DEF file depending on the difference between the high and low values:

Difference between Number of categories:

high and low values:

1 1

2-8 2

9-20 3

21-50 4

>50 5

If the difference between high and low is over 1000 then the first four categories are evenly divided with the remainder into the fifth category. The ranges are not meant to reflect any proportional divisions in the data. They are there to help you set up your own categories.

SURVENT SPECS

{house: 1/9.6

What is the current value of your home?

!NUM,,,100000-500000,,RF}

MENTOR TABSET

TABSET= { house_z:

TITLE=:

What is the current value of your home?}

STUB=

100000-100125

100126-100250

100251-100375

100376-100500

100501-500000

[STAT] Mean

[STAT] Standard deviation

[STAT] Standard error}

ROW=: [1/9.6#100000-100125/100126-100250/100251-100375/100376-100500/ &

100501-500000/”RF” ]&

$[MEAN,STD,SE] [1/9.6 *RANGES=100000,500000,,RF,,]

}

You can specify a value for exception codes to be used in calculating statistics. Using the above example, we will assign a value of zero (0) to the exception code RF in the Survent specification. This will be reflected in the *Ranges specification on the row variable.

SURVENT SPECS

{QN20: 1/55.2

Q20. How many children are in your household?

!NUM,,,0-10,,RF=0}

MENTOR TABSET

TABSET= { qn20_z:

TITLE=:

Q20. How many children are in your household?}

STUB=:

0-3

4-5

6-10

[STAT] Mean

[STAT] Standard deviation

[STAT] Standard error}

ROW=: [1/55.2 # 0-3/4-5/6-10/”RF” ] &

$[MEAN,STD,SE] [1/55.2 *RANGES=0,10,,RF=0]

}

CHANGING WHAT APPEARS IN THE DEF FILE

There are several options you can specify in your Survent questionnaire specification file that changes what goes into the DEF file. You can use the ~SPEC_RULES command, the !MISC command, backslash options and compiler commands. The backslash commands control where text appears (Survent only, Mentor only, or both) while ~SPEC_RULES, !MISC, the compiler commands have options that make general changes to the DEF file. These commands are described in detail below.

!MISC OPTION

CATEGORY_STATISTICS (CATSTATS)

Allows you to suppress statistical testing on rows that have the $[STATS=]option. Using -CATEGORY_STATISTICS will prevent statistical testing on rows other than means.

The only way to use this option is in its negative form, -CATEGORY_STATISTICS. Including CATEGORY_STATISTICS (without the minus sign) in your ~PREPARE specs does nothing.

CATEGORY_STATISTICS adds [-STATS] in front of the category part of a row variable in the DEF file.If your ~PREPARE specifications look like:

{HOURS: 72.2

!MISC -CATEGORY_STATISTICS

In a typical day, how many hours do you spend listening to the radio?

!NUM,,,1-24,,DK,VA=4 }

then the row variable for the tabset HOURS_Z will look like this in the .DEFfile:

ROW=: $[-STATS] [ 72.2 # 1-5/10-13/14-24/”DK”/”VA” ] &

$[STATS,MEAN,STD] [72.2 *RANGES=1,24,,DK,VA=4,]

If you use -CATEGORY_STATISTICS on a table that does not have a mean, no statistical tests will be run on the table, and you will get a warning similar to the following:

(WARN #5385) Table T0003 with STATS= ban1_st but no stat tests

( are you using NUMITEMS()? )

To customize the statistics written to the .DEF file, use the COLUMN_MEAN option to ~SPEC_RULES command in your ~PREPARE specs. (See Mentor, Appendix B: ~SPEC_RULES.)

NUM_EXCEPTIONS=STUBTITLE,STUBTITLE

Adds additional stubs (e.g. exception codes or numbers outside the range) to NUM type questions. All questions with [SAMEAS label] will have the same additional stubs in the tabset unless a new !MISC NUM_EXCEPTIONS is in the question definition.

If your ~PREPARE specifications look like:

{LISTHRS: 72.2

!MISC NUM_EXCEPTIONS=”Don’t Listen”,”Don’t Know”

In a typical day, how many hours do you spend listening to the radio?

!NUM,,,1-24,99,DK,VA=4 }

then the tabset in the DEF file will look like:

TABSET= {listhrs_z:

TITLE=:

In a typical day, how many hours do you spend listening to the radio? }

STUB=:

1-5

6-9

10-13

14-24

Don’t Listen

Don’t Know

[STAT] Mean

[STAT] Standard Deviation

[STAT] Standard Error }

ROW=: [72.4 # 1-5/6-9/10-13/14-24/99/”DK”/”VA” ] &

$[MEAN,STD,SE] [74.2 *RANGES=1,24,99,DK,VA=4,]

}

RANGES=”…“

Specifies which numeric ranges to use for rows. For NUM questions only. Any legal range will be passed to the DEF file; no error checking is made on the ranges.

If your ~PREPARE specifications look like:

{ QN1b: 7

!MISC RANGES=”1//10/11-20/21-50/51-98/99″

Q1b. How many catalogs are delivered to your office weekly?

!NUM,,,1,99

}

then the tabset in the DEF file will look like:

TABSET= { qn1b_z:

TITLE=:

1b. How many catalogs are delivered to your office weekly?}

STUB=:

11-20

21-50

51-98

[STAT] Mean

[STAT] Standard deviation

[STAT] Standard error

}

ROW=: [1/7.2 # 1//10/11-20/21-50/51-98/99 ] &

$[MEAN,STD,SE] [1/7.2 *RANGES=1,99,,,,]

}

RATING=n

Generates default statistics for rating scale CAT questions. N is the number of categories in the rating scale. You may exclude Don’t Know or Refused categories by specifying a lower number. You may use -n to reverse the scale. This can only be specified in a Survent spec file, not from EZWriter.

{QN1: 1/6

!MISC rating=5

ON A SCALE OF 1 TO 10, WHERE 10 MEANS YOU LIKE IT A LOT AND 1 MEANS

YOU LIKE IT A LITTLE, HOW WOULD YOU RATE KRAL FOR PER- SONAL APPEAL?

!CATEGORY

5 (5) LIKE IT A LITTLE

4 (4)

3 (3)

2 (2)

1 (1)

0 DON’T KNOW

}

Below is the tabset generated to the DEF file. The statistics rows added to the stub definition and the statistics calculations on the row variable.(Remember to have the AUTOPUNCHES option set in the spec file to have the definition match the response codes.)

TABSET= { qn1_z:

TITLE=:

ON A SCALE OF 1 TO 10, WHERE 10 MEANS YOU LIKE IT A LOT AND 1 MEANS YOU LIKE IT A LITTLE,

HOW WOULD YOU RATE KRAL FOR PERSONAL APPEAL?}

STUB=:

(5) LIKE IT A LITTLE

(4)

(3)

(2)

(1)

DON’T KNOW

[STAT] Mean

[STAT] Standard deviation

[STAT] Standard error

}

”qn1(5/4/3/2/1/0)

ROW=: [1/6.1^5/4/3/2/1/10] &

$[MEAN,STD,SE] [1/6.1 *RANGES=1-5]

}

For a 10-point rating scale using a single column (one through ten, and X for Don’t Know), use !MISC RATING=10. If the answers were in column seven, the row definition in the DEF file would look like:

ROW=: [7^1/2/3/4/5/6/7/8/9/10/11] &

$[MEAN,STD,SE] subscript([7^1//0])

SAMEAS_XXXX

If you use the Survent option of [SAMEAS label], the !MISC options are also retained from the specified question.

USER_TEXT=“string of text”

This option allows you to put additional text within the body of the PREPARE spec file. While this text will NOT appear in the DEF file (or your table), it is text associated with the question and can be displayed with the ~CLEAN PRINT_LINES \v5 option. See Mentor, Appendix B ~CLEAN PRINT_LINES for details. You can continue along line of text by putting an ampersand at the end of the USER_TEXT line.

If your ~PREPARE specifications look like:

{LISTHRS: 72.2

!MISC USER_TEXT=”This question was Q4 of last year’s survey.” &

“It will be used again next year.”

In a typical day, how many hours do you spend listening to the radio?

!NUM,,,1-24,99,DK,VA=4 }

~CLEAN

PRINT_LINES “\v2s” LISTHRS

PRINT_LINES “\v5s” LISTHRS

~END

then your list file will include:

PRINT_LINES “\v2s” LISTHRS

In a typical day, how many hours do you spend listening to the radio?

PRINT_LINES “\v5s” LISTHRTS

This question was Q4 of last year’s survey. It will be used again next year.

Backslash options can be used in either question text or response text to control where text is used, either by Survent only, Mentor only, or both:

\+ Displays text only on Survent interviewing screens.

\- Prints this text only on tables or when the variable is referenced (e.g., by utilities).

\* Does both of the above. (default)

{ qn17: 1/52

\+Q17. Into which of the following categories does your total family income

fall?

\-Q17. Respondent Income Category

!CAT

1 Under $15,000

2 $15,000 – $24,9994

3 $25,000 – $34,999

4 $35,000 – $44,999

5 $45,000 – $49,999

6 $50,000 or more

9 Don’t know/Refused

}

TABSET= { qn17_z:

TITLE=:

Q17. Respondent Income Category}

STUB=:

Under $15,000

$15,000 – $24,999

$25,000 – $34,999

$35,000 – $44,999

$45,000 – $49,999

$50,000 or more

Don’t know/Refused}

”qn17(1/2/3/4/5/6/9)

ROW=: [1/52.1^1/2/3/4/5/6/9]

}

In this example the question presented on the interviewer’s screen was recast as a statement for the table title. Only the text after the \- is passed to the DEF file and only the text after the \+ will display on a Survent screen.

Backslash commands, by default, are not passed to Mentor variables or spec files. You must specify the ~SPEC_RULES option USE_PRINT_ENHANCEMENTS; then when a Mentor variable is made or specifications are generated from Survent the following rules are followed for backslash commands found in the text.

For standard text or Survent only (\*):

\A \H \OR# \O# \_ \T \(#,#,#,#) are removed.

\B \U \I \F \E \N \^<character> are passed to the

\^<hexdigit><hexdigit> Mentor variable.

\\ is changed to \N.

\@ is replaced with the either the question

label or number.

\DC+fb+fb \DDC+fb+fb \C+fb+fb \C+f_ are passed to the Mentor variable as is.

\:label:^-# is replaced with ANSWERFROM(label)

\|:col.width:|, \|:col:|.width, are replaced with DATAFROM(loc.wid).

or \|:col:|^width

\|:label +offset#:| ^-width is replaced with DATAFROM(label).

\#(label) is replaced with ANSWERFROM(label,ALL).

\#(label,1,4) is replaced with ANSWERFROM(label,1,4).

\[col.wid] is replaced with PHONETEXT(col.wid).

For Mentor only text (\-):

\G \X \T \<color specs> \~<letter> \^<char> are all passed to the

\’ \” \\ \W \U \I \F \B \E \N \-W \-U \-I \-F \-B Mentor variable.

Refer to your Survent manual 2.5 QUESTION TEXT for information on Survent backslash commands, and to your Mentor manual Appendix B: TILDE COMMANDS, ~CLEANER PRINT_LINES for information on Mentor print controls.

~SPEC_RULES specified before ~PREPARE COMPILE Mentor_SPECS causes Survent to generate optional specifications to the DEF file.

Syntax: ~SPEC_RULES option option…

The options are BASE, BASE_COMMENT, CLN_CHECK, COLUMN_MEAN, DO_LOOPS, NO_BASE, STORE_TABLES, STUB_DEFAULT, and USE_PRINT_ENHANCMENTS, and they are described in the following pages.

BASE

Converts Survent !IF statements to BASE= and TITLE_4= definitions in the Mentor DEF file. Note: !IF statements are passed to the DEF file exactly as written in the Survent specification file, e.g., !IF QN6(1) becomes BASE=: QN6(1) in the DEF file. This would require that variable QN1 be available in an open DB file in order to correctly tabulate the data. TITLE_4 definitions substitute the response text for the response code referenced in the !IF statement, e.g.,(QN6 is Yes). To get around this limitation write your !IF statements by referencing data locations instead of question labels, e.g., !IF [1/31^1].

If your ~PREPARE specifications look like:

{ QN6A: 1/31

!IF [1/30^1]

Q6a. Which entertainment was participated in during the past three months?

!CAT,,6

1 Video games

2 Billiards

3 Fun House

4 Musical Revue

5 Dunk the Moose

6 Other

(-) 7 Don’t know/refused

}

then the tabset in the DEF file will look like:

TABSET= { qn6a_z:

base=: ([1/30^1])

T4=: ([1/30^1])}

TITLE=:

Q6a. Which entertainment was participated in during the past three months?}

STUB=:

Video games

Billiards

Fun House

Musical Revue

Dunk the Moose

Other

Don’t know/refused}

”qn6a(1/2/3/4/5/6/7)

ROW=: [1/31.1^1/2/3/4/5/6/7]

}

BASE_COMMENT

Converts Survent !IF statements to BASE= and TITLE_4= definitions in the DEF file, but comments them out.

CLN_CHECK

Causes the compile option ~PREPARE COMPILE CLEANING_SPECS to write out a CHECK [datavar] instead of the default EDIT varname statement to the CLN file.

COLUMN_MEAN=

Customizes the default statistics written to the DEF file. You must provide your own stub labels for the statistics rows generated with this option. Default statistics are written for NUM questions and questions written with the !MISC option explained above.

Syntax: COLUMN_MEAN=”a” with b

Options:

“a” is the specification line needed to calculate statistics on the row variable in the DEF file, e.g., $[MEAN,STD,SE,MEDIAN]

b what text, if any, you want added to the STUB= line in the Mentor DEF file. You can use this for a previously defined DB item, as in the example below.

>CREATE_DB rrunr

>FILE_TO_DB statstub # statstub: [STAT] Mean

[STAT] Standard Deviation

[STAT] Median }

>END_OF_FILE

~SPEC_RULES COLUMN_MEAN=”$[MEAN,STD,MEDIAN]” WITH statstub

~PREPARE COMPILE Mentor_SPECS

Survent specifications …

~END

TABSET= { qn20_z:

TITLE=:

Q20. Children}

STUB=

0-3

4-5

6-10

[STAT] Mean

[STAT] Standard Deviation

[STAT] Median }

ROW=: [1/55.2#0-3/4-5/6-10/”RF” ] &

$[MEAN,STD,PTILE=.5] [1/55.2 *RANGES=0,10,,RF,,]

}

Here are some of the lines from the previous spec file explained:

>CREATE_DB rrunr Creates the DB file rrunr.

>FILE_TO_DB Converts the spec lines into db items and stores them in the open DB file.

statstub The name of the db item.

# Has >FILE_TO_DB read the following lines until an >END_OF_FILE command is reached.

statstub: Name of the STUB= variable defined here.

[STAT] Mean The stub label.

>END_OF_FILE The end of the specifications.

Compiling Specifications From The Mentor Program:

~DEFINE STUB=statstub:

[STAT] Mean

[STAT] Standard Deviation

[STAT] Median }

same specifications as example above. . .

If you are compiling Survent specifications with the Mentor program then follow the example above to define a stub label set for the statistics rows generated by ~SPEC_RULES COLUMN_MEAN=.

DO_LOOPS

Converts Survent LOOP type questions into a Mentor loop variable in the DEF file. The tabulated data will reflect all iterations of the loop in the frequency. -DO_LOOPS turns this option off, but then you will only get the first iteration of the loop. The loops are explained more after these specs:

TABSET= { phones_z:

TITLE=:

Which of the following types of telephones do you have?}

STUB=:

Wall phone

Desk phone

Cordless phone

Cellular phone

Novelty phone (Garfield, Snoopy, Mickey Mouse, etc.)

None of the above}

”phones(01/02/03/04/05/06)

ROW=: [1/5.1^1/2/3/4/5/6]

}

TABSET= { purchase_z:

TITLE=:

Where did you purchase your PHONES?}

STUB=:

From an ATT phone store

From a department store

From an audio/video/electronics specialty store

From a mail order house

None of the above}

”purchase(01/02/03/04/05)

ROW=: [ (5,3) 1/8.1 ^ 1/2/3/4/5]

}

(5,3) in the previous example indicates the maximum number of times to loop (5) and the number of columns or increment between iterations of the loop (3). In this example, each iteration of the loop uses three data columns (two for the loop controller and one for the response) for a total of 15 columns if the loop is executed the maximum number of times. When the data is tabulated Mentor will check for a response to the purchase question in the third column of all five iterations of the loop, columns: 8; 11; 14; 17; and 20.

NO_BASE

Does not convert !IF statements (because the tab writer will define all of the bases). (DEFAULT)

STORE_TABLES

Causes the default table names starting with T001 to be included in each TABLE_SET definition. If you save your tables in a DB file then the table name will be stored with the other table elements defined for that table. You can edit this item in the DEF file to change these names.

EX:

TABSET= { qn1_z:

TITLE=:

Q1. How much do you agree with the following statement:

The fast food at Road Runners is worth what I pay for it.}

STUB=:

(5) Completely agree

(4) Somewhat agree

(3) Neither agree nor disagree

(2) Somewhat disagree

(1) Completely disagree

Don’t Know/Refused to answer

[STAT] Mean

[STAT] Standard deviation

[STAT] Standard error}

”qn1(5/4/3/2/1/0)

ROW=: [1/6.1^5/4/3/2/1/10] &

$[MEAN,STD,SE] [1/6.1*RANGES=1-6]

store=T001

}

You cannot use the SET AUTOMATIC_TABLES command with this option since ROW= causes Mentor to make a table with the next available table name (in this example T001). STORE= also causes Mentor to make tables with either the name assigned to it or the next available table name (see SET TABLE_NAME=). In the example above, STORE= is already assigned the next available default table name T001. Mentor would print an error message for a duplicate table name since ROW= would make T001 then STORE=T001 would remake the same table.

Other SPEC_RULES keywords are:

STUB_DEFAULT=[options]

Allows you to specify default stub [options] for stub labels written to the STUB= definition in the DEF file.

USE_PRINT_ENHANCEMENTS

Passes Survent text enhancements (e.g., \B) or Mentor print enhancements to the titles and stub labels in the DEF file. Refer to Backslash options earlier in this section for a list of which commands are passed.

Response Code Options

There are several options available which allow you to control the conversion of Survent response codes in the Mentor row variable in the DEF file. You can create subtotal (or netted) categories, suppress categories from the row variable, mark a category as exclusive, and control which categories to include in statistics calculations.

Syntax: (<options>) == (<punches or codes>) Response text

Options:

(< options >)

The standard Survent response code options: offset, ↔punch, and SKIPTO; and these Mentor options:

(-DISPLAY)

Suppresses this response during Survent interviewing. The default is DISPLAY.

(EXCLUSIVE)

Specifies this as an exclusive response during Survent interviewing. The default is -EXCLUSIVE. This is the same as saying minus (- ) or -punch in standard Survent spec writing. The keyword allows you say this anywhere inside the options parentheses. In the DEF file exclusive categories are marked in the row variable with the keyword, e.g, [6^5/4/3/2/1/(exclusive)0].

(-MENTOR_SPEC)

Says do not include this response as a category in the row variable in the DEF file. The default is Mentor_SPEC. This also suppresses the comment, e.g., ”qn1(5/4/3/2/1/0), in the DEF file.

(STATISTICS)

Controls which categories will be included in statistics calculations (only tests defined on the ~DEFINE STATISTICS= statement). The default is STATISTICS for all categories. However, if you specify (STATISTICS) on any response item, then the default for all others is (-STATISTICS). The statistics categories are marked in the row variable with the keyword stats: [2/10.2^1/2/(stats)3/4/5].

Statistics defined in the row variable, e.g., $[MEAN,STD,SE], are not affected by this option.

A special response code indicating that this is a non-response item during interviewing. There must be as many equal = signs as response code length. Please refer to your Survent manual for more information.

(< punches or codes >)

The codes for the row variable category generated in the DEF file; punches for CAT questions and codes for FLD questions.

If there are no parentheses ( )s or an empty set of parentheses, then a [COMMENT] line is included in the stub definition in the DEF file. The variable is stored in the open DB file with the additional categories.

Response Text

Specifies the text that will appear during Survent interviewing and on the stub label for this item.

In the example below, we have created two netted categories: punches four and five (5,4); and punches one and two (2,1). These items will not display as responses during Survent interviewing (-DISPLAY) and will be the only categories included in tests defined on the ~DEFINE STATISTICS= statement (STATISTICS). The last response will not be included in the row variable (-Mentor_SPEC), but it will be an exclusive response during Survent interviewing (EXCLUSIVE).

{ QN1: 1/6.1

!MISC RATING=5

Q1. How much do you agree with the following statement:

The fast food at Road Runners is worth what I pay for it.

! CAT

(-DISPLAY, STATISTICS) = (5,4) TOP BOX

5 (5) Completely agree

4 (4) Somewhat agree

3 (3) Neither agree nor disagree

(-DISPLAY, STATISTICS) = (2,1) BOTTOM BOX

2 (2) Somewhat disagree

1 (1) Completely disagree

(-Mentor_SPEC, EXCLUSIVE) 0 Don’t Know/Refused to answer

}

Here is the TABLE_SET definition created in the DEF file. Note the stub and row definitions. The equal sign = response items and text specified on question QN1 were converted to stub labels and corresponding netted categories on the row variable.

TABSET= { qn1_z:

TITLE=:

Q1. How much do you agree with the following statement:

The fast food at Road Runners is worth what I pay for

it. }

STUB=:

TOP BOX

(5) Completely agree

(4) Somewhat agree

(3) Neither agree nor disagree

BOTTOM BOX

(2) Somewhat disagree

(1) Completely disagree

[STAT] Mean

[STAT] Standard deviation

[STAT] Standard error}

ROW=: [1/6.1^( stats)5,4/5/4/3/( stats)2,1/2/1] &

$[MEAN,STD,SE] [1/6.1 *RANGES=1-5]

}

Compiler Commands

These are commands that you put in your Survent questionnaire specficications. With them, you can control which questions get passed to the DEF file. In addition, you can include Mentor specifications in your Survent questionnaire and designate the program-generated file they should be passed to: CLN, DEF, or TAB.

{!-DO_Mentor}

Allows you to exclude a question or block of questions from the DB file and DEF file. The default is to convert each CAT, FLD, and NUM question to a variable in the DB file and a TABLE_SET definition in the DEF file. {!DO_Mentor} turns the default back on.

{!Mentor_CLN}, {!Mentor_DEF}, and {!Mentor_TAB}

Used to pass Mentor specifications to the CLN, DEF, or TAB file, respectively. The Survent compiler treats these blocks as comments and no syntax checking is done. When you compile your questionnaire with either the option Mentor_SPECS or CLEANING_SPECS, these blocks will be passed to the appropriate file.

{!Mentor_DEF

{TABLE_SET=tab1:

EDIT= -COLUMN_TNA }_

TITLE= table title }_

ROW= [2/5^1//8]

} }

NOTE: The first closing brace on the last line ends the TABLE_SET and the second closing brace ends the !Mentor_DEF block.

Brace underscore (}_) allows you to imbed a right brace (}) inside the compiler command block when it is the last character on a line that you want passed as part of a specification. In the example above EDIT= and TITLE= each require a closing right brace. The underscore is stripped when the specification is passed to the file and the right brace is not interpreted as the end of the command block. The specification passed to the DEF file will look similar to this:

{TABLE_SET=tab1:

EDIT= -COLUMN_TNA }

TITLE= table title }

ROW= [2/5^1//8]

}

USING E-TABS

Mentor makes files that are usable by E-Tabs. E-Tabs is a software package that has a Writer module which can take a Mentor (or any number of other software packages) print file and prepare it for viewing by a Reader module. The end user can browse the tables, print the tables, do specific keyword searches, and cut/paste portions of the tables to other software packages such as Excel, Word, or PowerPoint. It can also create charts or graphs. E-Tabs will create a few files, one with an extension of .ZTE (ebook.zte) which is the final output file which the user will use.

The user can then modify that file as long as they keep the extension of .ZTE. E- Tabs has a Dos/Windows version and also SCO/Sun Solaris Unix version.

The E-Tabs program needs these 3 files which Mentor now creates:

tab1.prt (our normal tables excluding the table of contents)
cfmctoc.ite (table of contents)
ebook.ini (description of table regions)

These Mentor features are needed to create the E-Tabs files:

Use ~SET ETABS_PRINTFILES

This says create the three E-Tabs files.

You must use >PRINTFILE statements to provide the names of the three E-Tabs files.

For tables file use:

>print_file tab1 #1 page_width=132

for toc file use:

>print_file cfmctoc.ite,user -formfeed #2 page_width=2000

for ebook file use

>print_file ebook.ini,user -formfeed #3 page_width=2000

You must add this EDIT option: TCON=(separate_file)

Spec writers should observe the following rules:

1) Lines in the table of contents cannot wrap, so make the page width long enough to accommodate this.

2) Works best with Mentor 8.1 banners created with make_banner.

3) Banner headers (age, income, etc.) should be on the same level.

This format is preferable:

AGE INCOME RATING

======================= ======================== =============

Un- Un- Neu-

der Over der $15- Over tral

Total 35 35-54 54 $15k $35k $35k Good /Poor

—– —- —– —– —- —– —- —- —–

This format is not preferable:

AGE INCOME RATING

========================= ========================= ==============

Under Over Under $15- Over Neutral

Total 35 35-54 54 $15k $35k $35k Good /Poor

—– —– —– —- —– —- —- —- ——-

4) EDIT TCON=( ) options should include:

TCON_PAGE_NUMBERS
HEADER
FOOTER
TABLE_NAMES

5) Do not use these EDIT TCON=( ) options:

FIRST
PRINT_PAGE_NUMBERS

6) To create the E-Tabs ebook.zte file from the CfMC print files, make sure the table of contents file is named cfmctoc.ite and the description of table regions file is named ebook.ini.

If you are working with more than one set of tables in the same directory you might want to use the same root name when creating the CfMC files (tab1.prt, tab1.ite, tab1.ini). Then using a batch file, rename the CfMC files before creating the ebook.zte file. After the E-Tabs file is created, the same batch file can rename the ebook.zte to tab1.zte.

More E-Tab Options

You can now change .prt, .ini and .ite files when using ~SET ETABS_PRINTFILES.

EX:

~SET ETABS_PRINTFILES

>PRINTFILE mt3581a #1

>PRINTFILE mt3581b #2

>PRINTFILE mt3581c #3

~EXECUTE

TABSET=one

SET PRINTTCON

>PRINTFILE

>PRINTFILE mt3581d #1

>PRINTFILE mt3581e #2

>PRINTFILE mt3581f #3

~EXECUTE

TABSET=one

SET PRINTTCON

>PRINTFILE