SDA 3.5 Documentation for LISTCASE

NAME

listcase - List values of individual cases

USAGE

listcase -b batch_filename
OR
listcase -options (for command-line version)

DESCRIPTION

LISTCASE is a program to produce a case-by-case listing of the values of a set of variables. One or more filter variables can be used, in order to limit the listing to a subset of the cases in the dataset.

All selected cases are listed, including those with missing-data codes. However, the missing-data codes are not included in the calculation of summary statistics, if statistics are requested.

CALCULATION AND DISPLAY OF PERCENTAGES

Aside from simply specifying the name of a variable, it is possible to convert a number into the percent of another variable. (Both variables must be variables.) This is particularly useful when the cases in the data file are aggregate units such as cities.

To calculate and display a percent, use the following formats, beginning with $p, instead of a simple variable name:

$p(var1, var2): This will display the value: 100 * var1 / var2.
(using 1 decimal place) where ’var1’ and ’var2’ are variables in the dataset. It is not necessary that either ’var1’ or ’var2’ be specified separately for listing.
$p(var1, var2, 2): To display a percent using other than one decimal place, specify the desired number of decimal places after var2. The example above would use 2 decimal places.
$p(demo, totvote, "Percent democratic"): To give your own name to the percentage created, put the name you want within double quotes. This name will be displayed at the top of the column for that percentage.

MODES OF EXECUTION

The program runs in two modes -- a batch mode with HTML output, and a command-line mode with plain-text output.

Batch mode

When the SDA Web interface runs the batch-mode version of the program, users will not have to deal with the keywords given in this document. The HTML output from the program goes directly to the user’s Web browser.

It is possible to run the program in batch mode without the Web interface by preparing a command file, which specifies the variables to be listed and the options to use. This document explains how to prepare such a file. The name of this batch command file is specified to the program after the ‘-b’ option flag.

Command-line mode

When the program is run in command-line mode (using options other than ‘-b’), the specifications are given by using the various option flags described below. In command-line mode, the output from the program is generated in plain text (not HTML) and is sent to the user’s screen (the standard output). The output can be redirected to a file in the usual way by using ‘>’.

The command-line version of the program is intended to be used primarily for diagnostic purposes. It does not generate percentages or statistics, force variable names to upper or lower case, or limit the output to some maximum number of cases. However, it does allow for filter variables, and it can display category labels as well as code values. See below for an explanation of the available command-line options.

KEYWORDS FOR BATCH-MODE EXECUTION

The batch file contains specifications for the listing. These specifications are given in the form "keyword = something" with one keyword per line. Keywords may be given in any order, either in upper or in lower case. The valid keywords are as follows (with significant characters shown in capital letters):


Keyword       Possible Specification          Default (if no keyword)
_____________________________________________________________________


STUdy=        path of dataset directory       Look for variables only in
                                                current directory

VARiables=    variable name(s)                REQUIRED
               (separated by spaces/commas)
               can specify percents, as well
               as individual variables

Filter=       name(s) and codes of filter     No filter
                variable(s)

GVARCase=     LOWER or UPPER                  No force to lower/upper case

SAvefile=     filename to receive output      Output sent to screen
                (overwrite existing file)       (standard output)

VALues=       (how to display numeric vars)
               Codes - numeric codes          Both
               Labels - category labels
                (if any; otherwise codes)
               Both - Codes AND labels

MAXCases=     max number of cases to display  500

STATistics=   mean, sum, min, max             No summary statistics

COLOR=        Yes                             No color for heading

LAnguagefile= Name of file with non-English   English labels on
                labels and messages             output

RUNtitle=     Title or comment for run        No title or comment

TExt=         Yes                             No text for variables

Abbreviations

Keywords can be abbreviated down to the number of characters required to differentiate them from other keywords. Usually only one character is required. The keyword for the vertical variable, for instance, can be given as "variables=" or "vars=". Either upper or lower case may be used.

Repetition of Keywords

If there is not enough room on a line to list all of the desired variables, the keyword can be repeated on a new line, and more variables can be listed. In such a case the second list is appended to the first list, for purposes of generating tables. This appending feature only applies to the keywords for specifying the variables to be listed and the filter variables. If other keywords are repeated, the program will print an error message and stop.

Comments

Anything on a line beginning with "#" is ignored by the batch processor and can therefore be used for comments. Blank lines are also ignored.

EXAMPLES OF BATCH FILES


# Basic example

     vars = spend spend2 spend3
     filter = age(18-20) gender(1)

     savefile = mylist

---------------------------------------------

# Specify that only category labels be output
# (If a category has no label, the numeric
#  code value will be output.)

     vars = spend spend2 spend3
     filter = age(18-20) gender(1)

     values = labels

     savefile = mylist

---------------------------------------------

# Get percentages as well as individual variables
# For example, the percent of total income
#  represented by wages

     vars = wages, totincom, $p(wages,totincom)

     filter = age(18-20) gender(1)
     savefile = mylist

---------------------------------------------

# Specify study, text, and a run title

     study = /sa/sdatest
     vars = spend spend2 spend3 spend4
     filters= age(18-50) party(1-3)

     text = yes
     runtitle = List the values of the spending variables

     savefile= mytables

OPTION FLAGS FOR COMMAND-LINE EXECUTION

The LISTCASE program is executed in command-line mode whenever option flags other than ‘-b’ are used. The meaning of the available options is as follows:

-a: List only the CASEID values.
-f filter(s): Filter specifications to limit the cases to be displayed. An example of a filter specification is:
-f ’age(18-25),gender(2)’
Note that quotes are ALWAYS necessary around the filter specifications.
-v varlist: List of variables (in addition to the CASEID variable) for which the code values will be displayed. Names of variables can be separated by commas or blanks. If they are separated by blanks, the list of variables needs to be put in quotes.
A variable name may be given with a range restriction like ’age(18-20)’. This has the same effect as a filter specification.
-s path: Look for variables in the specified study path(s) in addition to the current directory.
-l: Show the category labels, in addition to the category values.
(This option flag is a lower-case ’L’.)
-h: Display a list of options.

EXAMPLES OF COMMAND-LINE SPECFICATIONS

listcase -f ’age(18-25)’: List CASEID values for cases with the values 18-25 on age.
listcase -v age,educ,gender -f ’region(1)’: List values of CASEID, age, educ, gender for cases in region 1.
listcase -l -v ’income(1-5)’: List category values and labels for everyone with categories 1-5 on the income variable.

CSM, UC Berkeley
April 12, 2011