ACCESS -- load data from a saveset when needed by SST

Synopsis:
ACCESS FILE[filename] options

The ACCESS command allows variables contained in a saveset to be loaded into SST only when the data is needed by SST. The variables will appear in listings as if they exist in memory but the data will not be loaded until it is actually needed by SST. Any variables that already exist in memory will be overwritten. If no file extension is present in filename, .sav is assumed.

By default, the length of the current observation range used by SST is set to the length of the largest variable accessed from a saveset. This action is not performed if the current observation range has been set explicitly with the RANGE command. Additionally, the ACCESS command will never set the current range to a length less than that set by a previous LOAD or ACCESS command. The auto range feature can be enabled and disabled using the command CONFIG RANGE[auto=on|off].

SST savesets can be created with the SAVE command. SST savesets can also be read with the LOAD command. The only difference in ACCESS and LOAD is that the latter brings all variables into memory at once. LOAD minimizes interactive computing time, but may require significant startup time.

Required subops

FILE[filename]
The name of the saveset to be read.

Optional subops

TAPE[filename]
The TAPE subop can be used in place of FILE to optimize saveset access for sequential access devices such as tape drives. This subop also results in some savings in memory usage at the expense of speed when used with random access devices.

TIME
Display a summary of the time used by this command.

TO[variable list]
Change the names of the variables as they are read from the saveset. The number of variables listed in the TO subop must agree with the number listed in the VAR subop.

VAR[variable-list]
Access only the specified variables. If no argument is present all variables contained in the saveset will be accessed. The names used to store the variables can be changed with the TO subop.

Examples

SST1> ACCESS FILE[bkw]                      # access all variables in bkw.sav
SST2> ACCESS FILE[bkw] VAR[pop15] TO[abc]   # access variable 'pop15' as 'abc'
SST3> LIST                                  # access variables marked by '+'

---- Variables ----
abc         50+ Wed Jul 26 20:32:06 1989 percentage population under 15
deldpi      50+ Wed Jul 26 20:32:06 1989 real disposable income growth rate
dpi         50+ Wed Jul 26 20:32:06 1989 real disposable income per capita
pop15       50+ Wed Jul 26 20:32:06 1989 percentage population under 15
pop75       50+ Wed Jul 26 20:32:06 1989 percentage population over 75
sr          50+ Wed Jul 26 20:32:06 1989 average personal savings rate

SST4> CALC mean(pop15-abc)
      0.00000e+000
SST5> LIST

---- Variables ----
abc         50  Wed Jul 26 20:32:06 1989 percentage population under 15
deldpi      50+ Wed Jul 26 20:32:06 1989 real disposable income growth rate
dpi         50+ Wed Jul 26 20:32:06 1989 real disposable income per capita
pop15       50  Wed Jul 26 20:32:06 1989 percentage population under 15
pop75       50+ Wed Jul 26 20:32:06 1989 percentage population over 75
sr          50+ Wed Jul 26 20:32:06 1989 average personal savings rate


AGGREGATE -- aggregate data using summary measures

Synopsis:
AGGREGATE VAR[variable list] TO[variable list] BY[variable] {option2

The AGGREGATE command forms counts, means, sums, or standard deviations of variables by specified categories in the population. It can be used for Analysis of Variance calculations, and to form statistics for various sub-samples.

Required subops

VAR[variable list]
Specifieds a list of variables in the existing data set for which summary statistics are to be calculated.

TO[variable list]
For each variable in the VAR subop, a corresponding variable name must be specified in the TO subop. Observations on the variables in the TO subop will be calculated using groups of observations on the input variable in the VAR subop.

BY[variable list]
A discrete variable whose levels define the categories used in forming the summary measures. If a variable list is given, then each possible combination of levels defines a category.

Optional subops

MEAN
Return the category means. This is the DEFAULT if omitted.

NOBS
Return the number of observations in the category.

SUM
Return the sum of observations in the category.

STDDEV
Return the standard deviation of the observations in the category. If more than one of the subops MEAN, NOBS, SUM, STDDEV is used, only one is calculated, in the precedence NOBS, SUM, STDDEV, MEAN.

BYVAR
By default, AGGREGATE omits observations for which there is any missing data in the VAR variable list. If BYVAR is present, then an observation is omitted for a variable only if that variable is missing.

IF[expression]
Restrict the active observations to those for which expression is true.

KEY[argument]
If KEY is present, then each variable in the TO list has a length equal to the number of levels of the BY variable, and the argument of KEY is a variable list giving the category levels of the BY variables. The length of the variable list in KEY must equal the length of the variable list in BY. If KEY is absent, then the variables in the TO list are the same length as the variables in the VAR list, with the categorical summary in each observation in the corresponding category.

OBS[observation list]
Restrict the active observations to those observations listed.

TIME
Display a summary of the time used by this command.

Example

Suppose we have data on family income, faminc, for households in diffrent regions, region:

  Obsno        faminc            region
     1:      10.00000           1.00000
     2:      20.00000           1.00000
     3:      15.00000           2.00000
     4:      20.00000           2.00000
     5:      25.00000           2.00000

The command

AGGREGATE VAR[faminc] BY[region] TO[avinc] KEY[newreg]

would compute mean income for each of the two regions:

  Obsno         avinc            newreg
     1:      15.00000           1.00000
     2:      20.00000           2.00000


ARRAY -- create a shell variable

Synopsis:
ARRAY name ARRAY name = value ARRAY name = (value1 value2 ... valueN)

The ARRAY command is used to define an array of values. For example

ARRAY name = (value1 value2 ... valueN)

The array name is any valid SST identifier. The value of an element of the array can be any string; it should be separated from other values by a space or a comma (below we describe how to embed spaces and commas in a single element of an array variable). If an array has only a single value the parenthesis can be omitted. We can create a variable with no value by omitting everything after the equal sign (including the equal sign itself). Here are some valid array declarations; the third creates a null array:

ARRAY list  = (pop15, pop75, dpi)
ARRAY single = this is a single array element
ARRAY flag
ARRAY quote = (pop15,"this is a single array element")

To recall a array, we use the array metacharacter -- the dollar sign ($). Array substitution behaves much like simple macro substitution, the array is "expanded", replacing the array reference. Since the array has many values associated with it, we must specify the element of the array we would like to retrieve. A general array reference has the following form:

$variable_name[index]

The index is used to specify the elements of the array which should be extracted. It can either be a single integer ($name[3]), a range of integers ($name[1-4]) or an open ended range ($name[2-]). This last form will extract the second to the last elements of the array name. If only the array name appears ($name), all the values of the array separated by spaces are substituted. Consider the following example:

SST1> array list = (one, dos, tres, 4, ivefay)

SST2> echo One element: $list[3]
One element: tres

SST3> echo All elements: $list
All elements: one dos tres 4 ivefay

SST4> echo Some elements: $list[3-]
Some elements: tres 4 ivefay

It is often necessary to determine the size of an array. To do this we use an array reference of the form $#name. When SST encounters this reference it will replace it by the number of elements in the array name (this array must exist). As an example, let's write a command file to calculate a two stage least squares with any number of exogenous variables:

# reg2.cmd - calculate a two stage regression
# Usage:  RUN reg2(y1, y2, x_vars, z_vars)
#                  $1  $2  $3      $4

# Set up some arrays to act on
array y1 = $1
array y2 = $2
array x_vars = ($3)                     # exogenous variables
array z_vars = ($4)                     # instruments

reg dep[$y2] ind[$x_vars $z_vars] pred[y2hat]
reg dep[$y1] ind[y2hat $x_vars] coef[b2sls]

# Calculate the error
set ls2_err = y1 - b2sls(1)*y2
foreach (i; {1-$#x_vars2) {
            set ls2_err = sl2_err - b2sls($i+1) * $x_vars[$i]
}
calc stdev(e2sls)

As each command in the command file is executed the values of the arrays are substituted in place of the array references. This substitution does not occur until the commands are actually executed. Thus array references within the body of a loop are not expanded until the loop is actually executed (and not just defined). Also notice that array references are allowed inside the subscripts of an array reference, as in `$x_vars[$i]'. The array i will first be expanded to determine which element of x_vars to retrieve. The entire reference will then be replaced by that element of x_vars.

Now lets take a look at some of the other functions that the array mechanism can perform. The following table is a summary:

Reference       Value
---------       -----

$#name          The number of words in the array "name"
$?name          "1" if the array "name" exists, "0" otherwise

$0              The name of the current command file
$1, $2, ...     The arguments specified for this command file
$*              All command file arguments separated by spaces

$<              Reads a single line of input from the terminal
$(expr)         Evaluates "expr" using CALC and substitutes the result
                For example $(PI) converts the representation of the
                string '3.1416..' to a floating point number that can
                then be used in subops like DOMAIN.
$'s1, s2'       "1" if the strings s1 and s2 are equal, "0" otherwise
$^varname       Unique values of an SST variable, in sorted order,
                separated by spaces

It is often necessary to use an array in a location where it's meaning might be ambiguous. For example, suppose that we would like to expand a array i and immediately follow it by the word data. The obvious array reference, $idata, is indistinguishable from the expansion for a array with the name idata. In such cases the array reference can be surrounded by braces to delimit it from surrounding text. So our desired reference would become ${i2data

Internal arrays

SST defines a number of internal arrays (as opposed to user arrays) which can be accessed in the same way as user arrays. These arrays are listed below. Note that only the status and argv arrays appear when listed with the LIST ARRAY command. The other arrays may listed by explicitly specifying them in the ARRAY subop to the list command.

Name            Value
----            -----
time            The current time (hh:mm:ss)
version         Date and time that this version of SST was created
echo            Value of the CONFIG ECHO flag ("on" or "off")
verbose         Value of the CONFIG VERBOSE flag ("on" or "off")
status          "1" if the last command ran successfully, "0" otherwise
argv            Arguments for the current command file

The status array can be set to reflect the return status of a command file by specifying an argument to the EXIT command. This argument must be a valid expression; the status array is set to the value of the expression (as determined by the CALC command) converted to an integer. If a file contains no EXIT command, it's return status is the same as the last command executed. If the EXIT command contains no argument, the status array is set to 1. Note that setting the status array using the ARRAY command will not work since status will immediately be reset to the return status of the ARRAY command (probably 1).

Internal array functions

SST also defines some array functions which allow access to SST data and provide useful operations. The following functions are defined:

Function                Value
--------                -----
$strcmp(s1, s2)         '1' if s1 equals s2, '0' otherwise
$labels(var)            list of value labels for the SST variable 'var'
$values(var)            sorted list of values contained in 'var'
$vallab(var, value)     label associated with a given value
$labval(var, label)     value associated with a value label
$extract(s, i, j)       extract a substring of s (ith through jth chars)


AUTO -- compute autocorrelation function of a time series

Synopsis:
AUTO VAR[variable list] LAG[number] options

The autocorrelation function is computed for each variable specified in the VAR subop for up to the number of lags specified in the LAG subop. If the LAG subop is not present, the default maximum is fifteen lags. This function assumes the data are equally spaced in time, without gaps

Required subops

VAR[variable list]
Produce an autocorrelation for each variable listed in variable list.

Optional subops

IF[expression]
Compute the autocorrelation function only for observations in which expression is non-zero.

LAG[number]
Set the number of lags used to compute the autocorrelation function to number. The default value is 15.

OBS[observation list]
Limit the observations for which the autocorrelation function is calculated to those listed in observation list.

PARTIAL
If the PARTIAL subop is present, partial autocorrelations are calculated in addition to autocorrelations. In both cases, a plot of the autocorrelations is produced with + denoting the value of the autocorrelation and parentheses indicating plus or minus one standard deviation bounds.

TIME
Display a summary of the time used by this command.

BY[variable]
Labels bars with values in variable

STACK
If present, a stacked bar plot is produced.

Example

To compute the first fifteen autocorrelations for the time-series `unemp':

auto var[unemp]


BAR -- plot a bar chart for a set of variables

Synopsis:
BAR VAR[variable list] options

A bar chart of the variables specified in the VAR subop is graphed using the observations determined by the IF and OBS subops (if present). This command produces a bar for each observation and variable, unless the subop STACK is present. If STACK is present, then a stacked bar is produced for each observation. The AGGREGATE command with the KEY subop can be used to prepare data summaries for bar plotting.

Required subops

VAR[variable list]
Specify which variables are to be included in the bar chart.

Optional subops

FILE[pathname]
Save output to the specified file. If the current terminal type does not support file output this option is ignored.

IF[expression]
Restrict the active observations to those for which expression is true.

LAB[string]
Generate a label for the graph.

OBS[observation list]
Restrict the active observations to those observations listed.

PARM[string]
Specify optional parameters to customize the display.

PRINT
If present, the output is sent to the printer rather than to the screen. When this option is used, TERM must also be present unless this has been set as an environment variable on your system.

SIZE[llx lly urx ury]
Change the size of the plot by specifying the coordinates of the lower left and upper right corners of the plot. Each of the coordinates should be in the range 0 to 1. See SIZE.

TERM[terminal]
Use the driver for terminal. See TERM.

TIME
Display the time required to execute the command.

Example

To generate a bar chart for the first five observations of sr and pop15 from the BKW data set:

SST1> load file[bkw]
SST2> bar var[sr pop15] by[(obsno)] obs[1-5]


BOXPLOT -- plot boxplots for a set of variables

Synopsis:
BOXPLOT VAR[variable name] options

A boxplot is drawn for each variable listed in the VAR subop. The top and bottom of the box correspond to the 25th and 75th per- centiles of the variable, the horizontal line through the box corresponds to its median. The vertical line, or "whiskers", have ends that extend beyond the quartiles by a distance equal to 1.5 times the interquartile range. Approximately 99 percent of normally distributed data will lie within the whiskers. Outliers are identified by *. The boxplot is printed vertically with the variable name listed on the X axis of the graph. The PARM option may be used to change the parameters used to describe the graph.

Required subops

VAR[variable name]
Variables to be plotted.

Optional subops

FILE[filename]
Save output to the specified file. If the current terminal type does not support file output this option is ignored.

IF[expression]
Restrict the active observations to those for which expression is true.

LAB[string]
Generate a label for the graph.

OBS[observation list]
Restrict the active observations to those observations listed.

PARM[options]
Options to the PARM subop can be used to customize the format of the graph. For the BOXPLOT command, options which affect the X axis are ignored. See PARM.

PRINT
If present, the output is sent to the printer rather than to the screen. When this option is used, TERM must also be present unless this has been set as an environment variable on your system.

SIZE[llx lly urx ury]
Change the size of the plot by specifying the coordinates of the lower left and upper right corners of the plot. Each of the coordinates should be in the range 0 to 1. See SIZE.

TERM[terminal]
Use the driver for terminal. See TERM.

TIME
Display a summary of the time used by this command.

Example

SST3> LOAD FILE[bkw]                #Boxplot with terminal output
SST4> BOXPLOT VAR[sr dpi deldpi]

BREAK -- terminate a loop

Synopsis:
BREAK

Break out of the body of a FOREACH, FOR or WHILE loop. If more than one loop is in progress, the innermost loop is terminated -- it is an error to issue the BREAK command outside of a loop. More information on SST loops is given under the name of each loop.

Example

SST2> FOREACH (i; 1 2 3 4 5) {    # Simple loop to illustrate BREAK command
1> ECHO iteration number $i
1> IF ($i>2) BREAK
1> }
iteration number 1
iteration number 2
iteration number 3
SST3>


BREAKDOWN - Means and Standard Deviations by Category

Synopsis:
BREAKDOWN DEP[variable name] BY[variable list] options

This command forms means and standard deviations of the variable specified in the DEP subop, classified by the values of the variable given in the BY subop, and prints out the results in a convenient format. If there are several variables in BY, then all possible combinations of values of these variables are used to form the classification. The AGGREGATE command can also be used to generate classified means and standard deviations, in a form useful for construction of further variables.

Required subops

DEP[variable name]
The variable to be analyzed. If a variable list is given, only the first is used.

BY[variable list]
Variable list whose values (in all possible combinations) form the classes by which the dependent variable is analyzed.

Optional subops

ANOVA
If present, the statistics necessary for a one-way Analysis of Variance are included in the output. The analysis is made only for the last variable in the BY list, given the largest values of preceeding variables in the BY list.

IF[expression]
Restrict the active observations to those for which expression is true.

OBS[observation list]
Restrict the active observations to those listed in observation list.

TIME
Display a summary of the time used by this command.


CALC -- evaluate a scalar expression

Synopsis:
CALC expression

If an expression is typed on the command line, the expression is evaluated and the user is returned to the SST prompt. If no expression is typed on the command line, SST is placed in calculator mode. Expressions are evaluated as entered by the user until `q' or `quit' is typed at the calculator prompt. Any valid expression can be evaluated by the calculator. If a variable name is mentioned without any reference to a particular observation, the calculator assumes the first observation on the variable is to be used. An underscore can be used to retrieve the last result calculated by SST

For more information in SST expressions see the SST User's Guide.

Example

SST1> LOAD FILE[bkw]
SST2> CALC 1/sqrt(2)                    # Calulation using constant data
      0.70711
SST3> CALC mean(sr)                     # Calculate mean value of a variable
      9.67100
SST4> CALC log(sr[12])                  # Calculation on an individual
      1.27815                           # observation
SST5> CALC 2+_                          # Calculation on last result
      3.27815


CD -- change working directory

Synopsis:
CD path

Change the current working directory to path. If path is not specified the name of the current directory is printed.

Example

SST1> CD                        # Print the current directory
D:\sst
SST2> CD data                   # Go to a subdirectory
D:\sst\data
SST3> DIR

.                 <DIR>      7-27-89   9:52p
..                <DIR>      7-27-89   9:52p
BLACKER.DAT            796   7-26-89   8:23p
DABNEY.DAT             199   7-26-89   8:43p
FLEMING.DAT            160   3-17-87   8:00a
LLOYD.DAT               33   7-04-89   6:51p
PAGE.DAT                 5   7-26-89   9:45p
RICKETTS.DAT           126   7-26-89   9:45p
RUDDOCK.DAT             14   6-26-89  10:09p
        9 File(s)  316416 bytes free
SST4> CD A:/                    # Return to starting point
A:\
SST5>


CLEAR -- restart an SST session

Synopsis:
CLEAR options

If no options are present all user data is destroyed. This includes variables, functions, macros and the history and replay lists. A specific subset of these can be cleared by using one of the options given below. To clear specific data elements, such as a single matrix or variable, use the DEL command.

Optional subops

ARRAY
Clear all user arrays (see ARRAY).

FUNC
Clear all user defined functions (see DEFINE).

MACRO
Clear all macros.

MAT
Clear all matrices.

VAR
Clear all SST variables.

TIME
Display a summary of the time used by this command.

CLEAR examples

SST1> LOAD FILE[bkw]
SST2> DEFINE add(a,b) = a + b           # Define some SST objects
SST3> MACRO LS LIST
SST4> LIST

---- Variables ----
deldpi      50  Wed Jul 26 20:32:06 1989 real disposable income growth rate
dpi         50  Wed Jul 26 20:32:06 1989 real disposable income per capita
pop15       50  Wed Jul 26 20:32:06 1989 percentage population under 15
pop75       50  Wed Jul 26 20:32:06 1989 percentage population over 75
sr          50  Wed Jul 26 20:32:06 1989 average personal savings rate

---- Functions ----
add          2

---- Macros ----
LS           0

SST5> CLEAR MACRO                       # Clear macros only
SST6> LIST

---- Variables ----
deldpi      50  Wed Jul 26 20:32:06 1989 real disposable income growth rate
dpi         50  Wed Jul 26 20:32:06 1989 real disposable income per capita
pop15       50  Wed Jul 26 20:32:06 1989 percentage population under 15
pop75       50  Wed Jul 26 20:32:06 1989 percentage population over 75
sr          50  Wed Jul 26 20:32:06 1989 average personal savings rate

---- Functions ----
add          2

SST7> CLEAR                             # Clear all SST objects
SST8> LIST

No objects in memory


CLS -- clear screen

Synopsis:
CLS

CLS clears the screen on systems which support this action. On some systems the TERM or SSTTERM environment variables must be correctly initialized before this command may be used. For more information see CONFIG.

Example

SST1> cls               # clear the terminal screen


COMPRESS -- remove missing observations from variables

Synopsis:
COMPRESS VAR[variable list] options

This command does listwise deletion of each observation for which any of the variables in VAR have missing data, or which are excluded by the IF or OBS subops, and relocates the remaining data sequentially from the beginning of the file. See also EXPAND.

Required subops

VAR[variable list]
Compress only the specified variables.

Optional subops

IF[expression]
Limit the active observations to those for which expression is true.

OBS[observation list]
Limit the active observations to those listed in observation list.

TIME
Display a summary of the time used by this command.

TO[variable list]
Change the names of the variables to be acted upon as they are read. The number of variables listed in the TO subop must agree with the number listed in the VAR subop.


CONFIG -- change default operating parameters

Synopsis:
CONFIG options

Many of the operating parameters of SST can be changed by the user. To change these characteristics use the CONFIG command. The basic syntax is CONFIG option[parameter {= value2] where the parameter and optional value depend on the option specified. If no command is specified the current options are printed.

Optional subops

ARRAY[meta=c]
Change the ARRAY meta characters. See section EDIT[on|off term=type block=on|off]
Normally the EDIT command must be used to enter the SST online editor. To automatically invoke the editor for each input line specify EDIT[on]. EDIT[off] turns the autoedit feature off (the default). The term option can be used to change the terminal type used by the editor. Specifying an unknown terminal type causes the autoedit feature to be turned off. The block option determines whether a block cursor is used in edit mode (on terminals which support different cursor types). The default is block=on.

HISTORY[length=n off batch=on|off meta=c]
The option length sets the history list length to n. Setting n to zero (or alternatively using the off option) turns the history mechanism off. The batch option controls whether commands read from batch files are stored in the history list. For more information on the meta option, see section Changing SST's metacharacters
Change the macro meta characters. See section Changing SST's metacharacters
The long option causes the MORE filter to display a longer, more descriptive prompt as opposed to its normal terse prompt (selected with the short prompt). The lines option sets the number of lines on the screen (the lines= string can be omitted). If the number of lines is set to zero or the off option is specified the MORE filter is turned off. If the on option is given, SST will try to determine the number of lines on the screen automatically.

OUT[filename]
Turns off all output from SST (including error messages). OUT[on] will turn the output back on.

PRECIS[digits=n val=on|off]
The PRECIS subop allows the user to specify the number of significant digits used when printing output. The default precision is five digits. New precisions may be set between one and eight digits using the length option. The val option allows certain SST routines to print value labels instead of numerical values for SST variables which have an associated value list. For more informtion on value labels, see LABEL.

PROMPT[prompt string]
Set the command line prompt (detailed below).

RANGE[auto=on|off]
Setting the auto option to on allows the LOAD command to set the current range based on the size of the data in the saveset. See the LOAD command for more details.

REPLAY[length=n off batch=on|off]
The length option sets the number of commands for which output is saved. Specifying a length of zero (or using the option off) turns off the replay mechanism. The batch option controls whether the output from commands executed in batch files are saved in the replay buffer.

SAVE[backup=on|off warn=on|off checksum=on|off]
The backup option forces the SAVE command to create backup copies of files that are overwritten. The default is not to create backup copies. The warn option causes the SAVE command to print a warning message when backup copy of a file is created. The checksum option controls whether checksums are verified when a saveset is read into memory (default = on).

TERM[graphics=type text=type]
Sets the graphics and text terminal types. The graphics terminal type is used by the SST plot commands. For a list of valid terminal types, see TERM. The SSTTERM environment variable can also be used to set the graphics terminal type. The text terminal type is used by the SST command line editor. By default, the TERM environment variable is used to determine the text terminal type. If an invalid terminal type is specifed, an error message is printed and the autoedit option is automatically turned off (see the EDIT subop, above).

TMP[path]
The TMP subop determines the pathname which SST uses when opening temporary files. It defaults to the directory given in the TMP environment variable or the current directory (if TMP does not exist). A list of pathnames may be specified by seperating directory names with a colon, : on Unix systems, or a semicolon, ;, on MSDOS systems. Using a list of directories for the TMP subop allows SST to use a different device for temporary files if the first device fills up. This is particulary useful under MSDOS, where the first TMP directory is typically on a RAM disk (for speed), with the alternate directory on a hard disk (for volume). Currently only the first two directories given in the list are recognized.

WARNING[on|off]
Turn warning messages on or off. The save option may be used to control the generation of warning messages when the SAVE command creates a backup file of an existing saveset (see SAVE).

SST echoing parameters

In its default state, SST will echo all commands as they are read from a file, but it will not echo commands as they are executed within a loop or macro. Echoing commands as they are read from a file is controlled by the batch option of the ECHO subop. If we specify `ECHO[batch=on]' then commands are echoed; `ECHO[batch=off]' will cause commands to be read silently. For convenience, `batch=' can be omitted.

If a file is run with the ECHO[off] option, the batch file is run with echoing turned off. When the batch file exits the batch echo flag is restored to its original value. Other options are available (see RUN).

Setting `ECHO[verbose=on]' will cause SST to echo each command just before it is executed. This means that you can see exactly what commands SST is executing. This is particularly useful when debugging command files. An equivalent form, `VERBOSE[on]' may also be used.

By default, SST does not print commands inside of loops, IF statements and macros before they are executed. The ECHO[loop=on|off] and ECHO[macro=on|off] subops can be used to control echoing inside of loops (including IF statements) and macros respectively.

Setting the prompt

The primary SST prompt can be changed using the CONFIG PROMPT command. The prompt can be changed to any string by specifying the string as an argument to the PROMPT subop. There are several special character sequences that are expanded within the prompt before it is printed:

Sequence        Expansion
--------        ---------
$h              Current history number
$s              Blank space
$t              Current time
$e              Escape character (ASCII 27)

Additionally, variable references can be contained in the prompt string. These references are expanded each time the prompt is printed.

In order to prevent prompt and variable references from expanding when the command is executed (instead of when the propmt is printed), all metacharacters should be prefixed by the escape character (backslash). The following example demonstrates how to change the prompt string:

SST1> rem this is what the default prompt looks like
SST2> config prompt[sst\$h>\$s]                #Change the prompt
sst3> rem this is what the new prompt looks like

Changing SST's metacharacters

Three of SST's metacharacters can be changed -- the HISTORY, MACRO and ARRAY metacharacters. This might be useful if you use one of the metacharacters for other purposes often (for example, $ on VMS systems is often included in filenames) or you prefer a certain metacharacter (UNIX csh users are probably used to ! as a history character). To change the metacharacters use the CONFIG command and the HISTORY, MACRO and/or ARRAY subops. The arguments to each of the subops should be the the string meta= followed by a backslash (\) and then followed by the desired metacharacter. Below are some common mappings:

History Macro   Array           Comments
------- -----   -----           ---------

%       @       $               Default
!       @       $               Use csh history metacharacter
%       $       $               Same macro and array metacharacter
%       @       @               Avoid problems with $ on VMS

The MACRO and ARRAY metacharacters can be identical. In this case the MACRO filter is applied first and the ARRAY filter is applied only if the MACRO filter could not find the listed macro. If neither the array or macro exist, an error message is printed. The HISTORY metacharacter should be unique.


CONTINUE -- jump to next iteration in a loop

Synopsis:
CONTINUE

Continue to the next iteration of a FOREACH, FOR or WHILE loop. If more than one loop is in progress, the innermost loop is terminated -- it is an error to issue the CONTINUE command outside of a loop. For more information on SST loops see the respective topics.

Example

SST1> FOREACH (i; 1 2 3 4 5) {         # Simple loop to illustrate CONTINUE
1> IF ($i % 2 == 0) CONTINUE            # Skip even numbers
1> ECHO Iteration number $i             # Echo even numbers
1> }
Iteration number 1
Iteration number 3
Iteration number 5
SST2>


COVA -- compute descriptive statistics

Synopsis:
COVA VAR[variable list] options

The COVA command computes descriptive statistics such as means, standard deviation, ranges, and correlations on a set of one or more variables. By default only univariate statistics are calculated. The optional COV subop can be used to include a matrix of correlations and covariances for the variables listed in the VAR subop.

Required subops

VAR[variable list]
Compute statistics for each variable in variable list.

Optional subops

BYVAR
By default, the COVA command considers an observation to be valid only if it is valid for all variables listed in the VAR subop. If the BYVAR subop is specified then the univariate statistics will be computed independently -- missing observations in one variable will not be considered missing in all other variables.

COV
The COV subop provides both correlations and covariances; correlations are printed below the diagonal and variances and covariances are printed above the diagonal.

COVMAT[matrix]
the COVMAT subop allows the (symmetric) covariance matrix of the variables to be retrieved in matrix.

IF[expression]
Restrict the active observations to those for which expression is true.

OBS[observation list]
Restrict the active observations to those listed in observation list.

TIME
Display a summary of the time used by this command.

Example

To obtain statistics for all variables:

cova var[*]

To obtain the mean of x when y equals one:

cova var[x] mean if[y==1]


CVTSAV - convert savesets to new format

Synopsis:
cvtsav filename options

The cvtsav program converts savesets created by SST version 1.8 and earlier to those used by SST versions 1.9 and up. To convert a saveset, run the cvtsav program and pass as an argument the name of the saveset to be converted:

cvtsav bkw

The old version of the saveset bkw will be saved in a file with the same name and the extension .old.

Options

The following options are supported by cvtsav:

-k
Keep the results of a partially completed conversion when an error is encountered. This option can be used to try to recover data from a corrupted saveset.

-o file
Write the converted saveset to file instead of overwriting the input file.

-v
List the actions performed by the conversion program as they are executed.


DATA -- input formatted data

Synopsis:
DATA FMT[data list] FILE[filename] options

Input integer and string data from a formatted file. Column locations of the variables are specified using the FMT subop. A period or MD in a field is translated as missing data (except for string fields).

Required subops

FMT[data list]
Specification of column locations of variables, along with format infor- mation. Examples follow:

FMT[a 1-3 b 4]              # Reads variable a from columns 1-3
                              and variable b from column 4
FMT[a 1-3 b 4-4]            # Same
FMT[a b c 1-12]             # Reads variables a, b, c from equal
                              length fields 1-4, 5-8, 9-12
FMT[a 1-2 (P) b 4]          # Reads variable a in packed decimal
                              format, variable b in integer format
FMT[a 1-9 (S) b 4]          # Reads a as a string containing
                              character data
FMT[a 1-2 (bn) b 3-5 (bz)]  # Reads a treating blanks as missing
                              data, and reads b treating blanks
                              as zeros (the default)
FMT[/1 a 1-3 /2 b 2-5]      # Reads a from columns 1-3 of record 1
                              and b from columns 2-5 of record 2
FMT[a 1-3 (MD=-99)]         # Reads a with -99 translated to
                              missing data
FMT[a 1-3 (P,MD=-99) b 4]   # Reads a in packed decimal, with -99
                              translated to missing data
FMT[a 1-3 (bn,MD=-98,-99)]  # Reads a with blanks, -98, and -99
                                 translated to missing data

FILE[filename]
The file that the data is to be read from.

Optional subops

BYVAR

LENGTH[integer]
The length of a record, required if the data comes in fixed length records without embedded newlines at the end of each record (typically IBM).

NOBS[integer]
Number of observations in the data set.

RECORDS[]
Number of records (lines or cards) per observation; the default is one.

TIME
Display a summary of the time used by this command.

Example

Supposed a file, input.dat, has the following data

123
456
789
012

The following commands are executed in SST

SST1> DATA FILE[input.dat] FMT[/1 x 2 /2 y 1-2] RECORDS[2]
SST2> print var[x y]

  Obsno             x                 y
     1:       2.00000          45.00000
     2:       8.00000           1.00000


DATE -- assign dates to a time series

Synopsis:
DATE START[starting date] PER[integer]

The first observation is assigned the date specified in the START subop. Dates are normally specified in the form `period : subperiod'. The number of subperiods is specified in the PER subop and should be a positive integer. If the PER subop is omitted, a periodicity of one (i.e., annual data) is assumed. If no subperiod is specified for the starting date in the START subop, the starting subperiod is assumed to be the first subperiod of the starting period. If this command is run, then the standard internal numbering of observations by sequential integers, corresponding to the variable obsno, is replaced by the dating syntax of this command. Thereafter, the dating syntax must be used in the OBS subop. SST does not currently permit use of the date syntax in IF subops, so that it cannot be used to select subperiods for analysis.

Required Subops

START[starting date]
The date for the first observation.

Optional Subops

PER[integer]
The number of subperiods in a period.

Example

With monthly data beginning in June of 1974, give the command in the following form:

date start[1974:6] per[12]
cova var[gnp] obs[1974:6-1988:5]

For quarterly data beginning in the first quarter of 1948, use:

date start[48:1] per[4]

Note that SST works correctly whether you number the years starting from 48 or 1948, so long as your usage is consistent. For annual data beginning in the year 1896, try:

date start[96:1] per[1]

The above command could be shortened to:

date start[96]

since the default value for PER is one.


DEFINE -- define a user function

Synopsis:
DEFINE name(arg1, ..., argn) = SST expression

Users can define their own functions using the DEFINE command. The expression must be free of syntax errors but variables and other functions that are referenced by the expression need not exist until it is actually executed. When the defined function is called, the dummy arguments (arg1, arg2, etc) will be replaced by the values of the expressions used in their place in the function call.

Example

A user function to standardize an expression by deviating it from its mean and then dividing by its standard deviation is given below:

SST1> DEFINE stand(x) = (x - mean(x)) / stddev(x)
SST2> set ssr = stand(sr)


DEL - delete a variable or other data element

Synopsis:
DEL options

Deletes variables or other data elements currently in memory (or temporarily swapped to disk).

Optional subops

ARRAY[array list]
Delete the arrays listed.

FUNC[function list]
Delete the functions listed.

MACRO[macro list]
Delete the macros listed.

MAT[matrix list]
Delete each matrix contained in matrix list.

TIME
Display a summary of the time used by this command.

VAR[variable list]
Delete the variables contained in variable list.

Example


SST1> LOAD FILE[bkw]
SST2> DEFINE add(a,b) = a + b           # Set up some SST objects
SST3> MACRO ls LIST
SST4> LIST

---- Variables ----
deldpi      50  Wed Jul 26 20:32:06 1989 real disposable income growth rate
dpi         50  Wed Jul 26 20:32:06 1989 real disposable income per capita
pop15       50  Wed Jul 26 20:32:06 1989 percentage population under 15
pop75       50  Wed Jul 26 20:32:06 1989 percentage population over 75
sr          50  Wed Jul 26 20:32:06 1989 average personal savings rate

---- Functions ----
add          2

---- Macros ----
ls           0

SST5> DEL VAR[dpi sr] MACRO[ls]         # Delete some objects
SST6> LIST

---- Variables ----
deldpi      50  Wed Jul 26 20:32:06 1989 real disposable income growth rate
pop15       50  Wed Jul 26 20:32:06 1989 percentage population under 15
pop75       50  Wed Jul 26 20:32:06 1989 percentage population over 75

---- Functions ----
add          2

SST7> DEL VAR[pop*]                     # Wildcards may be used in VAR
SST8> LIST

---- Variables ----
deldpi      50  Wed Jul 26 20:32:06 1989 real disposable income growth rate

---- Functions ----
add          2

SST9>


DIR -- list files in a directory

Synopsis:
DIR path

The contents of the directory specified by path are displayed. If path is omitted, the contents of the current directory are displayed (see CD for more information).

Example

SST1> DIR                               # Show contents of current directory

.                 <DIR>      7-16-89  11:51a
..                <DIR>      7-16-89  11:51a
SST.LOG               1212   7-30-89   4:55p
DATA              <DIR>      7-27-89   9:52p
BKW.DAT               3300   7-26-89   8:23p
BKW.SAV               1539   7-26-89   8:32p
DEMO.CMD               796   7-26-89   8:23p
SST.CMD                219   7-27-89  10:47p
        8 File(s)  317440 bytes free
SST2> DIR data                          # Show contents of subdirectory 'data'

.                 <DIR>      7-27-89   9:52p
..                <DIR>      7-27-89   9:52p
BLACKER.DAT            796   7-26-89   8:23p
DABNEY.DAT             199   7-26-89   8:43p
FLEMING.DAT            160   3-17-87   8:00a
LLOYD.DAT               33   7-04-89   6:51p
PAGE.DAT                 5   7-26-89   9:45p
RICKETTS.DAT           126   7-26-89   9:45p
RUDDOCK.DAT             14   6-26-89  10:09p
        9 File(s)  316416 bytes free
SST3>


DURAT -- estimate discrete hazard models

Synopsis:
DURAT DEP[variable] IVALT[label:varlist ...] options

DURAT estimates discrete hazard models by the method of maximum likelihood using an iterative Newton-Raphson procedure. The dependent variable, specified in the DEP subop, is the observed duration or spell length for the observation. Spell lengths take only integral values 1,...,T. The binary variable in CENSOR equals zero if the observation is censored (i.e., if the end of the spell was not observed before the termination of the sampling process) and equals one otherwise. The escape probability for each period is assumed to be of the form PHI(beta x_it) where PHI() denotes the standard normal distribution function and x_it is the vector of independent variables for the period specified in the IVALT subop. Each variable list in the IVALT subop consists of T variable names -- observations on the variable described by the label for each of T possible periods of, e.g., an unemployment spell. Values of the independent variable for periods after the end of an unemployment spell are not accessed, but should have non-missing values for proper sample selection.

Required subops

DEP[variable name]
The dependent variable of the discrete hazard model.

IVALT[label:variable list ...]
The independent variables, as described above.

Optional subops

CENSOR[variable name]
A binary variable indicating which observations are not censored. If this subop is omitted, it is assumed that all observations are non-censored.

COEF[matrix name]
Save the final values of the parameters in matrix name.

CONVG[number]
The maximum value of the gradient vector (in the norm of the estimated covariance matrix) before the search is terminated. The default value is 0.001.

COVMAT[matrix name]
Save the covariance matrix in the specified matrix. This matrix is not usually printed or saved. See the PRT subop for information on printing the covariance matrix.

IF[expression]
Restrict the active observations to those for which expression is true.

MAXIT[integer]
Specify the maximum number of iterations to run before terminating the search. By default, the maximum number of iterations is 15.

LOGISTIC
Use a commutative logistic in place of the default normal distribution function.

METH[]
No definition available at present.

OBS[observation list]
Restrict the active observations to those listed in observation list.

PERDUM
If present, time-period dummy variables Period1 through PeriodT, where T is the number of periods, are added as explanatory variables. If this subop is used, then constants should be excluded from the independent variables.

PRT[n]
Controls the amount of information that is printed at each iteration. The default level of printing is 1 and includes the value of the likelihood function at each iteration, the stepsize and the convergence criterion. To have SST print out the covariance matrix after the last iteration, set n to 2. If n is 3, SST will also print the parameter values at each iteration. To aid in debugging, SST will print the numerical derivatives on the first iteration if n set at 5.

START[starting values]
Specify the starting values for the parameters listed in the IVALT subop. By default all parameters start with a value of zero.

STEP[number]
Specify a fixed stepsize to be used at each iteration in the search. By default SST tries to pick an optimum stepsize at each iteration.

TIME
Display a summary of the time used by this command.

Example

Suppose we have a three wave panel consisting of unemployed individuals. Let spell denote the wave in which an individual was rehired. Some workers are still unemployed at the end of the panel, so we code a variable unemp3 which equals one if the worker is unemployed all three periods and equals zero otherwise. There are two independent variables, x and z, which are measured each period of the panel:

durat dep[spell] ivalt[x: x1 x2 x3 z: z1 z2 z3] censor[unemp3]


ECHO -- print strings to the output device

Synopsis:
ECHO string

The echo command prints string on SST's output. If the string ends with a colon (:) the trailing linefeed is suppressed. Additionally the following C escape sequences are recognized:

\n      print a newline
\r      print a carriage return
\t      print a tab

The ECHO command is most useful inside batch files to indicate progress when echoing is turned off.

Example

SST1> LOAD FILE[bkw]                    # Load data for use in this example
SST2> ECHO Entering loop
Entering loop
SST3> FOREACH (var; sr pop* dpi) {     # Run commands on the variables
1> ECHO Working on variable $var        # Show which variable we are at
1> REM Commands for execution go here   # Execute some command
1> }
Working on variable sr
Working on variable pop15
Working on variable pop75
Working on variable dpi
SST4>


EDIT -- command line editor

Synopsis:
EDIT command-specifier

The command line editor, invoked by the edit command, allows you to recall a command from the history list and edit it interactively. The command is recalled from the history list in much the same way as the history mechanism recalls commands. Unlike the syntax used for the history mechanism, however, a space should separate the the word EDIT and the history selector. Also, to recall the most recently excecuted command command in the history list, we use the special command edit last. Note that this is different from the history mechanism, which uses %% to recall the last command. Once the EDIT command has been entered, the selected command is displayed for editing. The basic editor commands are:

^F or Right Arrow       Move the cursor forward one character
^B or Left Arrow        Move the cursor back one character
^N or Down Arrow        Move the cursor down one line
^P or Up Arrow          Move the cursor up one line
^A or Home Key          Move the cursor to the beginning of the line
^E or End Key           Move the cursor to the end of the line
^T or Insert Key        Toggle between insert and overwrite mode
^J                      Insert a linefeed before the cursor
^O                      Insert a new line above the cursor
^D or Del Key           Delete the character under the cursor
^H or Delete            Delete the character before the cursor
^U                      Delete from the cursor to the start of the line
^W                      Delete the previous word (delimited by spaces)
^K                      Kill the rest of a line or delete the linefeed if
                        the cursor is at the end of the line
^L or ^R                Redraw the edited command
Return                  Exit the editor and execute the command
^C or Cntl Break        Quit the editor without executing the command

Initially the editor is in insert mode: printable, non-control characters are inserted before the cursor and the cursor is moved one position to the right. In overwrite mode typed characters replace the characters in the command.

The editor can be left on continuously by using CONFIG EDIT[ON]. In this case, all input to SST is through the editor.

Changing the key bindings

The command editor key bindings can be changed to allow any function to be bound to any key. When SST starts up it looks for the file sst.key or .sstkey in the current and home directories. If the file exists, it is read line by line and the editor binding table is updated accordingly. The format for a single line is:

keyname function #comment

The three fields must be separated by white space but any of the fields can be omitted. The keyname field gives the key that is to be rebound. The keyname can be one of the following:

  1. A single character
  2. A circumflex, `^', followed by a single character. This is interpreted as the control code corresponding to the character. So `^H' would be the same as ASCII code 8.
  3. A backslash followed by a decimal number representing the ASCII code for the character. This allows any keycode to be entered, even if it can't be represented as a printable character.
  4. A key name string. The following key names are recognized by SST (but they may not exist on all terminals):

    left    right   up      down    home    end     insert  delete  ESC
    

    In addition the keys F1, F2, ..., F10 are also recognized and correspond to the numbered function keys on the keyboard, if any.

  5. A prefix key followed by another keyname. The prefix keys are ^X and ESC by default. These may be changed by binding keys to the Control-X-prefix and ESC-prefix functions.

The function field gives the action that should occur when the key is pressed. If no function is present the key will not have any effect when it is pressed. See section Editor functions. The comment field, preceded by a hash (#), may be used to explain the function of the key in greater detail.

Editor functions

In the list of functions given below, the key sequence shown in parentheses gives the default key binding for each function.

backward-char (^B)
Move the cursor left one character.

beginning-of-line (^A)
Move the cursor to the beginning of the current line.

Control-X-prefix (^X)
ESC-prefix (ESC)
These functions should be bound to the prefix keys (which are ^X and ESC by default). Once these keys have been defined, the keyname for that key can be used as the prefix keyname in the sst.key initialization file.

delete-char (^D)
Delete the character under the cursor.

delete-backward-char (delete, ^H)
Delete the character before the cursor.

delete-backward-word (ESC delete)
Delete the word before the cursor. A word is defined as a sequence of characters containing no spaces.

delete-beginning (^U)
Delete from the current cursor position to the beginning of the line.

delete-end
Delete from the current cursor position to the end of the line.

delete-line
Delete the current line.

describe-bindings
List all the current key bindings.

describe-key
Describes the function currently bound to a key.

end-of-line (^E)
Move the cursor to the end of the current line.

execute (^M)
Execute the command being edited.

execute-check
If the command being edited does not end in a backslash, execute the command. Otherwise move the cursor to the end of the command and insert a newline. This corresponds to the default behavior of the return key when the editor is disabled.

execute-command
Execute an editor command. This function prompts for a command and then executes that command as if it had been called from the current cursor location.

forward-char (^F)
Move the cursor right one character.

help
Enter interactive help mode.

insert-history
Insert an event from the history list.

insert-tab (^I)
Insert enough spaces to move the cursor to the next tab stop. This function should be bound to the tab key as the editor does not know how to handle non-printing characters.

interrupt (^C)
Generate an interrupt.

kill-line (^K)
Delete the rest of the current line up to the linefeed; at the end of a line delete the the linefeed.

newline (^J)
Insert a newline at the current location.

next-line (^N)
Move the cursor down one line.

nil
This is the default function for unmapped characters.

open-line (^O)
Insert a newline above the current line and leave the cursor at the beginning of the new line.

overwrite-mode (insert)
Toggle between insert mode and overwrite mode.

previous-line (^P)
Move the cursor up one line.

print-history
Print the current history list.

redisplay (^L, ^R)
Redraw the screen.

save-noexec
Save the command being edited in the history list without executing it. This is equivalent to the :p command in the SST history mechanism.

self-insert-char
Insert character at the current location and move cursor right.

set-key
Bind a key to a function. This function prompts for a key and an editor command and binds the command to the key.

shell-command
Execute a program.

suspend (^Z)
Suspend SST and return to the shell (BSD Unix systems only).

previous-command
Replace the current buffer with the previous command from the history list. This function may be called multiple times to move backwards through the history list.


ENTER -- enter or change data from the keyboard

Synopsis:
ENTER TO[variable list] options

The ENTER command allows data to be entered or changed from the keyboard in an interactive editing mode. The program will prompt the user for data values on the variables specified in the TO subop in the range specified by the OBS subop. When finished with data entry, type `q' or `quit'.

Required subops

TO[variable list]
The list of variables which are to be edited or created.

Optional subops

IF[expression]
Restrict the active observations to those for which expression is true.

OBS[observation list]
Restrict the active observations to those listed in observation list.

TIME
Display a summary of the time used by this command.

Example

SST1> ENTER TO[year parts labor] OBS[1-3]
year(1) [ MD ]: parts(1) [ MD ]: labor(1) [ MD ]:
year(2) [ MD ]: parts(2) [ MD ]: labor(2) [ MD ]:
year(3) [ MD ]: parts(3) [ MD ]: labor(3) [ MD ]:
SST2> # Add and change the data
SST3> ENTER TO[year parts labor] OBS[2-5]
year(2) [ 1984.000000 ]: parts(2) [ 53.869999 ]: labor(2) [ 84.050003 ]:
year(3) [ 1985.000000 ]: parts(3) [ MD ]: labor(3) [ 29.250000 ]:
year(4) [ MD ]: parts(4) [ MD ]: labor(4) [ MD ]:
year(5) [ MD ]:
SST4> PRINT VAR[year parts labor]

  Obsno          year             parts             labor
     1:       1.98300e+003     35.43000          73.92000
     2:       1.98400e+003           MD          84.05000
     3:       1.98500e+003     14.32000          29.25000
     4:       1.98600e+003      9.50000           1.00020e+002
     5:            MD                MD                MD


EXIT -- exit a batch file

Synopsis:
EXIT return-status

Exit the current input file, returning control to the terminal. The EXIT command terminates the execution of commands from the command file regardless of whether it occurs inside SST control loops. Note that if EXIT is executed from the keyboard rather than from a batch file, it has the same effect as QUIT: it will exit SST completely. To exit SST completely from within a command file, use the QUIT command.

Return-status is an optional integer that sets the value of the status array (see ARRAY).

EXAMPLE

In order to avoid exiting from SST, this first example uses the SST batch file exitdemo.cmd, the contents of which are as follows:

# exitdemo.cmd -- demonstrates the EXIT command
FOREACH (i; 1 2 3 4 5) {
        ECHO Iteration number $i
        IF ($i > 2) EXIT
}
ECHO Done with exitdemo         # Note that this message will never be printed

To demonstrate both uses of the EXIT command, execute the following commands:

RUN exitdemo
EXIT     # note that this will take you out of SST, just like QUIT

Your output should look like this:

SST1> run exitdemo
# Exitdemo.cmd - demonstrate the EXIT command
FOREACH (i; 1 2 3 4 5) {
     ECHO Iteration number $i
     IF ($i > 2) EXIT
}
Iteration number 1
Iteration number 2
Iteration number 3
SST4> exit
D>


EXPAND command

Synopsis:
EXPAND VAR[variable list] options

The observations on the variables in VAR are taken sequentially from the start, ignoring the global and local sample vectors, and are moved in sequence to the locations that are active, given the RANGE, and given the OBS or IF subops. This command can be used, for example, to move a block of new observations so they are positioned following current observations.

Required subops

VAR[variable list]
Expand the variables listed.

Optional subops

IF[expression]
Restrict the active observations to those for which expression is true.

OBS[observation list]
Restrict the active observations to those listed in observation list.

TIME
Display a summary of the time used for this command.

TO[variable list]
Rename variables as they are acted upon. The number of variables listed in the VAR subop must agree with the number of variables listed in the TO subop.

Example

read to[x y] file[olddata] nobs[20]      # read old data set
read to[xn yn] file[newdata] nobs[10]    # read new data set
set d=obsno>20
expand var[xn yn] if[d]                  # relocate new following old
set x = d?xn:x                           # merge data sets
set y = d?yn:y


FIGURE -- combine multiple SST plots

Synopsis:
FIGURE { block of SST plotting commands 2

The FIGURE command allows you to combine a set of SST plots into a single figure. SST executes the block of commands given in the FIGURE command and superimposes all plotting output. By using the SIZE subop for the plotting commands, multiple plots can be combined into a single figure. If the TERM subop is used for any of the plotting commands, it must be identical for all of the plotting commands.

The FIGURE command does not take subops.

EXAMPLE

SST1> LOAD FILE[bkw]
SST2> FIGURE {   
1> SCAT VAR[sr pop*] SIZE[0 0 1 0.5]    # lower half
1> HIST VAR[sr pop*] SIZE[0 0.5 1 1]    # upper half
1> }


FOR -- execute commands in a loop

Synopsis:
FOR (init-command; test-expr; update-command) { block of SST commands 2

The FOR command allows you to run a set of SST commands while some condition holds. It is modeled after the for loops of the C programming language. The body for the FOR loop can either be a single command on the same line as the FOR keyword or a set of commands enclosed in braces. Execution proceeds as follows: SST executes the init-command; this command typically initializes values to be used in the loop. Next the logical expression test-expr is evaluated; if it is true, it performs the specified block of commands; otherwise it proceeds to subsequent commands outside the body of the loop. After the first pass through the set of commands, the update-command is executed and test-expr is re-evaluated. Again, if it is true it performs the commands. If the expression is false, it proceeds to the commands following the loop.

The FOR command does not take any subops.

Example

SST1> LOAD FILE[bkw]
SST2> FOR (CALC counter = 1; counter <= 50; CALC counter += 20) {
1> # Run the regression for a set of observations
1> COVA VAR[sr] IF[obsno < counter]
1> }
Warning: no valid observations

Variable:       sr     average personal savings rate

Mean                    9.04350      Standard deviation      4.46338
Minimum                 0.60000      Skewness               -0.43968
Maximum                16.85000      Kurtosis                2.02817
Valid observations        20


Variable:       sr     average personal savings rate

Mean                   10.04750      Standard deviation      4.51185
Minimum                 0.60000      Skewness               -0.28951
Maximum                21.10000      Kurtosis                2.73361
Valid observations        40


FOREACH -- execute commands in a loop

Synopsis:
FOREACH (name; list) { block of SST commands 2

The FOREACH command allows you to execute a set of SST commands for each name in a list. Whenever $name is encountered in the block of commands given in the FOREACH loop, it is replaced with the current value of the index variable, name. Any valid SST identifier may be used as the index variable. The list of values that the index variable is to take on should be separated by commas or spaces.

SST wildcard characters are also allowed in the FOREACH value list. The index variable will be set to each variable name that matches the wildcard specification, just as if that variable name had actually been given in the FOREACH value list.

A range may be specified in order to run a FOREACH loop over all integers from some starting value to some ending value. Instead of typing in a list of values for list, we can type "{start-stop2" where "start" and "stop" are both integers with start < stop. The BREAK and CONTINUE commands may be used to alter the flow of a FOREACH loop. For more information see BREAK or see CONTINUE.

The FOREACH command does not take subops.

EXAMPLE

SST1> LOAD FILE[bkw]
SST2> FOREACH (var; sr pop*) {   # Create a loop over a group of variables
1> ECHO Running loop on variable $var
1> REM Your command would go here
1> }
Running loop on variable sr
Running loop on variable pop15
Running loop on variable pop75


FREQ -- display one way frequency distribution

Synopsis:
FREQ VAR[variable list] options

A oneway frequency distribution is computed for the variables specified in the VAR subop. The resulting display shows the number of times each distinct value in the variable is taken. The IF and OBS subop control selection of the sample observations. There is no restriction of the number of distinct values that the variables in the VAR subop can take.

Required subops

VAR[variable list]
A frequency distribution is calculated for each variable listed in variable list.

Optional subops

IF[expression]
Restrict the active observations to those for which expression is true.

OBS[observation list]
Restrict the active observations to those listed in observation list.

TIME
Display a summary of the time used by this command.


GOTO -- jump to a label in a batch file

Synopsis:
GOTO label-name

Transfer control to the statement following the label label-name. A label is a line containing a label name followed by a colon (`:'). It is used only to indicate a location for the GOTO comand. The label name may be a string composed of letters, numbers or the underscore (`_') and must start with a letter or an underscore. There is one restriction on where labels can occur -- a label should not appear inside the body of a loop, an IF statement or a MACRO definition. The GOTO command is only valid inside a batch file and does not use any subops.

EXAMPLE

This example uses a batch file, since GOTO cannot be used with keyboard input. The contents of the batch file are as follows:

# Gotodemo.cmd -- demonstrates the GOTO command
GOTO bottom
REM The middle will be executed after the bottom
middle:
REM Middle of file -- we will exit now to avoid creating an infinite loop
EXIT
bottom:
REM This is the bottom of the file
GOTO middle

To run this example, execute the following command:

RUN gotodemo

The output should look like this:

SST1> RUN gotodemo
GOTO bottom
REM This is the bottom of the file
GOTO middle
REM Middle of file -- we will exit now to avoid creating an infinite loop
EXIT
SST8>


HELP -- access the online reference manual

Synopsis:
HELP topic subtopic ... HELP

The HELP command is used to access the online SST reference manual. This manual contains the same information as the printed SST reference manual. To specify information on a particular topics use the syntax:

help <topic>

You may exit the HELP utility by entering `q' when prompted for a subtopic.

Interactive commands

While in interactive mode you can either enter a subtopic name or a one character HELP command whenever SST asks you for a new topic. To get a list of commands available enter `?' followed by RET. The HELP commands are summarized below:

<subtopic>      skip to the specfied subtopic\n\
*               list available subtopics\n\
n, p            move to the next, previous topic in the manual\n\
u               move up from this topic\n\
g               move to a node specified by name\n\
l               move the the last node visited\n\
b               go to the beginning of this node\n\
q               quit the help command\n\
?               print a summary of commands\n\

SST help file (sst.hlp)

The SST HELP file, sst.hlp, contains all the text for the online version of the SST reference manual. If SST cannot find this file it will print an error message and you will not be able to access the manual. SST looks for the help file in several places:

  1. The directories specified in the SSTLIB environment variable (MSDOS and UNIX versions only). This variable has the same format as the PATH environment variable -- a list of directories separated by colons (or semicolons under MSDOS). You must set this environment variable before SST is entered in order for SST to look there.

  2. A system dependent directory defined when SST is installed. Your system manager is responsible for setting up this directory correctly.

  3. The directories listed in the current PATH environment variable.


HIST -- plot a histogram for a set of variables

Synopsis:
HIST VAR[variable list] options

A histogram of the variables specified in the VAR subop is plotted using the observations determined by the IF and OBS subops (if present). The range of the variables is divided into equal intervals (called bins) and boxes with height proportional to the number of observations in each bin are plotted. The bin spacing corresponds to the subquanta spacing of the x axis (see PARM).

When more than one variable is plotted, a cumulative count is kept for each bin and boxes are drawn for each subtotal as the variables are processed. Boxes can be plotted side by side using the horizontal option of the PARM subop and one in front of the other (smallest first) using the vertical option. If the total option is present, the total count for all variables is used to determine the height of the box for each bin and only the outline of the boxes is displayed (this is the default mode for one variable).

Required subops

VAR[variable list]
Specify which variables are to be plotted.

Optional subops

FILE[pathname]
Save output to the specified file. If the current terminal type does not support file output this option is ignored.

IF[expression]
Restrict the active observations to those for which expression is true.

LAB[string]
Generate a label for the graph.

OBS[observation list]
Restrict the active observations to those observations listed.

PARM[string]
Specify optional parameters to customize the display.

PRINT
If present, the output is sent to the printer rather than to the screen. When this option is used, TERM must also be present unless this has been set as an environment variable on your system.

SIZE[llx lly urx ury]
Change the size of the plot by specifying the coordinates of the lower left and upper right corners of the plot. Each of the coordinates should be in the range 0 to 1. See SIZE.

TERM[terminal]
Use the driver for terminal. See TERM.

TIME
Display the time required to execute the command.

XLAB[string]
Change the horizontal axis label.

YLAB[string]
change the vertical axis label.

EXAMPLE

SST1> LOAD FILE[bkw]
SST2> HIST VAR[pop15 pop75]


HISTORY mechanism -- re-execute a command

Synopsis:
HISTORY n %command

The HISTORY command takes an optional argument, n, which specifies the number of commands to be printed. A sample history list might look like this:

1  load file[bkw]
2  reg dep[sr] ind[pop15 pop75]
3  scat var[sr pop15 pop75]
4  list var[pop*]
5  history

Commands from the history list can recalled and executed using the SST history metacharacter -- the percent sign (`%'). Several formats are available for recalling a command. If we have just entered the commands listed above (making the current history number 6) we can recall commands as follows:

Selector type       Example     Command recalled
-------------       -------     ----------------
Absolute            %3          scat var[sr pop15 pop75]
Relative            %-4         reg dep[sr] ind[pop15 pop75]
Command search      %lo         load file[bkw]
Previous            %%          history

No space is allowed between the history metacharacter and the selector. SST will print the command after performing history substitution so that you can see the command that is executed.

Besides the selection commands given above, you can also select a range of commands using history numbers. To re-execute the 5th through 7th commands from the history list we use the command `%5-7'. History ranges can also be used with the EDIT command to edit several commands and rerun them.

The history mechanism supports 4 operators. An operator simply takes a previous command from the history list and performs some simple action on it. The syntax for specifying an operator is `%selector:operator' where selector is one of the forms mentioned above. The four operators and their functions are:

Op      Example          Description
--      -------          -----------
p       %5:p             Print the command without executing it
s       %reg:s/old/new/  Substitute 'new' for 'old' in the cmd (once)
gs      %co:gs/old/new/  Globally substitute 'new' for 'old'
e       %-2:e            Edit the command string

More than one operator can be applied by concatenating the operators after the selector. So we could say `%reg:gs/pop15/pop75/:e' to mean "recall the last command beginning with `reg' and globally replace `pop15' with `pop75' and then invoke the editor on the resulting command string". Notice that the history command `^old^new^' is equivalent to `%%:s/old/new/'.

For convenience, the history character is not expanded if it precedes a space, equals sign or open parenthesis. This allows the SST expression routines to be used without having to constantly retype the backslash character.


IF -- conditionally execute commands

Synopsis:
IF (test-expr) { block of SST commands 2 ELSE { block of SST commands }

The body for the IF statement can either be a single command on the same line as the IF keyword or a set of commands enclosed in braces. The logical expression for the IF statement can be any valid CALC expression. If it evaluates to exactly zero it is considered to be false, otherwise it is true.

The ELSE statement is also supported. It allows you to provide an alternate action if the logical expression of an IF statement is false. Following the ELSE keyword by another IF statement allows simple case-type statements to be set up:

if (abs(b1[3] < 1.0)) {
    reg dep[y] ind[x1 x2]
2 else {
    if (abs(b1[2] < 1.0)) {
         reg dep[y] ind[x1 x3]
    2 else {
        reg dep[y] ind[x2 x3]
    }
}

If you are going to use an ELSE statement you must enclose the IF-body and the ELSE-body in braces and the ELSE statement must appear on the same line as the closing brace of the IF-body.

The IF statement does not take any subops. The test expression in the IF statement is a scalar; if vectors appear, only their first components are used in testing the truth of the expression. If the test expression is true, then the block of SST commands is executed for all observations. This is quite different than the IF subop in other statements, which evaluates a logical expression observation-by-observation.


IMPORT command

Synopsis:
IMPORT FILE[filename] FUNC[symbol]

The IMPORT command allows user compiled functions to be incorporated into SST in a limited manner. The IMPORT command is currently only supported under SunOS 4.0 and above.

Imported functions can be used to evaluate scalar quantities in SST expressions. The functions can be used anyplace that scalar functions are normally allowed. Since the functions are compiled, they typically execute faster than a function written as a (uncompiled) SST expression. Also, the imported function mechanism allows individual customization of SST.

When executing an imported function, the normal SST error mechanisms are easily bypassed. It is the user's responsibility to insure that imported functions do not interfere with SST data structures or otherwise overwrite SST's internal variables. Improperly written user functions can cause SST to core dump or otherwise abort execution.

Required subops

FILE[filename]
The name of the object file which contains the function to be incorporated into SST. The .o extension must be included.

FUNC[symbol]
The name of the function to be incorporated. This is both the name of the function as it occurs in the object file and the name of the function within SST.

Error messages

There are a number of error messages which are specific to the IMPORT command. Understanding these error messages requires some knowledge of unix linking terminology and methods.

This error usually occurs when a symbol in the user function has the same name as a symbol defined by SST. The only solution is to rename the symbols in the file so that they do not conflict. Unfortunately, there are thousands of functions defined in SST, so conflicts can be difficult to locate and correct. One simple procedure is to append and underscore to the end of all user-defined functions. SST functions never end in an underscore.

This error occurs when the function name listed in the FUNC subop is not actually present in the object file.

The imported function references symbols which do not exist. This error can occur because the user references functions that are defined in the standard C library, but not used by SST. The only solution is to include definitions for all symbols referenced by the user-defined function.

This error can also occur if the symbol table has been stripped from SST. For systems which allow the use of IMPORT, the symbol table should be left in place when SST is installed.

The object file specified in FILE is not a valid object module. The file should be compiled with the cc command and must have its symbol table intact.

IMPORT must be able to locate the executable for SST in order to access its symbol table. The executable is searched for in the current path, specified by the PATH environment variable.

Example

The contents of the file user.c are:

int myfunc(stack, argc)
double *stack;
int argc;
{
    extern double atan2();

    if (argc != 2) return 0;
    stack[0] = atan2(stack[0], stack[1]);
    return 1;
}

After compiling this function (cc -c user.c) we may do the following:

SST1> IMPORT FILE[user.o] FUNC[myfunc]
SST2> calc atan(1)              # SST version
      0.78540
SST3> calc myfunc(1,1)          # user version
      0.78540


LABEL -- label variables in memory

Synopsis:
LABEL VAR[variable list] LAB[labels] VAL[value labels] LABEL VAR[variable list] LABEL FILE[file] LAB[saveset label]

The variable or variables specified in the VAR subop will be associated with the label supplied in the LAB subop. Variable labels should not exceed more than thirty characters. The VAL subop is used to associate value labels to particular values of a variable. Value labels can be no more than eight characters and must not contain spaces. Value labels are used in printing tables and frequency distributions. To delete any already existing labels information associated with the variables in the VAR subop, use the second form of the command given above.

If the FILE subop is present, the LABEL command adds, changes or deletes a saveset label. This label appears when the saveset is listed with the LIST command. If the LAB subop is present, the saveset label is overwritten (or created if it doesn't exist). If the FILE subop is present and the LAB subop is omitted, the label for the specified saveset is deleted.

Required subops

VAR[variable list]
Specify the variables to be acted upon. If the FILE subop is present, this subop is ignored.

FILE[filename]
Act on the label for the specified saveset.

Optional subops

LAB[label]
Specify the label name to be used.

MAT[label]
Label the specified matrices in addition (or instead of) the listed variables. Only the LAB subop is recognized for matrices.

VAL[value label list]
Associate value labels to particular values of a variable. A value label is a floating point value followed by the desired label (separated by a space). The label must be a string with no more than 8 characters. Spaces and commas are not allowed in the label. Any number of value labels can be given in the VAL subop.

Example

To give the label `female dummy' to the variable sex which takes the values one (for females) and zero (for males):

label var[sex] lab[female dummy] val[1 female 0 male]


LIST -- list information about variables

Synopsis:
LIST options

LIST provides information about variables or other SST objects either currently stored in memory or in an SST saveset. The default action is to list information about all variables, matrices, functions and macros stored in memory. This information includes the object name, size (i.e. number of observations, dimensions or argument count), the time it was last modified, and a short description (if available). By default, all information about the objects is listed -- this can be overridden using the NAMES subop. The FILE subop can be used to list saveset information instead of objects in memory.

Specific objects stored in SST's memory can be listed by specifying the object name and an optional list of objects. The valid SST objects are listed below.

Optional subops

ARRAY[array-list]
List currently defined arrays and their definitions. If a list of array names is specified, only those arrays are listed. Array definitions are not listed by default.

EDIT
List the key bindings for the editor. The key bindings are not listed by default.

FILE[filename]
List variables stored in filename instead of memory. Besides giving information about the variables in the saveset, the saveset modification time and saveset label are also printed.

FUNC[function-list]
List all currently defined functions. If a list of functions is included only those functions will be listed.

MAT[matrix-list]
List each matrix contained in matrix-list. If no argument is specified all matrices will be listed.

MACRO[macro-list]
List the macros currently defined by SST. If macro-list is included only those macros will be listed.

NAMES
List only the names of the specified objects.

TAPE[filename]
This subop is used in place of the FILE subop to specify that the saveset is contained on a tapedrive instead of a disk. The effect of this option is to minimize random access of the saveset. If the TAPE option is specified only the long form of the listing is available (i.e. NAMES is ignored).

TIME
Display a summary of the time used by this command.

VAR[variable-list]
List variable information. If a list of variables is given only information about those variables will be listed. Otherwise otherwise all variables are listed.

Example

SST1> LOAD FILE[bkw]             # Load some objects into memory
SST2> DEFINE add(a,b) = a + b
SST3> MACRO ls LIST
SST4> LIST                       # List all SST objects

---- Variables ----
deldpi      50  Wed Jul 26 20:32:06 1989 real disposable income growth rate
dpi         50  Wed Jul 26 20:32:06 1989 real disposable income per capita
pop15       50  Wed Jul 26 20:32:06 1989 percentage population under 15
pop75       50  Wed Jul 26 20:32:06 1989 percentage population over 75
sr          50  Wed Jul 26 20:32:06 1989 average personal savings rate

---- Functions ----
add          2

---- Macros ----
ls           0

SST5> LIST VAR                   # List just variables

---- Variables ----
deldpi      50  Wed Jul 26 20:32:06 1989 real disposable income growth rate
dpi         50  Wed Jul 26 20:32:06 1989 real disposable income per capita
pop15       50  Wed Jul 26 20:32:06 1989 percentage population under 15
pop75       50  Wed Jul 26 20:32:06 1989 percentage population over 75
sr          50  Wed Jul 26 20:32:06 1989 average personal savings rate

SST6> LIST VAR[pop*] MAT         # List variables and matrices

---- Variables ----
pop15       50  Wed Jul 26 20:32:06 1989 percentage population under 15
pop75       50  Wed Jul 26 20:32:06 1989 percentage population over 75

No matrices stored in memory

SST7> LIST NAMES                 # Short form

---- Variables ----
deldpi    dpi       pop15     pop75     sr

---- Functions ----
add

---- Macros ----
ls

SST8>


LOAD -- read data from a saveset

Synopsis:
LOAD FILE[filename] options

The LOAD command is used to read SST data from an SST saveset (created with the SAVE command). If no options are given, all objects contained in the saveset will be loaded into memory. Otherwise, only the indicated objects are loaded. Currently SST savesets support the following objects types:

Object type     Subop   Description
-----------     -----   -----------
variable        VAR     SST observation vectors (variables)
matrix          MAT     matrix
function        FUNC    User-defined functions (created with DEFINE)
macro           MACRO   User-defined macro (created with MACRO)

Objects that already exist in memory will be overwritten.

By default, the length of the current observation range used by SST is set to the length of the largest variable loaded from a saveset. This action is not performed if the current observation range has been set explicitly with the RANGE command. Additionally, the LOAD command will never set the current range to a length less than that set by a previous LOAD or ACCESS command. The auto range feature can be enabled and disabled using the command CONFIG RANGE[auto=on|off].

Versions of SST prior to 1.9 use a saveset format which is not compatible with the current savesets. A conversion program, `cvtsav', is available to convert between formats.

Required subops

FILE[filename]
The name of the saveset to be read. If no filename extension is specified, and neither the DIF nor the DBASE subops are included (see below), SST assumes an extension of .sav.

Optional subops

APPEND
Instead of overwriting variables, append data to the end of existing variables as they are read from the saveset. This option does not affect objects contained in the saveset which are not variables (i.e. matrices, functions, macros, etc). If variables in memory are of different lengths, then this subop locates the data at the end of the longest current variable.

DBASE
Read a file created in dBase III, dBase III PLUS, or dBase IV. Only variables can be stored in dBase files. Date fields within the dBase file are loaded as 6-digit integers in the form of 'yymmdd'; logical fields are read in as a 1 for true, and 0 for false. Character fields are turned into value labels for that variable. A unique identifier is assigned for each unique string encountered. Memo and float fields are ignored. If no filename extension was specified in the FILE subop, SST assumes an extension of .dbf.

DIF
Read a VisiCalc format saveset. Only variables can be stored in DIF savesets. If no filename extension was specified in the FILE subop, SST assumes an extension of .dif.

FUNC[function-list]
Load the specified functions. If function-list is omitted, all functions contained in the saveset will be loaded.

IF[expression]
Only load the observations for which the given expression is true. This option only affects variables read from the saveset. Currently the expression can only contain references to variables that are contained in memory.

MACRO[macro-list]
Read the listed macros into memory. If no macros are listed, all macros contained in the saveset will be loaded.

MAT[matrix-list]
Load only the specified matrices. If no argument is given, all matrices contained in the saveset will be retreived.

OBS[observation-list]
Only load the observations specified in observation-list.

TAPE[filename]
The TAPE subop can be used in place of FILE to optimize saveset access for sequential access devices. This subop also results in some savings in memory usage at the expense of speed.

TIME
Display a summary of the time used by this command.

TO
Change the names of the variables as they are read from the saveset and placed in memory. The number of variables listed in the TO subop must agree with the number listed in the VAR subop.

VAR[variable-list]
Read only the specified variables into memory. If no argument is present all variables contained in the saveset will be loaded. The names used to store the variables can be changed with the TO subop.

Checksums in savesets

SST uses checksums in savesets to indicate when data has been corrupted in a savesets. It is generally assumed that low level error detection and correction is present on the raw media used to store savesets, so only limited error checking is used. Checksum verification (during reads) can be turned off using the CONFIG command. Checksums are always generated during writing of savesets.

Checksums are present in savesets created by SST version 2.2 and greater. All savesets can be read and written by any version of SST (see Bugs below). The cvtsav command can be used to add checksum information to older savesets.

Examples

LOAD FILE[bkw]                      # load all objects in bkw.sav
LOAD FILE[bkw] VAR MAT              # load only matrices and variables
LOAD FILE[funcs] FUNC               # load functions from funcs.sav
LOAD FILE[bkw] VAR[pop15] TO[abc]   # load variable 'pop15' to 'abc'
LOAD FILE[big.1] VAR[a] FUNC[b] MAT # load variable 'a', function 'b'
                                    # and all matrices from 'big.1'

# Load observations 1-10 of variables pop15 and pop75
LOAD FILE[bkw] VAR[pop15 pop75] obs[1-10]


LOGIT -- estimation of binary and unordered logit models

Synopsis:
LOGIT DEP[variable list] IND[variable list] options

The LOGIT command estimates binary and unordered logit models by the method of maximum likelihood using an iterative Newton-Raphson procedure. The choice variable is specified in the DEP subop. The choice variable takes a finite number of values. In the case when the dependent variable is dichotomous (taken the values of zero and one, say), the choice probabilities are given by:

Independent variables are specified in the IND subop, as in the REG command. When the dependent variable contains more than two distinct values, a multinomial logit model is estimated. If 0 is the lowest numbered alternative, and j is another value of the dependent variable, then the choice probability for j is given by:

This corresponds to interacting the variables in IND with dummy variables for each alternative other than the lowest numbered one. SST does not currently permit estimation of ordered logit models.

Required subops

DEP[variable list]
The choice, or dependent variable. If more than one variable is specified, a separate logit is run for each variable listed.

IND[variable list]
The independent variables of the logit model.

Optional subops

COEF[matrix name]
Save the coefficient estimates in the indicated matrix. If more than one variable is listed in the DEP subop, a separate matrix should be given for each.

CONVG[number]
The maximum value of the gradient vector (in the norm of the estimated covariance matrix) before the search is terminated. The default value is 0.001.

COVMAT[matrix name]
Save the covariance matrix in the specified matrix. This matrix is not usually printed or saved. See the PRT subop for information on printing the covariance matrix.

IF[expression]
Restrict the active observations to those for which expression is true.

MAXIT[integer]
Specify the maximum number of iterations to run before terminating the search. By default, the maximum number of iterations is 15.

METH[]
Specifies the optimization method.

OBS[observation list]
Restrict the active observations to those listed in observation list.

PROB[variable name]
Save the predicted probabilities in the variable listed in the PROB subop. If multiple logits are to be performed a list of variable names should be given (one for each variable listed in the DEP subop). If the dependent variable has two categories, then the predicted probability is the estimated probability that the dependent variable takes its high value. If the dependent variable has more than two categories, so that a multinomial logit is performed, then the list must include a name for the probability of each alternative other than the lowest value. In the case of multiple multinomial logits, there must be a list of such variables for each dependent variable in order.

PRT[n]
Controls the amount of information that is printed at each iteration. The default level of printing is one and includes the value of the likelihood function at each iteration, the stepsize and the convergence criterion. To have SST print out the covariance matrix after the last iteration, set n to two. If n is three, SST will also print the parameter values at each iteration.

ROBUST
If present, the covariance matrix is calculated using the formula: (hboxHessian)^-1 (Outer Product of Score) (Hessian)^-1

START[starting values]
Specify the starting values for the parameters listed in the PARM subop. By default all parameters start with a value of zero.

STEP[number]
Specify a fixed stepsize to be used in the search (at each iteration). By default SST tries to pick an optimum stepsize at each iteration.

TIME
Display a summary of the time used by this command.

WEIGHT[variable list]
The WEIGHT subop is used to produce a Weighted Exogenous Sample Maximum Likelihood (WESML) estimate of the logit model. The variable list must contain one variable for each alternative, in the same order as the indexing of the dependent variable. If each alternative indexed j has frequency q_j in the population and s_j in the sample, and these differ due to sampling by alternative, then the weights q_j/s_j yield consistent estimates.


MATCH -- match data in a file and memory

Synopsis:
MATCH KEY[variable-name] FILE[filename] options

The MATCH command matches data in a file organized differently from data in RAM. The data is usually stored in an SST system file (saveset) which is specified in the FILE subop. The variable specified in the KEY subop is used to match observations in the file with data previously loaded into SST. It is necessary to have previously loaded or created the KEY variable during the SST session and a variable with the same name should be contained in the file. For each observation, SST looks at the value of the KEY variable in RAM and then searches for an occurrence of that value of the KEY variable in the file. Then SST reads the data for that observation into RAM. Only variables specified in the VAR subop are loaded from the file. If the VAR subop is omitted, all variables are loaded from the file except for the variables listed in the KEY subop. SST savesets can be created with the SAVE command SAVE.

If the FILE subop is not present, SST will read variables from memory instead of from a saveset. The operation of the MATCH command is unchanged. See section Using memory matching, below.

Required subops

KEY[variable-name]
The key to use to match data in memory with that in the file. A list of keys may also be specified -- if a unique match cannot be found on the first key, the second key is checked and so on. All keys must exist both in memory and in the saveset.

FILE[filename]
The name of the file to read the data from. If no FILE subop is present, SST will perform the matching operation using variables contained in memory.

Optional subops

BY[variable-name]
Use a different variable as the input (saveset) key. The number of variables listed in the BY subop must match the number listed in the KEY command.

BYLAB[variable-name]
Ordinarily, SST performs all matching based on the numeric value of the observations. If the BYLAB subop is present, the variables listed are matched by value label instead. The list of variables to this subop is a subset of the variables mentioned in the KEY subop above.

RP
By default, observations which cannot be matched are left unchanged if a variable being matched already exists in memory. If the RP subop is specified, unmatched observations are marked as missing data.

The RP subop also determines how value labels are copied from the input to output variables. By default, existing value labels in the output are not overwritten but new labels are added to the variable. If the RP subop is specified, any value labels which exist in both the input and output variables are changed to use the input variable labels.

TAPE[filename]
The TAPE subop can be used in place of FILE to optimize saveset access for sequential access devices such as tape drives. This subop also results in some savings in memory usage at the expense of speed when used with random access devices.

TIME
Display a summary of the time used by this command.

TO[variable-list]
Change the names of the variables as they are read from the saveset and placed in memory. The number of variables listed in the TO subop must agree with the number listed in the VAR subop.

VAR[variable-list]
Read on the listed variables from the file (by default, all variables contained in the saveset are loaded except for those listed in KEY). The names used to store the variables can be changed with the TO subop.

Using memory matching

The MATCH command can be used to reorganize data in memory by omitting the FILE subop. In this case, the operation proceeds as with a file, except that variables which already exist in memory are used. It is important to remember that unless the RP subop is specified, observations which fail to match the specified keys are not set to missing data. This is consistent with matching a variable from a file into an already existing variable in memory.


MATRIX -- evaluate matrix expressions

Synopsis:
MATRIX expression

Matrices can be created by running an SST command (such as REG with the COEF subop) or by entering them explicitly. An explicit matrix is created by surrounding a list of elements by braces, {2 (this is a change from SST 1.1 which used angle brackets). Column elements are separated by commas and the semicolon is used to indicate the end of a row. For example, the command

MATRIX {1, 2, 3; 4, 5, 6; 7, 8, 92

will print

             [  1]             [  2]             [  3]
[  1]      1.00000           2.00000           3.00000
[  2]      4.00000           5.00000           6.00000
[  3]      7.00000           8.00000           9.00000

This is the way that SST print matrices. As with the CALC statement, if an assignment is not specified the result of an expression is printed on the terminal.

SST supports the usual operations between matrices. Addition, subtraction and multiplication of matrices are denoted by +, - and *. The operations are performed whenever the matrices have the proper dimensions. There are two matrix division symbols, \ and /. If A and B are matrices then A\B and B/A correspond to left and right multiplication of B by the inverse of A. In general A\B denotes the solution X to the equation A*X = B and B/A denotes the solution to X*A = B. Left division A\B is defined whenever B has as many rows as A. If A is square, it is factored using gaussian elimination. The factors are then used to solve the equations A*X[:,j] = B[:,j] where B[:,j] denotes the jth column of B. The result is a matrix X with the same dimensions as B. If A is not square it is inverted in a least squares sense (using pseudo inverses). Right division operates similarly.

It is also possible to obtain element by element multiplication and division. If A and B have the same dimensions A .* B denotes the matrix whose elements are simple products of the individual elements of A and B. Multiplication and division of matrices by a scalar also use the operators *, / and \. In addition, scalar expressions can use the .*, ./ and .\ operators (they are equivalent to *, / and \ respectively).

One additional unary operator is available for use with matrices -- the transpose operator, '. The transpose operator should follow a matrix expression and will cause the rows and columns of the expression to be switched. Thus if we had assigned the value of our explicit matrix from above to the variable x we could set y to the transpose of x with the following command:

MATRIX y = x'

Element-by-element relational operators are supported for matrices, with A .< B denoting an array whose elements are one if the relation holds for the corresponding elements in A and B, and are zero otherwise. Relational operators such as .<=, .==, and .!= are defined similarly. Relational operators other than element- by-element are not supported.

Assignment operators are similar to those used for obsv's. Simple assignment and assignment operations (+=, -=, ..., .*=, ./=, .\=) are all supported. The increment and decrement operators cannot be used with matrices.

The conditional operator can be used in matrix expressions but only if the logical-expr evaluates to a scalar. The true-expr and false-expr parts of the operator can be of any data type (including matrices).

The following additional operators are available for matrices:

     B = inv(A)         inverse of A (using LU algorithm)
     B = ginv(A)        generalized inverse of A (Moore-Penrose)
     {U,D,V2 = svd(A)   singular value decomposition of a mxk matrix A,
                        A = UDV', where U is mxk, D and V are kxk,
                        U and V are column orthonormal, D is diagonal
     B = A'             transpose of A
     y = tr(A)          returns trace of A
     y = det(A)         returns determinant of A
     chol(A)            Cholesky decomposition of positive definite A,
                        A = B'B, B upper triangular
     B = diag(x)        returns diagonal matrix with vector x on diagonal
     y = vec(A)         returns vector containing rows of A, in sequence
     y = vech(A)        returns vector containing upper triangle of A,
                        row by row
     y = vecd(A)        returns vector containing the diagonal of A
     B = cumsum(A)      returns matrix containing the cumulative sums of
                        the elements in the columns of A
     B = mat(x)         converts variable to a column matrix
     x = var(A)         converts column matrix to a variable
     B = col(x,y,..,z)  converts variables to a matrix with columns x,y,...,z
     B = {A,C,...,D2    horizontally concatenates matrices
     B = {A;C;...;D2    vertically concatenates matrices
     B = kron(A,c)      Kronecker product of A and B
     B = ones(n,m)      returns a nxm array of ones
     B = zeros(n,m)     returns a nxm array of zeros
     B = eye(n,m)       returns a nxm matrix with ones down the diagonal,
                        zeros elsewhere; eye(n) returns the identity matrix
     B = toeplitz(x)    returns a band matrix with the first element of x
                        down the diagonal, the second element of x one
                        place off the diagonal, etc.
     y = size(A)        returns a vector of length 2 with y[1] equal to the
                        number of rows of A and y[2] equal to the number
                        of columns of A
     B = reshape(A,n,m) reshapes A into a matrix of dimension nxm, taking
                        the elements row-by-row
     y = maxindc(A)     returns a vector of indices of the rows of A that
                        contain the maximum elements in each column.
     B = submat(A,x,y)  returns a submatrix of A with rows corresponding
                        to the positive elements of the vector x, and 
                        columns corresponding to positive elements of 
                        the vector y

Example

SST1> MATRIX x = {1,2,32'       # create two column vectors
SST2> MATRIX y = {4,5,62'
SST3> MATRIX x' * y             # take their inner product
                [  1]
   [  1]     32.00000

SST4> MATRIX A = {2,1,-1; 1,2,0; 0,1,32
SST5> MATRIX invlu(A)           # calculate inverse using LU decomposition
                [  1]             [  2]             [  3]
   [  1]      0.75000          -0.50000           0.25000
   [  2]     -0.37500           0.75000          -0.12500
   [  3]      0.12500          -0.25000           0.37500


MLE -- maximum likelihood estimation

Synopsis:
MLE LIKE[expression] GRAD[expression list] PARM[parameter list] options

The log likelihood function, specified in the LIKE subop, is maximized using the algorithm of Berndt, Hall, Hall, and Hausman. This method requires the user to specify derivatives of the log likelihood with respect to the parameters in the GRAD subop. These derivatives should be listed in the same order in which the parameters are listed in the PARM subop. The user may optionally specify starting values for the parameters in the START subop, again in the same order as in the PARM subop.

Required subops

LIKE[expression]
The log likelihood function to be maximized. This should be a function of existing SST variables and parameters listed in the PARM subop.

GRAD[expression list]
The gradients of the log likelihood function given in the LIKE subop with respect to the variables listed in the PARM subop.

PARM[parameter list]
A list of variable names which specify the parameters of the likelihood function.

Optional subops

COEF[matrix name]
Save the final values of the parameters in matrix name.

CONVG[number]
The maximum value of the gradient vector, in the norm of the estimated covariance matrix, before the search is terminated. The default value is 0.001.

COVMAT[matrix name]
Save the covariance matrix in the specified matrix. This matrix is not usually printed or saved. See the PRT subop for information on printing the covariance matrix.

IF[expression]
Restrict the active observations to those for which expression is true.

MAXIT[integer]
Specify the maximum number of iterations to run before terminating the search. By default, the maximum number of iterations is 15.

METH[]
No definition currently available.

OBS[observation list]
Restrict the active observations to those listed in observation list.

PRT[n]
Controls the amount of information that is printed at each iteration. The default level of printing is 1 and includes the value of the likelihood function at each iteration, the stepsize and the convergence criterion. To have SST print out the covariance matrix after the last iteration, set n to 2. If n is 3, SST will also print the parameter values at each iteration. To aid in debugging, SST will print the numerical derivatives on the first iteration if n is increased to 5.

START[starting values]
Specify the starting values for the parameters listed in the PARM subop. By default all parameters start with a value of zero.

STEP[number]
Specify a fixed stepsize to be used at each iteration in the search. By default SST tries to pick an optimum stepsize at each iteration.

TIME
Display a summary of the time used by this command.

Example

sst1> # Define functions to make the example more readable
sst2> DEFINE resid(b0,b1,b2) = ( y - b0 - b1 * x1 - b2 * x2 )
sst3> DEFINE llk(b0,b1,b2) = (-0.5)*resid(b0,b1,b2)*resid(b0,b1,b2)
sst4> DEFINE grad0(b0,b1,b2) = resid(b0,b1,b2)*1
sst5> DEFINE grad1(b0,b1,b2) = resid(b0,b1,b2)*x1
sst6> DEFINE grad2(b0,b1,b2) = resid(b0,b1,b2)*x2
sst7> #
sst7> LOAD FILE[bkw]                            # load the data
sst8> RENAME VAR[sr pop15 pop75] TO[y x1 x2]    # use more convenient names
sst9> #
sst10> MLE LIKE[llk(b0,b1,b2)] PARM[b0,b1,b2] \
1>     GRAD[grad0(b0,b1,b2), grad1(b0,b1,b2),grad2(b0,b1,b2)] \
1>     PRT[4] METH[2] STEP[1]

      Parm    Analytic derivative     Numerical derivative
       b0             4.83550e+02              4.83548e+02
       b1             1.60523e+04              1.60490e+04
       b2             1.19847e+03              1.19846e+03

                        Parameter                 Gradient
       b0             0.00000e+00              4.83550e+02
       b1             0.00000e+00              1.60523e+04
       b2             0.00000e+00              1.19847e+03


ITERATION  1:   OLD LLF =   -2830.02     STEP =           101.19
                NEW LLF =    -685.17     GRAD*DIREC =      42.39

                        Parameter                 Gradient
       b0            -5.38802                 25.05264
       b1             0.31203                 -4.89105e+02
       b2             1.57387                  1.82734e+02


ITERATION  2:   OLD LLF =    -685.17     STEP =            28.98
                NEW LLF =    -426.65     GRAD*DIREC =      17.84

                        Parameter                 Gradient
       b0            11.13145                 12.37261
       b1            -0.11391                  5.11386e+02
       b2             0.99837                -23.34211


ITERATION  3:   OLD LLF =    -426.65     STEP =            22.73
                NEW LLF =    -374.41     GRAD*DIREC =       4.60

                        Parameter                 Gradient
       b0            26.43354                 30.01518
       b1            -0.39507                  9.56666e+02
       b2            -1.52638                 75.38226


ITERATION  4:   OLD LLF =    -374.41     STEP =            11.27
                NEW LLF =    -364.37     GRAD*DIREC =       1.78

                        Parameter                 Gradient
       b0            28.73167                  3.15343
       b1            -0.44077                  1.65552e+02
       b2            -1.59501                 -4.63924


ITERATION  5:   OLD LLF =    -364.37     STEP =            17.45
                NEW LLF =    -363.21     GRAD*DIREC =       0.13

                        Parameter                 Gradient
       b0            30.31361                  3.39953
       b1            -0.46562                  1.12307e+02
       b2            -1.90668                  8.29822


ITERATION  6:   OLD LLF =    -363.21     STEP =            10.45
                NEW LLF =    -363.10     GRAD*DIREC =       0.02

                        Parameter                 Gradient
       b0            30.53355                  0.45132
       b1            -0.46988                 23.66103
       b2            -1.91174                 -0.28692


ITERATION  7:   OLD LLF =    -363.10     STEP =            16.88
                NEW LLF =    -363.09     GRAD*DIREC =       0.00

                        Parameter                 Gradient
       b0            30.57709                  0.32924
       b1            -0.46993                 10.57930
       b2            -1.92888                  0.80480


At convergence grad * dir = 0.000237



********** Maximum Likelihood Estimation ***********

Independent        Estimated             Standard                 t-
 Variable         Coefficient             Error               Statistic

       b0          30.57709               0.47598              64.24051
       b1          -0.46993               9.67168e-03         -48.58858
       b2          -1.92888               6.44494e-02         -29.92855

auxiliary statistics              at convergence      initial
log likelihood                      -363.09            -2830
number of observations          50


   Variance-Covariance Matrix

                   b0                b1                b2
      b0      0.22656          -4.55913e-03      -2.85195e-02
      b1     -4.55913e-03       9.35414e-05       5.51576e-04
      b2     -2.85195e-02       5.51576e-04       4.15372e-03

Reference

See E. R. Berndt, B. H. Hall, R. E. Hall, and J. A. Hausman, "Estimation and Inference in Non-linear Structural Models", Annals of Economic and Social Measurement, vol. 3, no. 4 (1974), pp. 653-665.


MNL -- estimate random utility models

Synopsis:
MNL DEP[variable name] IVALT[label:variable list ...] options

The MNL command estimates multinomial logit models by the method of maximum likelihood using an iterative Newton-Raphson procedure. The choice variable is specified in the DEP subop. The choice variable is assumed to take C distinct values ordered from low to high. The strict utility of each alternative is assumed to be a linear combination of K variables measuring the attributes of that alternative to the decisionmaker. Different variables measure the same attribute of different alternatives. The user supplies K labels corresponding to the different attributes. For each label the user specifies C variables, separated from the label by a colon, measuring the attribute described by that label for each of the C alternatives. An error message is issued if the variable specified in DEP has a different number of categories than the number of variables specified following each label or if different numbers of variables are specified after two labels.

Required subops

DEP[variable name]
Specifies the choice, or dependent, variable. The dependent variable is assumed to take on C different values, ordered from lowest to highest.

IVALT[label:variable list ...]
Specifies K sets of independent variables, each containing C different variable names. A single set is specified by providing a label followed by a colon (`:') and then a list of C variable names. Multiple sets are delimited by spaces.

Optional subops

CENSOR[variable list]
If CENSOR is not present, then the MNL procedure does list-wise deletion, eliminating an observation if there is missing data in any of the variables for any of the alternatives. If CENSOR is present without an argument, then the procedure eliminates an alternative for an observation if there is any missing data for that alternative, but does not delete the observation unless the chosen alternative is deleted, or all but the chosen alternative are deleted. If CENSOR is present with a list of variables, one for each alternative ordered from low to high, then the procedure deletes an alternative if the corresponding censoring variable for the observation does not equal one. The observation is deleted if there is missing data for any alternative for which the corresponding censoring variable is one, or if the chosen alternative is deleted, or if all except the chosen alternative are deleted.

COEF[matrix name]
Save the coefficient estimates in the indicated matrix.

CONVG[number]
The maximum value of the gradient vector in the norm of the estimated covariance matrix before the search is to be terminated. The default value is 0.001.

COVMAT[matrix name]
Save the covariance matrix in the specified matrix. This matrix is not usually printed or saved. See the PRT subop for information on printing the covariance matrix.

IF[expression]
Restrict the active observations to those for which expression is true.

MAXIT[integer]
Specify the maximum number of iterations to run before terminating the search. By default, the maximum number of iterations is 15.

METH[]
Specify the optimization method.

OBS[observation list]
Restrict the active observations to those listed in observation list.

PRED[variable list]
Save the values of beta^T x_i for each observation in the specified variable.

PROB[variable name]
Save the predicted probabilities in the variable listed in the PROB subop.

PRT[n]
Controls the amount of information that is printed at each iteration. The default level of printing is 1 and includes the value of the likelihood function at each iteration, the stepsize and the convergence criterion. To have SST print out the covariance matrix after the last iteration, set n to 2. If n is 3, SST will also print the parameter values at each iteration.

ROBUST
If present, the covariance matrix is calculated using the formula: (Hessian)^-1 (Outer Product of Score)(Hessian)^-1

START[starting values]
Specify the starting values for the parameters listed in the PARM subop. By default all parameters start with a value of zero.

STEP[number]
Specify a fixed stepsize to be used in the search (at each iteration). By default SST tries to pick an optimum stepsize at each iteration.

TIME
Display a summary of the time used by this command.

WEIGHT[variable list]
The WEIGHT subop is used to produce a Weighted Exogenous Sample Maximum Likelihood (WESML) estimate of the logit model. The variable list must contain one variable for each alternative, in the same order as the indexing of the dependent variable. If each alternative indexed j has frequency q_j in the population and s_j in the sample, and these differ due to sampling by alternative, then the weights q_j/s_j yield consistent estimates.

Examples

1. Suppose consumers choose between three modes of transportation: mode = 0 for automobile, mode = 1 for bus, and mode = 2 for subway. We assume that consumers base their choice on the cost of the mode (carcost, buscost, and subcost) and its convenience as measured by the time required to commute on that mode (cartime, bustime, subtime). The command to perform the multinomial logit estimation is:

mnl dep[mode] ivalt[cost:carcost buscost subcost \
                    time: cartime bustime subtime]

The convergence criteria would be set to their default values, as stated above.

2. It is also possible to perform binary logit estimation using the MNL command. Let y be a dummy variable taking the value 1 for success and 0 for failure. Suppose the probability of a success depends on two variables, x and z, e.g.:

First, we create vectors of ones and zeroes:

set one = 1
set zero = 0

Then we issue the following logit command:

mnl dep[y] ivalt[const:one zero x:x zero z:z zero]

Substitution of the corresponding strict utility values into the formula for multinomial logit choice probabilities shows that this does in fact give the same choice probabilities as the binary logit model specified above. Of course, this particular exercise could be performed much more easily using the LOGIT command.

Reference

Daniel McFadden, "Conditional Logit Estimation of Qualitative Choice Models", in P. Zarembka, ed., Frontiers of Econometrics (New York: Academic Press, 1973).


MORE filter -- cause output to appear one screen at a time

SST has a built in paging utility, called the MORE filter, which can keep output from scrolling off of the screen before you have a chance to read it. To use the MORE filter you must tell SST how many lines your screen has using the CONFIG command:

CONFIG MORE[lines=24]

Once this is done, when output is about to scroll off of the screen the MORE utility will issue a prompt on the bottom of your screen. It looks like this:

--More--

At this point you have several options. Hitting the space bar will allow another screen full of output to scroll by. If you hit the return key then only a single line of output will be printed. If you know that it's okay for any remaining output to scroll of the screen then you can hit the `c' key (for continue). This causes SST to continue printing output with no further interruptions. You can also suppress all remaining output by hitting `s'; this will "silence" output until a response from the terminal is required. Finally, to stop the current command use `q' (or `^C'). These options are summarized below:

Key         Action
---         ------

space       print another screen full of output
return      print a single line of output
c           continue without interruption
s           suppress output to the screen
q or ^C     quit the current command
?           print help options

You can change the behavior of the MORE utility using the CONFIG command:

CONFIG MORE[lines=20]           # set the screen size to 20 lines
CONFIG MORE[off]                # turn off the more filter
CONFIG MORE[on]                 # turn on the more filter - get the
                                  screen size from termcap
CONFIG MORE[long]               # enable more verbose prompt
CONFIG MORE[short]              # enable short prompt (shown above)

The lines= string can be omitted. If the number of lines is set to zero, the default setting, the more filter is turned off.


PAUSE -- temporarily stop execution

Synopsis:
PAUSE

Stops execution of SST commands until the carriage return is pressed. In processing batch files, users may want to inspect output as it is processed. Thus, inserting the PAUSE command after a command such as REG, which produces some output, would allow the user to examine the regression results before continuing processing (or ending the batch run). However, do not include PAUSE statements if batch files are being run in the background on UNIX or VMS (this warning does not apply to DOS users).

PAUSE is ignored if the current output is not the terminal.

Example

SST1> LOAD FILE[bkw]
SST2> COVA VAR[sr]

Variable:       sr     average personal savings rate

Mean                    9.67100      Standard deviation      4.48041
Minimum                 0.60000      Skewness               -5.56975e-003
Maximum                21.10000      Kurtosis                2.67630
Valid observations        50

SST3> PAUSE           # program won't continue until return is pressed
Press return to continue
SST4>


PLOT -- plot variables or an expression

Synopsis:
PLOT VAR[variable list] options PLOT EXPR[expression] DOMAIN[var{=domain2]

If the VAR subop is specified a line is drawn connecting valid observations for each variable listed (thus n variables give n separate lines). This set of connected points can be further reduced using the optional IF and OBS subops. If only one variable is given it is plotted on the y-axis with the observation number plotted on the x-axis. If two or more variables are given the plots are stacked on top of each other (this can be modified with the nomatrix option of the PARM subop).

If the EXPR subop is present, the listed expression is plotted on the y-axis as a function of the variable listed in the DOMAIN subop. The DOMAIN subop must contain a string of the form `var = start TO stop' where start and stop are scalar constants. The expression will be plotted versus the indicated variable using the current local sample vector, derived from the IF and OBS subops, to determine the points to be generated. In evaluating the expression, the lower bound of the domain will be assigned observation 1 and the upper bound will be assigned the maximum valid observation number of the current local sample vector.

Required subops

VAR[variable list]
Variables to be plotted.

EXPR[expression]
Expression to be plotted (used with the DOMAIN subop).

DOMAIN[var = min TO max]
Set the domain of independent variable var to lie between min and max. The variable name var must appear in the EXPR subop.

Optional subops

FILE[pathname]
Save output to the specified file. If the current terminal type does not support file output this option is ignored.

IF[expression]
Restrict the active observations to those for which expression is true.

LAB[string]
Generate a label for the graph.

OBS[observation list]
Restrict the active observations to those observations listed.

PARM[string]
Specify optional parameters to customize the display.

PRINT
If present, the output is sent to the printer rather than to the screen. When this option is used, TERM must also be present unless this has been set as an environment variable on your system.

SIZE[llx lly urx ury]
Change the size of the plot by specifying the coordinates of the lower left and upper right corners of the plot. Each of the coordinates should be in the range 0 to 1.

TERM[terminal]
Use the driver for terminal.

TIME
Display the time required to execute the command.

Example

SST1> LOAD FILE[bkw]                        # Load some data
SST2> PLOT VAR[(obsno) pop15 pop75]         # Plot pop15, pop75 vs. obsno


POISSON -- estimate Poisson regression models

Synopsis:
POISSON DEP[variable list] IND[variable list] options

The variable specified in the DEP subop should be a count, i.e., it should only take on non-negative integer values. The probability that the dependent variable takes the value y is assumed to be

where log lambda = x_i' beta and x_i denotes the vector of independent variables specified in the IND subop. Estimates are obtained by the maximum likelihood method.

Reference

J.A. Hausman, B.H. Hall, and Z. Griliches, "Econometric Methods for Count Data", Econometrica (1983).

Required subops

DEP[variable list]
The dependent variable should take only non-negative integer (i.e. count) values.

IND[variable list]
The independent variables in the Poisson model.

Optional subops

COEF[matrixname]
Save the final values of the parameters in matrixname.

CONVG[number]
The maximum value of the gradient vector in the norm of the estimated covariance matrix before the search is to beterminated. The default value is 0.001.

COVMAT[matrixname]
Save the covariance matrix under the specified matrix name. This matrix is not usually printed or saved. See the PRT subop for information on printing the covariance matrix.

IF[expression]
Restrict the active observations to those for which expression is true.

MAXIT[integer]
Specify the maximum number of iterations to run before terminating the search. By default, the maximum number of iterations is 15.

METH[]
No definition available at present.

OBS[observation list]
Restrict the active observations to those listed in observation list.

PRT[n]
Controls the amount of information that is printed at each iteration. The default level of printing is 1 and includes the value of the likelihood function at each iteration, the stepsize and the convergence criterion. To have SST print out the covariance matrix after the last iteration, set n to 2. If n is 3, SST will also print the parameter values at each iteration.

ROBUST
No description is available at present.

RSD[variable list]
Save the residuals in the specified variable. The number of variables given in the RSD subop should correspond to the number of variables listed in the DEP subop.

SRSD[variable list]
Save the studentized residuals to the specified variables.

START[starting values]
Specify the starting values for the parameters listed in the PARM subop. By default all parameters start with a value of zero.

STEP[number]
Specify a fixed stepsize to be used at each iteration in the search. By default SST tries to pick an optimum stepsize at each iteration.

TIME
Display a summary of the time used by this command.


PRINT -- print data currently in memory

Synopsis:
PRINT VAR[variable list] options

This command displays active observations of the variables listed in the VAR subop. Values are printed on the screen in up to four columns and organized by observation.

The PRINT command can also be used to display the values of functions and macros, using the corresponding subops.

Required subops

VAR[variable list]
Specify which variables are to be displayed.

Optional subops

ARRAY[array list]
Print hte definitions of the specified SST array variables. If no array variables are specified, all variables will be printed.

FUNC[function list]
Print the definitions of the specified functions. If no functions are listed, the definitions for all functions are given.

IF[expression]
Restricts the active observations to those for which expression is true.

MACRO[macro list]
Print the definitions for the specified macros. If no macros are listed, the definitions for all macros stored in memory are given.

MATRIX[matrix list]
Print the values of the listed matrices. The matrix list argument is required.

OBS[observation list]
Restricts the active observations to those included in the observation list.

TIME
Display a summary of the time used by this command.

Example

SST1> LOAD FILE[bkw]                    # Load some data
SST2> PRINT VAR[sr pop*] OBS[1-5, 9]    # Print pieces of the data

  Obsno            sr             pop15             pop75
     1:      11.43000          29.35000           2.87000
     2:      12.07000          23.32000           4.41000
     3:      13.17000          23.80000           4.43000
     4:       5.75000          41.89000           1.67000
     5:      12.88000          42.19000           0.83000
     9:       4.98000          46.64000           1.06000

SST3>


PROBIT -- estimate binary or ordered probit models

Synopsis:
PROBIT DEP[variable name] IND[variable list] options

The PROBIT command estimates a binary probit model by the method of maximum likelihood using an iterative Newton-Raphson procedure. The ordered n-chotomous dependent variable is specified in the DEP subop. The dependent variable takes a finite number of values corresponding to a continuous observed variable falling into a finite number of categories. If the dependent variable is binary, it takes its high value with probability PHI(beta x_i) and its low value with probability 1-PHI(beta x_i) where PHI(.) denotes the cumulative normal distribution function. Independent variables are specified in the IND subop, as in the REG command. The USER'S MANUAL describes the setup of the model in the ordered probit case.

Required subops

DEP[variablename]
The ordered n-chotomous variable to be used in the probit model.

IND[variable list]
A list of independent variables.

Optional subops

COEF[matrixname]
Save the coefficient estimates in the indicated matrix. If more than one variable is listed in the DEP subop, a separate matrix name should be given for each.

CONVG[number]
The maximum value of the gradient vector in the norm of the estimated covariance matrix before the search is to be terminated. The default value is 0.001.

COVMAT[matrix name]
Save the covariance matrix in the specified matrix. This matrix is not usually printed or saved. See the PRT subop for information on printing the covariance matrix.

IF[expression]
Restrict the active observations to those for which expression is true.

MAXIT[integer]
Specify the maximum number of iterations to run before terminating the search. By default, the maximum number of iterations is 15.

METH[]
No definition is currently available.

OBS[observation list]
Restrict the active observations to those listed in observation list.

PRED[variable list]
Save the values of beta' x_i for each observation in the specified variable. If more than one variable is listed in the DEP subop, a separate variable name should be included for each.

PROB[variable name]
Save the predicted probabilities in the variable listed in the PROB subop. If multiple logits are to be performed, a variable name should be given for each variable listed in the DEP subop.

PRT[n]
Controls the amount of information that is printed at each iteration. The default level of printing is 1 and includes the value of the likelihood function at each iterating, the stepsize and the convergence criterion. To have SST print out the covariance matrix after the last iteration, set n to 2. If n is 3, SST will also print the parameter values at each iteration.

ROBUST
No definition currently available.

START[starting values]
Specify the starting values for the parameters listed in the PARM subop. By default, all parameters start with a value of zero.

STEP[number]
Specify a fixed stepsize to be used at each iteration in the search. By default SST tries to pick an optimum stepsize at each iteration.

TIME
Display a summary of the time used by this command.

Reference

R. D. McKelvey and W. Zavoina, "A Statistical Model for Ordinal Level Dependent Variables", Journal of Mathematical Sociology (1975).


QUIT - exit SST

Synopsis:
QUIT

Exit the SST program. It is the user's responsibility to make sure that all variables are saved before exiting.

Options

MEM
Check to make sure that all memory is properly freed before exiting SST. This is used for debugging purposes.

TIME
Display a summary of the time spent in SST during this session.

EXAMPLE

SST1> quit
D>


RANGE -- set the active observation range

Synopsis:
RANGE options

RANGE sets the active observation range for all subsequent commands. Observations marked as missing by the RANGE command will not be used in any calculations until explicitly reset by another RANGE command. The OBS subop is used to specify the active observations. The IF subop modifies the observation list specified by OBS. The active observations will consist of those specified by the OBS subop for which the expression in the IF subop is true. If no subops are specified the default maximum range is set (observations 1-8000 on most systems). The maximum observation number for your system can be determined by typing `CALC maxobs'. The maximum observation number is affected only by the OBS subop and not the IF subop.

When data is loaded with the LOAD command without RANGE being set, then the range vector will be set to the longest loaded observation, unless the default RANGE option is turned off using the CONFIG command. A READ command or a SAVE command are not restricted by the range, and will process all observations that are active after the IF or OBS subops are applied. A WRITE statement is restricted by the range. Also see Getting Started

Optional subops

IF[expression]
Observations for which expression is missing or zero will not be included in the active observation range.

OBS[observation list]
Only observations specified in observation list will be included in the active observation range. Elements of the observation list can either be individual observation numbers or a range of observation numbers, specified by the lower and upper limits of the range separated by a dash.

RP
No definition currently available.

TIME
Display a summary of the time used by this command.

Example

SST1> LOAD FILE[bkw]            # Load some data
SST2> RANGE obs[1-10]           # Set range to first 10 observations
SST3> SET x10 = obsno           # Create a variable
SST4> RANGE IF [obsno < 52]     # Use IF instead of OBS
SST5> SET x51 = obsno           # Create a larger variable
SST6> RANGE                     # Use default range
SST7> SET xmax = obsno
SST8> LIST                      # See how long everything is

---- Variables ----
deldpi      50  Wed Jul 26 20:32:06 1989 real disposable income growth rate
dpi         50  Wed Jul 26 20:32:06 1989 real disposable income per capita
pop15       50  Wed Jul 26 20:32:06 1989 percentage population under 15
pop75       50  Wed Jul 26 20:32:06 1989 percentage population over 75
sr          50  Wed Jul 26 20:32:06 1989 average personal savings rate
x10         10  Tue Aug 29 11:09:25 1989
x51         10  Tue Aug 29 11:09:58 1989
xmax      8000  Tue Aug 29 11:10:24 1989

SST9> RANGE IF[obsno <= size(sr)]       # Use data length to set range
SST10> RANGE OBS[1-$(size(sr))]         # Another way to get data length


READ - input data from a file

Synopsis:
READ TO[variable list] FILE[filename] options

This command inputs data from a disk file in ASCII format to the variables specified in the TO subop. Data values should be separated by one or more of the following delimiters: blank spaces, commas, newline characters. If data are not in this form, the user may supply a FORTRAN format description (for more information, click here) using the FMT subop. The NOBS subop, specifying the number of observations to be read, is optional. However, including the NOBS subop improves the efficiency of data reading. READ recognizes as missing data a period, the characters MD, or an empty field indicated by commas with nothing between.

By default, the length of the current observation range used by SST is set to the length of the data read from the file. This action is not performed if the current observation range has been set explicitly with the RANGE command. Additionally, the READ command will never set the current range to a length less than that set by a previous READ or LOAD command. The auto range feature can be enabled and disabled using the command CONFIG RANGE[auto=on|off].

Required subops

FILE[filename]
Specify the name of the file to be read.

TO[variable list]
Specify the variables into which data from filename is to be stored. If the variables do not exist they will be created.

Optional subops

BYVAR
By default, the READ command expects data to be organized by observation. That is, the values for each variable associated with a particular observation are grouped together. If the BYVAR subop is specified, SST will expect the data to be organized by variable. In other words, it will read all of the data for one variable before moving on to the next variable.

FMT[format description]/
Specify a FORTRAN-style format statement for the data to be read.

LENGTH[integer]
Specify the length of a fixed logical record on systems (typically IBM) where new records are not identified by embedded new line characters.

NOBS[integer]
This subop specifies the number of observations in a file. If the number of observations is known, using the NOBS subop will increase the speed of the READ command in the case of a BYVAR read by precluding the need for SST to count the number of observations in the file.

APPEND
Append data to the end of existing variables. The default action is to overwrite existing variables. If the auto range feature is enabled, the range is set to include the maximum observation that was set.

TIME
Display a summary of the time used by this command.

VAL
Forces strings present in the input file to be turned in to value labels for that variable. A unique identifier will be assigned for each unique string encountered. For more information on value labels, see LABEL. If the VAL subop is not present, strings encountered in the input file generate an error.

Example

The contents of the file acsii.dat are:

    1.1     3
      2    -5e2
      3     4

With this data we may do the following:

SST1> READ TO[x y] FILE[ascii.dat]      # Read three observations with
SST2> PRINT VAR[x, y]                   # variable 'y' assigned the values
                                        # 3, -500, and 4, respectively
  Obsno             x                 y
     1:       1.10000           3.00000
     2:       2.00000          -5.00000e+002
     3:       3.00000           4.00000

SST3> READ TO [x y] FILE[ascii.dat] BYVAR   # Assign the value -500, 3 and 4
SST4> PRINT VAR[x, y]                       # to the first 3 observations of
                                            # the variable 'y'
  Obsno             x                 y
     1:       1.10000          -5.00000e+002
     2:       3.00000           3.00000
     3:       2.00000           4.00000

SST5> READ FILE[bkw.dat] TO[sr pop15 pop75 dpi deldpi]
# Read data from the file 'bkw.dat', which has 5 columns
SST6> LIST

---- Variables ----
deldpi      50  Wed Jul 26 20:32:06 1989
dpi         50  Wed Jul 26 20:32:06 1989
pop15       50  Wed Jul 26 20:32:06 1989
pop75       50  Wed Jul 26 20:32:06 1989
sr          50  Wed Jul 26 20:32:06 1989
x            3  Tue Aug 29 11:32:12 1989
y            3  Tue Aug 29 11:32:12 1989

SST7>


RECODE -- recode data values

Synopsis:
RECODE VAR[variable list] MAP[(value list)=value ...]

The RECODE command uses the MAP subop to provide a list of values for an old variable which is to be recoded into a new variable. Values not in the current observation range or not among those specified by the IF and OBS subops will be unaffected, unless the RP subop is included in which case they will be replaced with the missing data code.

The MAP subop specifies how the data should be recoded. Each argument to the MAP subop is a list of values enclosed in parentheses if the list consists of more than one value, followed by a new value to which the old values in the list are to be recoded. The word thru can be used to specify a range of values (e.g., `(1 thru 5)') and the word else is taken as the default case if no other range is found which includes the data. In addition, the hi and lo keywords may be used specify open-ended ranges. If a value falls into more than one range specified in the MAP subop, the last recoding is used.

The RECODE command is also useful for assigning missing values. MD (or .) may appear in either the left-hand-side or right-hand-side of the map (see example below).

Required subops

VAR[variable list]
Specifies a list of one or more variables to be recoded.

MAP[(value list)=value ...]
Specifies how the data should be recoded. For each variable given in the variable list of the VAR subop, all values specified in the MAP subop's value list will be replaced with the single value specified after the equals sign. This process may be repeated by separating subsequent (value list)=value assignments with spaces.

Optional subops

TO[variable list]
Rename the recoded variable while preserving the old variable. The number of variables specified in the TO subop must be the same as the number specified in the VAR subop.

RP
Marks observations not in the current observation range or not among those specified by the IF and OBS subops as missing.

IF[expression]
Only recodes observations for which expression is true.

OBS[observation list]
Only recodes observations given in observation list.

TIME
Display a summary of the time used by this command.

Example

Suppose the variable x takes the values 1, 2, and 3, but we want to make it into a 0-1 dummy variable with the values 2 and 3 coded into the 1 category:

RECODE VAR[x] MAP[1=0,(2,3)=1]

The same could be accomplished using:

RECODE VAR[x] MAP[1=0,else=1]

To recode values of 9 in variable y as missing data:

RECODE VAR[y] MAP[9=md]

Values for which y is not equal to 9 are unaffected. Alternatively, all missing values could be recoded to the value -99 by:

RECODE VAR[y] MAP[md=-99]


REG - ordinary least squares regression

Synopsis:
REG DEP[variable list] IND[variable list] options

The variables listed in the DEP subop are regressed on the variables listed in the IND subop. Any observation for which one of the variables has missing data will be deleted from the estimation part for that regression. A wide variety of regression diagnostics are available using the optional subops listed below.

The REG command can also be used for instrumental variables (two-stage least squares) estimation by specifying a list of instrumental variables in the IV subop. SST checks to make sure the order condition is satisfied -- that is, the number of variables specified in the IV subop must be greater than the number specified in the IND subop.

Required subops

DEP[variable list]
The variables listed in variable list are used as the dependent variables of the regression. If more than one variable is specified then a separate regression is produced for each variable listed.

IND[variable list]
Specifies the independent variables of the regression.

Options

AR1
Correct for first-order auto-correlation using a two step estimation procedure.

COEF[matrix list]
Save the coefficients of the regression in the matrix specified. A separate matrix should be specified for each variable listed in the DEP subop.

COVMAT[matrix list]
Save the covariance matrix of the regression in the matrix specified. The matrix list should contain one matrix name for each regression that is performed.

HAT[variable list]
Store the diagonal elements of the "hat" matrix in the indicated variable. If multiple regressions are run, a variable name should be specified for each regression.

IF[expression]
Restrict the active observations to those for which expression is true.

IV[variable list]
Perform a two stage least squares using instrumental variables. Variables in the IV subop can overlap with those in the IND subop if there are exogenous variables included in the equation. The number of instrumental variables, including exogenous variables, must be at least as large as the number of independent variables.

OBS[observation list]
Restrict the active observations to those listed in observation list.

PRED[variable list]
For each regression performed, store the predicted values of the dependent variable in the corresponding element of the variable list.

PRT[n]
To print the covariance matrix, specify a printing level (n) of 2. The default value of n is 1. Note that the PRT option does not save the matrix before printing.

RSD[variable list]
For each dependent variable, store the residuals of the regression in the corresponding element of the variable list.

ROBUST
Heteroskedasticity-consistent standard errors computed using White's method, as described in the User's Manual.

SRSD[variable list]
For each regression, store the studentized residuals in the corresponding element of the variable list.

TIME
Display a summary of the time used by this command.

WEIGHT[variable]
The WEIGHT subop is used to produce a weighted regression. It is equivalent to multiplying the dependent variable and each of the independent variables by the square root of the variable specified in the WEIGHT subop and then performing an unweighted regression. When this subop is used, the weighted rather than the original data are used to calculate the auxiliary statistics for the regression.

Example

To regress the variable y on x1, x2, and x3:

reg dep[y] ind[x1 x2 x3]

The above regression would not include a constant term unless one of the variables listed in the IND subop is constant. To include a constant term in this regression:

set one = 1
reg dep[y] ind[one x1 x2 x3] pred[yhat]

The predicted values would then be stored as the variable yhat. To run a series of regressions with the same independent variables:

reg dep[y1 y2] ind[one x1 x2 x3] rsd[r1 r2]

The residuals from the regression of y1 on x1, x2, x3, and a constant would be saved as the variable r1, while the residuals from the regression of y2 on x1, x2, x3, and a constant would be saved as the variable r2.

To estimate an equation by two-stage least squares, specify the included endogenous and exogenous independent variables in the IND subop. The complete list of exogenous variables in the model (the instrumental variables consisting of both included and excluded exogenous variables) is specified in the IV subop. For example, suppose we want to estimate the following equation by 2SLS: y_1i = B_1 + B_2 y_2i + B_3 x_i + u_i where y_2i is an included endogenous variable, x_1i is an included exogenous variable, and x_2i is an excluded exogenous variable. The appropriate REG command would be:

reg dep[y1] ind[one y2 x1] iv[one x1 x2]

In the first stage, y2 is regressed on the variables specified in the IV subop. In the second stage, endogenous variables in the IND subop are replaced by their predicted values.


REM -- insert remarks in SST batch files

Synopsis:
REM remarks

Remarks cause no action to be taken except for the remark to be echoed to the output device. The primary use of remarks is to label actions in a batch file. REM must occur at the start of each line of a remark.

SST also allows the use of the hash mark (#) to delimit remarks. Unlike REM, the hash mark may appear at the end of a line of code, rather than on a separate line. Note that everything between a hash mark and the end of the line will be treated by SST as a comment and ignored by the command preprocessor.

Example

SST1> REM This is a remark.  SST ignores it.
SST2> # This is also a remark.
SST3> LOAD FILE[bkw]  # Hash marks may be placed after a command
SST4>


RENAME -- rename variables

Synopsis:
RENAME VAR[variable list] TO[variable list] options RENAME MAT[variable list] TO[variable list] options

The variables listed in the VAR subop are renamed using the names in the TO subop. The same number of variables must appear in both subops. Renaming a variable using the name of a variable already existing in memory causes an error message to be printed. The MAT subop can be used in place of the VAR subop to rename matrices.

Required subops

VAR[variable list]
Specify which variables are to be renamed. Expressions are allowed.

MAT[variable list]
Specify which matrices are to be renamed. This subop is ignored if the VAR subop is present.

TO[variable list]
Specify the new names for the variables given in VAR.

Optional subops

TIME
Display a summary of the time used by this command.

Example

SST1> LOAD FILE[bkw]
SST2> RENAME VAR[pop15 pop75] TO [p15 p75]
SST3> LIST

---- Variables ----
deldpi      50  Wed Jul 26 20:32:06 1989 real disposable income growth rate
dpi         50  Wed Jul 26 20:32:06 1989 real disposable income per capita
p15         50  Wed Jul 26 20:32:06 1989 percentage population under 15
p75         50  Wed Jul 26 20:32:06 1989 percentage population over 75
sr          50  Wed Jul 26 20:32:06 1989 average personal savings rate

SST4>


REPLAY -- view stored output from previous commands

Synopsis:
REPLAY command-specifier

SST has the ability to store the output from commands and "replay" them without re-executing the command. The default is for the last 10 commands to be stored. To adjust the number of commands saved, use the following CONFIG command:

CONFIG REPLAY[lines=n]

This will direct SST to store the output from the n most recently executed commands.

To replay a command, use syntax similar to the SST history mechanism:

replay 7        #replay the output from command number 7
replay reg      #replay the output from the last reg command
replay 4-8      #replay the output from commands 4 through 8

If no arguments are specified to the replay command then all commands and their associated output will be displayed. The replay command also accepts two arguments that are not used with history:

replay last     #replay the output from the last command
replay all      #replay all stored output

The replay utility can be used in conjunction with the MORE filter. In this case, output which is suppressed by using the `s' option in the MORE filter is stored in the replay buffer for later recall.

The replay command can be configured using the CONFIG command, for more information.


RUN -- run a batch file

Synopsis:
RUN filename(arguments) options

If a filename is specified without an extension, SST assumes the extension .cmd. Other extensions for command files may be used if they are specified in the RUN command.

Arguments can be accessed within the command file as $1, $2, etc. Inside the command file $1 will be replaced by the value of the first argument, $2 by the value of the second argument and so on. The special form $* may be used to specify all arguments.

As with macros, command file arguments must be separated by commas.

Optional subops

ECHO[on|off]
If off is specified, commands will not be echoed to the terminal as they are run. The default setting is on. Echoing of command files can also be controlled with the CONFIG command.

HISTORY[on|off]
If off is specified, commands read from the batch file will not be stored in the history list. The default setting is on.

MORE[on|off]
Off causes the MORE filter to be disabled while the batch file is running. The default setting is on. The MORE filter can also be controlled with the CONFIG command.

REPLAY[on|off]
Turn the REPLAY filter on or off for the duration of the batch file The default is on. The REPLAY subop will save the output of a prespecified number of commands executed in a batch file. For more information, see CONFIG.

WARNING[on|off]
Turn on or off the warning messages generated by the batch file. The default setting is on.

Example

rem tsls.cmd - Two Stage Least Squares
rem Usage:  RUN tsls(y1, y2, x1, x2, z_vars)
rem                  $1  $2  $3  $4  $5

reg dep[$2] ind[$3 $4 $5] pred[y2hat]
reg dep[$1] ind[y2hat $3 $4] coef[b2sls]
set e2sls = $1 - b2sls(1)*$2 - b2sls(2)*$3 - b2sls(3)*$4
calc stdev(e2sls)


SAVE -- write data to a saveset

Synopsis:
SAVE FILE[filename] options

The SAVE command is used to write SST data to an SST saveset, which can be read using the LOAD command. If no options are given, all objects contained in memory will be saved to the saveset. Otherwise, only the indicated objects are saved. Currently SST savesets support the following object types:

Object type     Subop   Description
-----------     -----   -----------
variable        VAR     SST observation vectors (variables)
matrix          MAT     matrix
function        FUNC    User-defined functions (created with DEFINE)
macro           MACRO   User-defined macro (created with MACRO)

If the UPDATE subop is not present and the saveset already exists, it will be overwritten. If the UPDATE option is given, objects which already reside in the saveset will be updated and all other objects will be appended to the saveset.

If the saveset already exists, a backup saveset is created (with the extension .old). An optional warning message is available to indicate when a backup file has been created. The warning message may be turned on using the command CONFIG WARNING[save=on]. A backup saveset is not currently created when the UPDATE or APPEND subop is present.

SST savesets are stored in machine-independent format and may be transferred between machine types. All transfers must be binary transfers.

Required subops

FILE[filename]
The name of the saveset to be created. If the UPDATE subop is not present and the saveset already exists it will be overwritten. If no filename extenion is specified, and neither the DIF nor the DBASE subops are included, SST assumes a default extension of .sav.

Optional subops

COMPRESS
Compress data as it is written into a saveset (not implemented)

DBASE
Write a file readable by dBase III, dBase III PLUS, or dBase IV. Only variables can be stored in dBase files. If the VAL subop is present (see below), any variable for which any value labels have been defined is written as a character field containing the value label associated with the value of the variable for each observation. Otherwise, the numeric content of the field is written as a numeric field. If the filename in the FILE subop has no extension, SST assumes an extension of .dbf.

DIF
Write a VisiCalc format saveset. Only variables are stored in DIF savesets. If the filename in the FILE subop has no extension, SST assumes an extension of .dif.

FUNC[function-list]
Save the specified functions. If function-list is omitted, all functions contained in memory will be saved.

IF[expression]
Only save the observations for which the given expression is true. This option only affects variables written to the saveset.

LAB[string]
Label the save with string. This label appears when the saveset is listed with the LIST command.

MACRO[macro-list]
Save the listed macros. If no macros are listed, all macros contained in the memory will be saved.

MAT[matrix-list]
Save only the specified matrices. If no argument is given, all matrices contained in memory will be saved.

OBS[observation-list]
Only save the observations specified in observation-list.

VAR[variable-list]
Save only the listed variables. If no argument is present all variables contained in memory will be saved. The names used to store the variables in the saveset can be changed with the TO subop.

TAPE
If this subop is specified the saveset is padded with zeros to fill a complete block. This padding is necessary for savesets being written to tapedrives but need not be specified for disk storage devices. The TAPE subop can also be used in systems with restricted memory resources to decrease the available memory needed to create a saveset.

TIME
Display a summary of the time used by this command.

TO[names]
Change the names of the variables as they are written into the saveset. The number of variables listed in the TO subop must agree with the number listed in the VAR subop.

UPDATE
Update objects in the saveset. If an object which is to be saved already exists in the saveset, the saveset object will be updated. Objects which are to be saved but do not exists in the saveset are appended to the saveset. All other objects in the saveset are left intact.

VAL
When used in conjunction with the DBASE subop (above), variables with value labels associated with them are written as character fields, instead of the default numeric fields. If the DBASE subop is not present, this subop has no effect.

Examples

SST1> LOAD FILE[bkw]                        # Create some SST objects
SST2> DEFINE add(a, b) = a + b
SST3> MACRO ls list
SST4> SAVE FILE[demo] VAR[pop*] MACRO       # Save some variables and macros
SST5> SAVE FILE[demo] VAR[sr] TO[other] APPEND  # Add some more data
SST6> LIST FILE[demo]                       # See contents of saveset

Listing of objects in save set "demo.sav":
Created: Wed Aug 30 15:45:21 1989

---- Variables ----
pop15       50  Wed Jul 26 20:32:06 1989 percentage population under 15
pop75       50  Wed Jul 26 20:32:06 1989 percentage population over 75

---- Macros ----
ls           0

SST7>


SCAT -- generate a two-way scatter plot

Synopsis:
SCAT VAR[variable list] options

The SCAT command produces a two-way scatter plot of one or more variables. For each observation which is valid for all listed variables, a point is generated. The set of points can be further reduced using the optional IF and OBS subops. If only one variable is given it is plotted on the y axis with the observation number plotted on the x axis. Two-way scatter plots of all combinations of two or more variables are displayed in matrix format; this format can be modified with the nomatrix option of the PARM subop.

Required subops

VAR[variable list]
Variables to be plotted.

Optional subops

FILE[pathname]
Save output to the specified file. If the current terminal type does not support file output this option is ignored.

IF[expression]
Restrict the active observations to those for which expression is true.

HIGHLIGHT[expression]
Highlight points for which expression is true. This option only works for modes in which points are actually plotted (i.e., it does not work with the connect option of the PARM subop). The point character used for highlighted points can be changed by using the point_style option of the PARM subop.

LAB[string]
Generate a label for the graph.

OBS[observation list]
Restrict the active observations to those observations listed.

PARM[string]
Specify optional parameters to customize the display.

PRINT
If present, the output is sent to the printer rather than to the screen. When this option is used, TERM must also be present unless this has been set as an environment variable on your system.

SIZE[llx lly urx ury]
Change the size of the plot by specifying the coordinates of the lower left and upper right corners of the plot. Each of the coordinates should be in the range 0 to 1. See SIZE subop.

TERM[terminal]
Use the driver for terminal.

TIME
Display the time required to execute the command.

Example

SST1> LOAD FILE[bkw]
SST2> SCAT VAR[sr pop*]


SELECT -- estimate models with correction for selection bias

Synopsis:
SELECT MODEL[dep variable = ind variable list] options

This command implements the procedures described in J.A Dubin and D. Rivers, "Selection Bias in Linear Regression, Probit and Logit Models", Sociological Methods and Research (1989). A two equation model is estimated by Full Information Maximum Liklihood. The first equation (the selection equation) specifies which values of the dependent variable in the second equation are to be treated as uncensored. The second equation (the outcome equation) is estimated after correcting for selectivity bias.

Required subops

MODEL[dependent variable = independent variable list]
Specify the selection equation and the outcome equation.

Optional subops

COEF[matrix name]
Save the final values of the parameters in matrix name.

CONVG[number]
The maximum value of the gradient vector in the norm of the estimated covariance matrix before the search is to be terminated. The default value is 0.001.

COVMAT[matrix name]
Save the covariance matrix in the specified matrix. This matrix is not usually printed or saved. See the PRT subop for information on printing the covariance matrix.

IF[expression]
Restrict the active observations to those for which expression is true.

MAXIT[integer]
Specify the maximum number of iterations to run before terminating the search. By default, the maximum number of iterations is 15.

METH[]
Specify the optimization method to be used

OBS[observation list]
Restrict the active observations to those listed in observation list.

PRT[n]
Controls the amount of information that is printed at each iteration. The default level of printing is 1 and includes the value of the likelihood function at each iteration, the stepsize, and the convergence criterion. To have SST print out the covariance matrix after the last iteration, set n to 2. If n is 3, SST will also print the parameter values at each iteration. To aid in debugging, SST will print the numerical derivatives on the first iteration if n is increased to 5.

START[starting values]
Specify the starting values for the parameters listed in the PARM subop. By default all parameters start with a value of zero.

STEP[number]
Specify a fixed stepsize to be used at each iteration in the search. By default SST tries to pick an optimum stepsize at each iteration.

TIME
Display a summary of the time used by this command.


SET -- perform arithmetic transformations of data

Synopsis:
SET expression; options

Most of the data that SST deals with is stored as observation vectors, also called variables. The data in an variable is a list of values, some of which may be marked as missing, meaning they are not valid and have no value. The SET command allows us to modify the values of existing variables or to create new variables using arithmetic operations.

The operations supported for variables include all operations available on scalars. A variable expression is evaluated by observation. For example, if we have an observation vector y, the command

SET x = y + 1

will add 1 to each observation of y and assign the result to x. The value of y remains unchanged.

Use of SET alone puts you in interactive mode. A SET command without a left-hand-side sends the result to standard SST output.

If any of the operands of an operation have missing observations, those observations will be marked as missing in the result. As an example consider the following data set:

Obsno            sr             pop15
   1:      11.43000          29.35000
   2:      12.07000          23.32000
   3:            MD          23.80000
   4:       5.75000                MD
   5:      12.88000          42.19000
   6:       8.79000          31.72000
   7:            MD                MD
   8:      11.90000          44.75000
   9:       4.98000          46.64000
  10:      10.78000          47.64000

If we issued the command

SET x = sr + pop15

we would get as a result:

Obsno            sr             pop15                 x
   1:      11.43000          29.35000          40.78000
   2:      12.07000          23.32000          35.39000
   3:            MD          23.80000                MD
   4:       5.75000                MD                MD
   5:      12.88000          42.19000          55.07000
   6:       8.79000          31.72000          40.51000
   7:            MD                MD                MD
   8:      11.90000          44.75000          56.65000
   9:       4.98000          46.64000          51.62000
  10:      10.78000          47.64000          58.42000

Relational operators also operate by observation. Just as with arithmetic operators, if one or both of the operands is missing, the result is marked as missing.

Conditional expressions allow variables to be used as the controlling, or logical, expression. The value of the result is the value of the true-expr for all valid, non-zero values of the logical-expr and the value of the false-expr for all other valid logical-expr observations. Observations which are missing in the logical-expr are marked as missing in the result. This can be summarized by the following pseudo code fragment, executed for every observation:

IF (logical-expr is valid) THEN
    IF (logical-expr is non-zero) THEN
        result = true-expr
    ELSE
        result = false-expr
ELSE
    result = "missing"

(The pseudo code commands listed are not the SST comands of the same name). Note that if true-expr (or false-expr) is missing for one of the observations in which it is used, the result for that observation will be marked as missing. Using the above data and the following command:

SET x = sr > 10 ? 0 : pop15
SET y = miss(sr) ? 0 : sr

would give the following result:

Obsno            sr             pop15                 x                y
   1:      11.43000          29.35000           0.00000         11.43000
   2:      12.07000          23.32000           0.00000         12.07000
   3:            MD          23.80000                MD          0.00000
   4:       5.75000                MD                MD          5.75000
   5:      12.88000          42.19000           0.00000         12.88000
   6:       8.79000          31.72000          31.72000          8.79000
   7:            MD                MD                MD          0.00000
   8:      11.90000          44.75000           0.00000         11.90000
   9:       4.98000          46.64000          46.64000          4.98000
  10:      10.78000          47.64000           0.00000         10.78000

Optional subops

Subops for the SET command are included by separating the optional subops from the expression with a semicolon.

IF[if-expression]
The expression will only evaluated for observations in which if-expression is true.

OBS[observation list]
The expression will only be evaluate for observations listed in observation list.

RP
When overwriting existing variables, SST leaves observations which are masked out by the IF and OBS subops, and the RANGE command, unchanged. If the RP subop is specified those observations will be marked as missing.

TIME
Display a summary of the time used to evaluate the expression.


SOLV -- solve for zeros of a function

Synopsis:
SOLV EXPR[expression] DOMAIN[var{=domain2] options

The SOLV command searches for a zero of a real function given in the EXPR subop.

Required subops

EXPR[expression]
The listed expression is considered as a function of the parameters given in the PARM or DOMAIN subops. The zeros of this function are searched for in the specified DOMAIN.

DOMAIN[var{= min TO max, ...2]
Set the domain of independent variables to lie between min and max. More general ranges can be specified. The PARM subop may also be used to specify the independent variables in the expression.

Optional subops

COEF[matrix name]
Save the values of the variables zeroing the function in the indicated matrix.

CONVG[number]
The maximum value of the square of the function before the search is terminated. The default value is 0.001.

GRAD[expression]
A vector of expressions, separated by commas, giving the gradient of the function with respect to the parameters. If this subop is absent, Brent's algorithm is used to find a zero. If this subop is present, then a Newton- Raphson algorithm is used.

IF[expression]
Restrict the active observations to those for which expression is true.

MAXIT[integer]
Specify the maximum number of iterations to run before terminating the search. By default, the maximum number of iterations is 15.

METH[]

OBS[observation list]
Restrict the active observations to those listed in observation list.

PARM[variable list]
Specify the variables which are to be considered as parameters to the expressions. The domain of the expression is unlimited.

PRT[n]

START[starting values]
Specify the starting values for the parameters listed in the PARM subop. By default all parameters start with a value of zero.

STEP[number]
Specify a fixed stepsize to be used in the search (at each iteration). By default SST tries to pick an optimum stepsize at each iteration.

TIME
Display a summary of the time used by this command.

Example

No example is currently available.


SORT -- sort the data in a variable

Synopsis:
SORT VAR[variable list] BY[variable list] options

Observations on the variables specified in the VAR subop are sorted according to values in ascending order of the variables specified in the BY subop. The procedure makes a key by sorting the values of the first variable in the BY subop. Ties in the first variable are then broken by sorting by values of the second variable, again in ascending order. Observations tied on both the first and second variables are then sorted by the third variable in the BY subop and so on for the remaining variables in the BY subop. If the VAR subop is omitted, all variables currently in memory, including variables entered using the LOAD command, will be sorted. Missing values are assumed to take values larger than any non-missing values and hence end up at the bottom of the observation list after sorting.

Required subops

VAR[variable list]
Specify the variables to be sorted. If this option is omitted, all variables currently in memory are sorted.

BY[variable list]
The variables listed in the VAR subop will be sorted according to the values of the observations of the first variable in the BY subop's variable list. Ties are broken by looking at the values of the next variable, and so on if further ties occur. If the BY subop is not present, the variables listed in the VAR subop are used for sorting.

Optional subops

INDEX[variable]
Store the permutation index generated by the sorting operation.

PERMUTE
Superceded by MATCH, no documentation available.

TIME
Display a summary of the time used by this command.

TO[variable list]
Change the names of the sorted variables. The number of variables listed in the TO subop must agree with the number listed in the VAR subop.

Example

To sort all observations of all variables according to values of the variable x:

sort by[x]

This will first cause the observations of x to be sorted into ascending numerical order, and then will sort the observations of all other variables according to the values of x.

To sort only variables y and z according to values of x:

sort var[y z] by[x]

Note that this last command will not rearrange values of the variable x since x is not included in the VAR subop.


SPOOL -- save commands and/or output for later display.

Synopsis:
SPOOL FILE[filename] options SPOOL OFF options SPOOL

Output consisting of either user-issued commands, SST output, or both is saved in the file specified in the FILE subop. Commands and output continue to be displayed on the screen as well. SPOOL creates files that do not already exist. For existing files SPOOL will overwrite its output. If neither the CMD or OUT subop is specified, both commands and output are spooled to the file. If CMD alone is specified, then only commands are saved, and the resulting file can be rerun using the RUN command. If OUT alone is specified, only output will be saved. To turn spooling off, include the OFF subop. If no file is specified, all files open for spooling will then be closed. The QUIT command also closes all spooling files. Entering SPOOL without other subops shows the current spooling status.

Required subops

FILE[filename]
Specifies the file in which to save output.

Optional subops

CMD
Saves commands in the spool file.

OUT
Saves output from commands in the spool file.

OFF
Close spool file.

APPEND
Append the output to an existing file.

VERBOSE[OFF|ON]
Causes the command to be echoed to the spool file just before the command is executed but after all variables and macros have been expanded. Normally commands are executed as they are typed in or read from a batch file. See SST Command Preprocessor.

Example

SST1> SPOOL FILE[reg.log]               # Save commands and output
SST2> LOAD FILE[bkw]
SST3> REG DEP[sr] IND[pop* dpi deldpi]


********* ORDINARY LEAST SQUARES ESTIMATION *********

Dependent Variable:        sr

Independent        Estimated             Standard                 t-
 Variable         Coefficient             Error               Statistic

    pop15           9.17220e-002          2.93033e-002          3.13010
    pop75           1.71408               0.72776               2.35526
      dpi           2.62804e-004          1.04941e-003          0.25043
   deldpi           0.55315               0.22022               2.51177


Number of Observations                  50
R-squared                                0.11667
Corrected R-squared                      5.90571e-002
Sum of Squared Residuals                 8.68872e+002
Standard Error of the Regression         4.34609
Durbin-Watson Statistic                  2.10304
Mean of Dependent Variable               9.67100

SST4> SPOOL OFF                 # Stop saving commands and output
SST5> LIST                      # This will not be saved

---- Variables ----
deldpi      50  Wed Jul 26 20:32:06 1989 real disposable income growth rate
dpi         50  Wed Jul 26 20:32:06 1989 real disposable income per capita
pop15       50  Wed Jul 26 20:32:06 1989 percentage population under 15
pop75       50  Wed Jul 26 20:32:06 1989 percentage population over 75
sr          50  Wed Jul 26 20:32:06 1989 average personal savings rate

SST6>


SYS -- invoke other programs without leaving SST

Synopsis:
SYS command

This command allows you to leave SST temporarily and do other tasks and then return to SST with all your data preserved as you left it. Any DOS command can be executed with SYS.

In UNIX, SYS shells you out to the SHELL environment specified by your shell environmental variable. Under DOS, SYS frees all memory using a memory swap. The CD command under SYS effects only the daughter shell, and is cancelled when you return to SST. Use CD directly when you are in SST in order to change disks or directories.

Example

To type a file without leaving SST (under the MSDOS operating system):

sys type filename


SYSREG -- estimate systems of regression equations

Synopsis:
SYSREG MODEL[dep variable = ind variable list] options

SYSREG estimates systems of regression equations using either the seemingly unrelated regression method or three stage least squares. The system of equations is specified using the MODEL subop. Each equation is entered by first specifying the dependent variable followed by an equals = sign and the list of independent variables appearing in that equation. Different equations are separated by spaces or commas. If three stage least squares (3SLS) estimation is desired, a list of instrumental variables should be specified using the IV subop. Otherwise, seemingly unrelated regression estimation (SURE) is performed. The estimation range is restricted by the inclusion of the IF or OBS subops. Residuals and predicted values can be saved by specifying the RSD and PRED subops, respectively. In both cases, the number of variables should be the same as the number of equations specified in the MODEL subop. The SIGMA subop may be used to save the estimated disturbance covariance matrix for the system as an SST matrix.

Required subops

MODEL[dependent variable = independent variable list]
Specify the system of equations to be regressed.

Optional subops

COEF[matrix name]
Save the final values of the parameters in matrix name.

COVMAT[matrix name]
Save the covariance matrix in the specified matrix. This matrix is not usually printed or saved. See the PRT subop for information on printing the covariance matrix.

IF[expression]
Restrict the active observations to those for which expression is true.

IV[variable list]
Causes a three stage least squares to be performed with the specified instrumental variables.

OBS[observation list]
Restrict the active observations to those listed in observation list.

PRED[variable-list]
Save the predicted values from each equation. The number of variable names specified must equal the number of equations specified in the MODEL subop.

RSD[variable list]
Save the residual values in the indicated variable. One variable should be given for each equation in the MODEL subop.

SIGMA[matrix name]
Save the estimated disturbance covariance matrix for the system.

TIME
Display a summary of the time used by this command.


TABLE -- n-way contingency table

Synopsis:
TABLE VAR[variable list] options

The TABLE command crosstabulates the first variable in the VAR subop by the second variable in the VAR subop for combinations of values of the remaining variables in the VAR subop. The first variable is the row variable and the second variable is the column variable. One table is produced for each combination of values of the remaining variables in the VAR subop. By default the TABLE command produces percentages by column for each subtable. The chi-square statistics and measures of association for each subtable are displayed if the MEASURES subop is present.

Required subops

VAR[variable list]
The row variable is given by the first variable name in variable list; the second variable name determines the column variable. If more than two variables are present then a separate table will be calculated for each combination of values in the remaining variables.

Optional subops

ROW
Show percentages of the number of each occurance by row instead of by column, which is the default setting.

MEASURES
Show the chi-square statistics and measures of association for each subtable.

IF[expression]
Restrict the active observations to those for which expression is true.

OBS[observation list]
Restrict the active observations to those listed in observation list.

TIME
Display a summary of the time used by this command.

Example

To obtain a crosstabulation of the variable x by y, with y as the column variable, use the command:

table var[x y]

To produce a crosstabulation of x by y for each combination of the values of the variables a and b and display the measures of association for each subtable, use:

table var[x y a b] measures


TOBIT -- estimate Tobit models

Synopsis:
TOBIT DEP[ variable name] IND[variable list] options

The TOBIT command estimates Tobit models by the method of maximum likelihood. The dependent variable is specified in the DEP subop. Values of the dependent variable less than zero are assumed to be censored with probability 1-PHI(beta' x_i), where PHI denotes the cumulative normal distribution function. Independent variables are specified in the IND subop, as in the REG command.

Required subops

DEP[variable name]
The dependent variable to be used in the Tobit model.

IND[variable list]
A list of independent variables.

Optional subops

COEF[matrix name]
Save the coefficient estimates in the indicated matrix. If more than one variable is listed in the DEP subop, a separate matrix should be given for each.

CONVG[number]
The maximum value of the gradient vector in the norm of the estimated covariance matrix before the search is to be terminated. The default value is 0.001.

COVMAT[matrix name]
Save the covariance matrix in the specified matrix. This matrix is not usually printed or saved. See the PRT subop for information on printing the covariance matrix.

IF[expression]
Restrict the active observations to those for which expression is true.

MAXIT[integer]
Specify the maximum number of iterations to run before terminating the search. By default, the maximum number of iterations is 15.

METH[]
Specify the optimization method to be used.

OBS[observation list]
Restrict the active observations to those listed in observation list.

PRED[variable list]
Save the values of beta^T x_i for each observation in the specified variable. A separate variable name should be included for each variable listed in the DEP subop.

PROB[variable name]
Save the censoring probabilities in the variable name given in the PROB subop.

PRT[n]
Controls the amount of information that is printed at each iteration. The default level of printing is 1 and includes the value of the likelihood function at each iteration, the stepsize, and the convergence criterion. To have SST print out the covariance matrix after the last iteration, set n to 2. If n is 3, SST will also print the parameter values at each iteration.

ROBUST
Compute robust standard errors.

START[starting values]
Specify the starting values for the parameters listed in the PARM subop. By default all parameters start with a value of zero.

STEP[number]
Specify a fixed stepsize to be used at each iteration in the search. By default SST tries to pick an optimum stepsize at each iteration.

TIME
Display a summary of the time used by this command.

Example

If values of zero for the variable y indicate censored observations, a censored regression with independent variable x and a constant one can be estimated using:

tobit dep[y] ind[one x]


WHILE -- execute commands in a loop

Synopsis:
WHILE (test-expr) { block of SST commands 2

The WHILE loop allows you to run a set of SST commands while some condition holds. It is modeled after the while loops of the C programming language. The body for the WHILE loop can either be a single command on the same line as the WHILE keyword or a set of commands enclosed in braces. Execution proceeds as follows: SST evaluates the logical expression; if it is true, it performs the specified set of commands; otherwise it proceeds to subsequent commands outside the body of the loop. After the first pass through the set of commands, it re-evaluates the logical expression. Again, if it is true it performs the commands. If the expression is false, it proceeds to the commands following the loop.

Example

SST1> CALC counter = 1
SST2> WHILE (counter <= 4) {
1> CALC counter                     # Print out the value of 'counter'
1> CALC counter = counter + 1
1> REM Other commands might be added here
1> }
      1.00000
      2.00000
      3.00000
      4.00000
SST3>


WRITE -- write variables to a file

Synopsis:
WRITE VAR[variable list] FILE[filename] options

The variables specified in the VAR subop are written to the file specified in the FILE subop in ASCII format. The filename may be preceded by drive or path descriptors. If the file specified does not exist, it will be created. If it already exists, it will be overwritten.

The equivalent command for storing data in the SST system file format is SAVE.

Required subops

FILE[filename]
Specifies the file to which the variables are written. On DOS machines, the filename CON: writes to the console. On UNIX machines, the filename /dev/tty writes to the console.

VAR[variable list]
Specifies which variables are to be written to the file.

Optional subops

BYVAR
The default format is for the data to be organized by observation. If the BYVAR subop is included, all observations will be output for the first variable listed in the VAR subop, followed by all observations on the second variable listed in the VAR subop, and so forth.

FMT[format description]/
The FMT subop allows the user to format output with a FORTRAN format description, which is described here.

IF[expression]
Write only those observations for which expression is true.

OBS[observation list]
Writes only those observations given in observation list.

TIME
Display a summary of the time used by this command.

Example

SST1> LOAD FILE[bkw]
SST2> WRITE FILE[mybkw.dat] VAR[sr pop15 pop75 dpi deldpi]
# Generate file 'mybkw.dat' from the bkw saveset
SST3> READ FILE[mybkw.dat] TO[a b c d e]
# Read back the file we just created
SST4> LIST          # Look at the variables in memory

---- Variables ----
a           50  Sat Sep 02 17:39:48 1989
b           50  Sat Sep 02 17:39:48 1989
c           50  Sat Sep 02 17:39:48 1989
d           50  Sat Sep 02 17:39:48 1989
deldpi      50  Wed Jul 26 20:32:06 1989 real disposable income growth rate
dpi         50  Wed Jul 26 20:32:06 1989 real disposable income per capita
e           50  Sat Sep 02 17:39:48 1989
pop15       50  Wed Jul 26 20:32:06 1989 percentage population under 15
pop75       50  Wed Jul 26 20:32:06 1989 percentage population over 75
sr          50  Wed Jul 26 20:32:06 1989 average personal savings rate

SST5>


Command Back Back SST