Formfeed (ASCII 12).
@item \n
-Newline (ASCII 10)
+New-line (ASCII 10)
@item \r
Carriage return (ASCII 13).
@item line-ends=@var{line-end-type}
One of @code{cr}, @code{lf}, or @code{crlf}. This controls what is used
-for newline in the output file. Default: @code{cr}.
+for new-line in the output file. Default: @code{cr}.
@item optimize-line-size=@var{level}
@code{paginate}, described below, for a related setting. Default:
@code{"\f"}.
-@item newline-string=@var{newline-value}
+@item newline-string=@var{new-line-value}
-The string written to the output to cause a newline (carriage return
+The string written to the output to cause a new-line (carriage return
plus linefeed). The default, which can be specified explicitly with
-@code{newline-string=default}, is to use the system-dependent newline
+@code{newline-string=default}, is to use the system-dependent new-line
sequence by opening the output file in text mode. This is usually the
right choice.
current run. The configuration options are:
@table @code
+@item -a @{compatible|enhanced@}
+@itemx --algorithm=@{compatible|enhanced@}
+
+If you chose @code{compatible}, then PSPP will use the same algorithms
+as used by some proprietary statistical analysis packages.
+This is not recommended, as these algorithms are inferior and in some cases
+compeletely broken.
+The default setting is @code{enhanced}.
+Certain commands have subcommands which allow you to override this setting on
+a per command basis.
+
@item -B @var{dir}
@itemx --config-dir=@var{dir}
Lists the available device driver classes, then terminates.
+@item -x @{compatible|enhanced@}
+@itemx --syntax=@{compatible|enhanced@}
+
+If you chose @code{compatible}, then PSPP will only accept command syntax that
+is compatible with the proprietary program SPSS.
+If you choose @code{enhanced} then additional syntax will be available.
+The default is @code{enhanced}.
+
+
@item -V
@item --version
full-fledged expressions in themselves.
@menu
-* Booleans:: Boolean values.
+* Boolean Values:: Boolean values.
* Missing Values in Expressions:: Using missing values in expressions.
-* Grouping Operators:: ( )
-* Arithmetic Operators:: + - * / **
-* Logical Operators:: AND NOT OR
-* Relational Operators:: EQ GE GT LE LT NE
-* Functions:: More-sophisticated operators.
-* Order of Operations:: Operator precedence.
+* Grouping Operators:: parentheses
+* Arithmetic Operators:: add sub mul div pow
+* Logical Operators:: AND NOT OR
+* Relational Operators:: EQ GE GT LE LT NE
+* Functions:: More-sophisticated operators.
+* Order of Operations:: Operator precedence.
@end menu
-@node Booleans, Missing Values in Expressions, Expressions, Expressions
-@section Boolean values
+@node Boolean Values, Missing Values in Expressions, Expressions, Expressions
+@section Boolean Values
@cindex Boolean
@cindex values, Boolean
-There is a third type for arguments and results, the @dfn{Boolean} type,
-which is used to represent true/false conditions. Booleans have only
-three possible values: 0 (false), 1 (true), and system-missing.
-System-missing is neither true nor false.
-
-@itemize @bullet
-@item
-A numeric expression that has value 0, 1, or system-missing may be used
-in place of a Boolean. Thus, the expression @code{0 AND 1} is valid
-(although it is always false).
-
-@item
-A numeric expression with any other value will cause an error if it is
-used as a Boolean. So, @code{2 OR 3} is invalid.
+Some PSPP operators and expressions work with Boolean values, which
+represent true/false conditions. Booleans have only three possible
+values: 0 (false), 1 (true), and system-missing (unknown).
+System-missing is neither true nor false and indicates that the true
+value is unknown.
-@item
-A Boolean expression may not be used in place of a numeric expression.
-Thus, @code{(1>2) + (3<4)} is invalid.
+Boolean-typed operands or function arguments must take on one of these
+three values. Other values are considered false, but cause an error
+when the expression is evaluated.
-@item
Strings and Booleans are not compatible, and neither may be used in
place of the other.
-@end itemize
-@node Missing Values in Expressions, Grouping Operators, Booleans, Expressions
+@node Missing Values in Expressions, Grouping Operators, Boolean Values, Expressions
@section Missing Values in Expressions
String missing values are not treated specially in expressions. Most
descriptions.
User-missing values for numeric variables are always transformed into
-the system-missing value, except inside the arguments to the
-@code{VALUE}, @code{SYSMIS}, and @code{MISSING} functions.
+the system-missing value, except inside the arguments to the
+@code{VALUE} and @code{SYSMIS} functions.
The missing-value functions can be used to precisely control how missing
values are treated in expressions. @xref{Missing Value Functions}, for
@cindex logical intersection
@item @var{a} AND @var{b}
@itemx @var{a} & @var{b}
-True if both @var{a} and @var{b} are true. However, if one argument is
-false and the other is missing, the result is false, not missing. If
+True if both @var{a} and @var{b} are true, false otherwise. If one
+argument is false, the result is false even if the other is missing. If
both arguments are missing, the result is missing.
@cindex @code{OR}
@item @var{a} OR @var{b}
@itemx @var{a} | @var{b}
True if at least one of @var{a} and @var{b} is true. If one argument is
-true and the other is missing, the result is true, not missing. If both
+true, the result is true even if the other argument is missing. If both
arguments are missing, the result is missing.
@cindex @code{NOT}
@cindex logical inversion
@item NOT @var{a}
@itemx ~ @var{a}
-True if @var{a} is false.
+True if @var{a} is false. If the argument is missing, then the result
+is missing.
@end table
@node Relational Operators, Functions, Logical Operators, Expressions
The relational operators take numeric or string arguments and produce Boolean
results.
-Note that, with numeric arguments, PSPP does not make exact
-relational tests. Instead, two numbers are considered to be equal even
-if they differ by a small amount. This amount, @dfn{epsilon}, is
-dependent on the PSPP configuration and determined at compile
-time. (The default value is 0.000000001, or
-@ifinfo
-@code{10**(-9)}.)
-@end ifinfo
-@tex
-$10 ^{-9}$.)
-@end tex
-Use of epsilon allows for round-off errors. Use of epsilon is also
-idiotic, but the author is not a numeric analyst.
-
Strings cannot be compared to numbers. When strings of different
lengths are compared, the shorter string is right-padded with spaces
to match the length of the longer string.
@cindex arccosine
@cindex inverse cosine
-@deftypefn {Function} {} ACOS (@var{number})
-@deftypefnx {Function} {} ARCOS (@var{number})
+@deftypefn {Function} {} ARCOS (@var{number})
Takes the arccosine, in radians, of @var{number}. Results in
-system-missing if @var{number} is not between -1 and 1. Portability:
-none.
+system-missing if @var{number} is not between -1 and 1.
@end deftypefn
@cindex arcsine
Takes the arctangent, in radians, of @var{number}.
@end deftypefn
-@cindex arcsine
-@cindex inverse sine
-@deftypefn {Function} {} ASIN (@var{number})
-Takes the arcsine, in radians, of @var{number}. Results in
-system-missing if @var{number} is not between -1 and 1 inclusive.
-Portability: none.
-@end deftypefn
-
-@cindex arctangent
-@cindex inverse tangent
-@deftypefn {Function} {} ATAN (@var{number})
-Takes the arctangent, in radians, of @var{number}.
-@end deftypefn
-
-@quotation
-@strong{Please note:} Use of the AR* group of inverse trigonometric
-functions is recommended over the A* group because they are more
-portable.
-@end quotation
-
@cindex cosine
@deftypefn {Function} {} COS (@var{angle})
Takes the cosine of @var{angle} which should be in radians.
@cindex values, missing
@cindex functions, missing-value
-Missing-value functions take various types as arguments, returning
-various types of results.
+Missing-value functions take various numeric arguments and yield
+various types of results. Note that the normal rules of evaluation
+apply within expression arguments to these functions. In particular,
+user-missing values for numeric variables are converted to
+system-missing values.
-@deftypefn {Function} {} MISSING (@var{variable or expression})
-@var{num} may be a single variable name or an expression. If it is a
-variable name, results in 1 if the variable has a user-missing or
-system-missing value for the current case, 0 otherwise. If it is an
-expression, results in 1 if the expression has the system-missing value,
-0 otherwise.
-
-@quotation
-@strong{Please note:} If the argument is a string expression other than
-a variable name, MISSING is guaranteed to return 0, because strings do
-not have a system-missing value. Also, when using a numeric expression
-argument, remember that user-missing values are converted to the
-system-missing value in most contexts. Thus, the expressions
-@code{MISSING(VAR1 @var{op} VAR2)} and @code{MISSING(VAR1) OR
-MISSING(VAR2)} are often equivalent, depending on the specific operator
-@var{op} used.
-@end quotation
+@deftypefn {Function} {} MISSING (@var{expr})
+Returns 1 if @var{expr} has the system-missing value, 0 otherwise.
@end deftypefn
@deftypefn {Function} {} NMISS (@var{expr} [, @var{expr}]@dots{})
Each argument must be a numeric expression. Returns the number of
-user- or system-missing values in the list. As a special extension,
+system-missing values in the list. As a special extension,
the syntax @code{@var{var1} TO @var{var2}} may be used to refer to a
range of variables; see @ref{Sets of Variables}, for more details.
@end deftypefn
@deftypefn {Function} {} NVALID (@var{expr} [, @var{expr}]@dots{})
Each argument must be a numeric expression. Returns the number of
-values in the list that are not user- or system-missing. As a special extension,
+values in the list that are not system-missing. As a special extension,
the syntax @code{@var{var1} TO @var{var2}} may be used to refer to a
range of variables; see @ref{Sets of Variables}, for more details.
@end deftypefn
-@deftypefn {Function} {} SYSMIS (@var{variable or expression})
-When given the name of a numeric variable, returns 1 if the value of
-that variable is system-missing. Otherwise, if the value is not
-missing or if it is user-missing, returns 0. If given the name of a
-string variable, always returns 1. If given an expression other than
-a single variable name, results in 1 if the value is system- or
-user-missing, 0 otherwise.
+@deftypefn {Function} {} SYSMIS (@var{expr})
+When @var{expr} is simply the name of a numeric variable, returns 1 if
+the variable has the system-missing value, 0 if it is user-missing or
+not missing. If given @var{expr} takes another form, results in 1 if
+the value is system-missing, 0 otherwise.
@end deftypefn
@deftypefn {Function} {} VALUE (@var{variable})
Prevents the user-missing values of @var{variable} from being
-transformed into system-missing values: If @var{variable} is not
-system- or user-missing, results in the value of @var{variable}. If
-@var{variable} is user-missing, results in the value of @var{variable}
-anyway. If @var{variable} is system-missing, results in system-missing.
+transformed into system-missing values, and always results in the
+actual value of @var{variable}, whether it is user-missing,
+system-missing or not missing at all.
@end deftypefn
@node Pseudo-Random Numbers, Set Membership, Missing Value Functions, Functions
@end deftypefn
@cindex variance
-@deftypefn {Function} {} VAR (@var{number}, @var{number}[, @dots{}])
-Results in the variance of the values of @var{number}. This function
-requires at least two valid arguments to give a non-missing result.
-@end deftypefn
-
@deftypefn {Function} {} VARIANCE (@var{number}, @var{number}[, @dots{}])
Results in the variance of the values of @var{number}. This function
requires at least two valid arguments to give a non-missing result.
-(Use VAR in preference to VARIANCE for reasons of portability.)
@end deftypefn
@node String Functions, Time & Date, Statistical Functions, Functions
@cindex numbers, converting from strings
@cindex strings, converting to numbers
-@deftypefn {Function} {} NUMBER (@var{string})
-Returns the number produced when @var{string} is interpreted according
-to format F@var{x}.0, where @var{x} is the number of characters in
-@var{string}. If @var{string} does not form a proper number,
-system-missing is returned without an error message. Portability: none.
-@end deftypefn
-
@deftypefn {Function} {} NUMBER (@var{string}, @var{format})
Returns the number produced when @var{string} is interpreted according
-to format specifier @var{format}. Only the number of characters in
-@var{string} specified by @var{format} are examined. For example,
-@code{NUMBER("123", F3.0)} and @code{NUMBER("1234", F3.0)} both have
-value 123. If @var{string} does not form a proper number,
-system-missing is returned without an error message.
+to format specifier @var{format}. If the format width @var{w} is less
+than the length of @var{string}, then only the first @var{w}
+characters in @var{string} are used, e.g.@: @code{NUMBER("123", F3.0)}
+and @code{NUMBER("1234", F3.0)} both have value 123. If @var{w} is
+greater than @var{string}'s length, then it is treated as if it were
+right-padded with spaces. If @var{string} is not in the correct
+format for @var{format}, system-missing is returned.
@end deftypefn
@cindex strings, searching backwards
@cindex cross-case function
@cindex function, cross-case
@deftypefn {Function} {} LAG (@var{variable})
+@anchor{LAG}
@var{variable} must be a numeric or string variable name. @code{LAG}
results in the value of that variable for the case before the current
one. In case-selection procedures, @code{LAG} results in the value of
@display
DATA LIST FREE
+ [(@{TAB,'c'@}, @dots{})]
[@{NOTABLE,TABLE@}]
FILE='filename'
END=end_var
var_list *
@end display
-In free format, the input data is structured as a series of comma- or
-whitespace-delimited fields (end of line is one form of whitespace; it
-is not treated specially). Field contents may be surrounded by matched
-pairs of apostrophes (@samp{'}) or quotes (@samp{"}), or they may be
-unenclosed. For any type of field leading white space (up to the
-apostrophe or quote, if any) is not included in the field.
-
-Multiple consecutive delimiters are equivalent to a single delimiter.
-To specify an empty field, write an empty set of single or double
-quotes; for instance, @samp{""}.
+In free format, the input data is, by default, structured as a series
+of fields separated by spaces, tabs, commas, or line breaks. Each
+field's content may be unquoted, or it may be quoted with a pairs of
+apostrophes (@samp{'}) or double quotes (@samp{"}). Unquoted white
+space separates fields but is not part of any field. Any mix of
+spaces, tabs, and line breaks is equivalent to a single space for the
+purpose of separating fields, but consecutive commas will skip a
+field.
+
+Alternatively, delimiters can be specified explicitly, as a
+parenthesized, comma-separated list of single-character strings
+immediately following FREE. The word TAB may also be used to specify
+a tab character as a delimiter. When delimiters are specified
+explicitly, only the given characters, plus line breaks, separate
+fields. Furthermore, leading spaces at the beginnings of fields are
+not trimmed, consecutive delimiters define empty fields, and no form
+of quoting is allowed.
The NOTABLE and TABLE subcommands are as in @cmd{DATA LIST FIXED} above.
NOTABLE is the default.
@display
DATA LIST LIST
+ [(@{TAB,'c'@}, @dots{})]
[@{NOTABLE,TABLE@}]
FILE='filename'
END=end_var
@display
FILE HANDLE handle_name
/NAME='filename'
- /RECFORM=@{VARIABLE,FIXED,SPANNED@}
+ /MODE=@{CHARACTER,IMAGE@}
/LRECL=rec_len
- /MODE=@{CHARACTER,IMAGE,BINARY,MULTIPUNCH,360@}
+ /TABWIDTH=tab_width
@end display
-Use @cmd{FILE HANDLE} to define the attributes of a file that does
-not use conventional variable-length records terminated by newline
-characters.
+Use @cmd{FILE HANDLE} to associate a file handle name with a file and
+its attributes, so that later commands can refer to the file by its
+handle name. Because names of text files can be specified directly on
+commands that access files, @cmd{FILE HANDLE} is only needed when a
+file is not an ordinary file containing lines of text. However,
+@cmd{FILE HANDLE} may be used even for text files, and it may be
+easier to specify a file's name once and later refer to it by an
+abstract handle.
Specify the file handle name as an identifier. Any given identifier may
only appear once in a PSPP run. File handles may not be reassigned to a
The NAME subcommand specifies the name of the file associated with the
handle. It is the only required subcommand.
-The RECFORM subcommand specifies how the file is laid out. VARIABLE
-specifies variable-length lines terminated with newlines, and it is the
-default. FIXED specifies fixed-length records. SPANNED is not
-supported.
+MODE specifies a file mode. In CHARACTER mode, the default, the data
+file is opened in ANSI C text mode, so that local end of line
+conventions are followed, and each text line is read as one record.
+In CHARACTER mode, most input programs will expand tabs to spaces
+(@cmd{DATA LIST FREE} with explicitly specified delimiters is an
+exception). By default, each tab is 4 characters wide, but an
+alternate width may be specified on TABWIDTH. A tab width of 0
+suppresses tab expansion entirely.
-LRECL specifies the length of fixed-length records. It is required if
-@code{/RECFORM FIXED} is specified.
-
-MODE specifies a file mode. CHARACTER, the default, causes the data
-file to be opened in ANSI C text mode. BINARY causes the data file to
-be opened in ANSI C binary mode. The other possibilities are not
-supported.
+By contrast, in BINARY mode, the data file is opened in ANSI C binary
+mode and records are a fixed length. In BINARY mode, LRECL specifies
+the record length in bytes, with a default of 1024. Tab characters
+are never expanded to spaces in binary mode.
@node INPUT PROGRAM, LIST, FILE HANDLE, Data Input and Output
@section INPUT PROGRAM
(@samp{=}) and the identifier variable name. The variable must already
have been declared with @cmd{NUMERIC} or another command.
+@cmd{REPEATING DATA} should be the last command given within an
+@cmd{INPUT PROGRAM}. It should not be enclosed within a @cmd{LOOP}
+structure (@pxref{LOOP}). Use @cmd{DATA LIST} before, not after,
+@cmd{REPEATING DATA}.
+
@node WRITE, , REPEATING DATA, Data Input and Output
@section WRITE
@vindex WRITE
variables are combined into a single record. Records with different
values are output in order. Thus, multiple sorted system files are
combined into a single sorted system file based on the value of the BY
-variables.
+variables. The results of the merge become the new active file.
The BY subcommand specifies a list of variables that are used to match
records from each of the system files. Variables specified must exist
IN, FIRST, LAST, and MAP are currently not used.
+@cmd{MATCH FILES} may not be specified following @cmd{TEMPORARY}
+(@pxref{TEMPORARY}) if the active file is used as an input source.
+
@node SAVE, SYSFILE INFO, MATCH FILES, System and Portable Files
@section SAVE
@vindex SAVE
If either DROP or KEEP is specified, the data is read; otherwise it is
not.
+@cmd{MODIFY VARS} may not be specified following @cmd{TEMPORARY}
+(@pxref{TEMPORARY}).
+
@node NUMERIC, PRINT FORMATS, MODIFY VARS, Variable Attributes
@section NUMERIC
@vindex NUMERIC
@cmd{RENAME VARIABLES} takes effect immediately. It does not cause the data
to be read.
+@cmd{RENAME VARIABLES} may not be specified following @cmd{TEMPORARY}
+(@pxref{TEMPORARY}).
+
@node VALUE LABELS, STRING, RENAME VARIABLES, Variable Attributes
@section VALUE LABELS
@vindex VALUE LABELS
variables called @dfn{break variables}. Several functions are available
for summarizing case contents.
-BREAK is the only required subcommand (in addition, at least one
-aggregation variable must be specified). Specify a list of variable
-names. The values of these variables are used to divide the active file
-into groups to be summarized.
+At least one break variable must be specified on BREAK, the only
+required subcommand. The values of these variables are used to divide
+the active file into groups to be summarized. In addition, at least
+one @var{dest_var} must be specified.
By default, the active file is sorted based on the break variables
-before aggregation takes place. If the active file is already sorted,
-specify PRESORTED to save time.
+before aggregation takes place. If the active file is already sorted
+or otherwise grouped in terms of the break variables, specify
+PRESORTED to save time.
The OUTFILE subcommand specifies a system file by file name string or
-file handle (@pxref{FILE HANDLE}). The aggregated cases are sent to
+file handle (@pxref{FILE HANDLE}). The aggregated cases are written to
this file. If OUTFILE is not specified, or if @samp{*} is specified,
then the aggregated cases replace the active file.
-Normally the aggregate file does not receive the documents from the
-active file, even if the aggregate file replaces the active file.
-Specify DOCUMENT to have the documents from the active file copied to
-the aggregate file.
-
-At least one aggregation variable must be specified. Specify a list of
-aggregation variables, an equals sign (@samp{=}), an aggregation
-function name (see the list below), and a list of source variables in
-parentheses. In addition, some aggregation functions expect additional
-arguments in the parentheses following the source variable names.
+Specify DOCUMENT to copy the documents from the active file into the
+aggregate file (@pxref{DOCUMENT}). Otherwise, the aggregate file will
+not contain any documents, even if the aggregate file replaces the
+active file.
-There must be exactly as many source variables as aggregation variables.
-Each aggregation variable receives the results of applying the specified
-aggregation function to the corresponding source variable. Most
-aggregation functions may be applied to numeric and short and long
-string variables. Others are restricted to numeric values; these are
-marked as such in this list below.
+One or more sets of aggregation variables must be specified. Each set
+comprises a list of aggregation variables, an equals sign (@samp{=}),
+the name of an aggregation function (see the list below), and a list
+of source variables in parentheses. Some aggregation functions expect
+additional arguments following the source variable names.
-Any number of sets of aggregation variables may be specified.
+Each set must have exactly as many source variables as aggregation
+variables. Each aggregation variable receives the results of applying
+the specified aggregation function to the corresponding source
+variable. Most aggregation functions may be applied to numeric and
+short and long string variables. Others, marked below, are restricted
+to numeric values.
The available aggregation functions are as follows:
Last value in this group.
@end table
-When string values are compared by aggregation functions, they are done
-in terms of internal character codes. On most modern computers, this is
-a form of ASCII.
+Aggregation functions compare string values in terms of internal
+character codes. On most modern computers, this is a form of ASCII.
-In addition, there is a parallel set of aggregation functions having the
-same names as those above, but with a dot after the last character (for
-instance, @samp{SUM.}). These functions are the same as the above,
-except that they cause user-missing values, which are normally excluded
-from calculations, to be included.
+The aggregation functions listed above exclude all user-missing values
+from calculations. To include user-missing values, insert a period
+(@samp{.}) between the function name and left parenthesis
+(e.g.@: @samp{SUM.}).
Normally, only a single case (for SD and SD., two cases) need be
-non-missing in
-each group in order for the aggregate variable to be non-missing. If
-/MISSING=COLUMNWISE is specified, the behavior reverses: that is, a
-single missing value is enough to make the aggregate variable become a
-missing value.
+non-missing in each group for the aggregate variable to be
+non-missing. Specifying /MISSING=COLUMNWISE inverts this behavior, so
+that the aggregate variable becomes missing if any aggregated value is
+missing.
-@cmd{AGGREGATE} ignores the current @cmd{SPLIT FILE} settings and causes
-them to be
-canceled (@pxref{SPLIT FILE}).
+@cmd{AGGREGATE} both ignores and cancels the current @cmd{SPLIT FILE}
+settings (@pxref{SPLIT FILE}).
@node AUTORECODE, COMPUTE, AGGREGATE, Data Manipulation
@section AUTORECODE
(@pxref{LEAVE}) resets the variable's left state. Therefore,
@code{LEAVE} should be specified following @cmd{COMPUTE}, not before.
-COMPUTE is a transformation. It does not cause the active file to be
+@cmd{COMPUTE} is a transformation. It does not cause the active file to be
read.
+When @cmd{COMPUTE} is specified following @cmd{TEMPORARY}
+(@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
+(@pxref{LAG}).
+
@node COUNT, FLIP, COMPUTE, Data Manipulation
@section COUNT
@vindex COUNT
@cmd{FLIP} transposes rows and columns in the active file. It
causes cases to be swapped with variables, and vice versa.
+All variables in the transposed active file are numeric. String
+variables take on the system-missing value in the transposed file.
+
No subcommands are required. The VARIABLES subcommand specifies
variables that will be transformed into cases. Variables not specified
are discarded. By default, all variables are selected for
variable can
be used to recreate the original variable names.
+FLIP honors N OF CASES. It ignores TEMPORARY, so that ``temporary''
+transformations become permanent.
+
@node IF, RECODE, FLIP, Data Manipulation
@section IF
@vindex IF
(@pxref{LEAVE}) resets the variable's left state. Therefore,
@code{LEAVE} should be specified following @cmd{IF}, not before.
+When @cmd{IF} is specified following @cmd{TEMPORARY}
+(@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
+(@pxref{LAG}).
+
@node RECODE, SORT CASES, IF, Data Manipulation
@section RECODE
@vindex RECODE
@cmd{SORT CASES} attempts to sort the entire active file in main memory.
If main memory is exhausted, it falls back to a merge sort algorithm that
-involves writing and reading numerous temporary files. Environment
-variables determine the temporary files' location. The first of
-SPSSTMPDIR, SPSSXTMPDIR, or TMPDIR that is set determines the location.
-Otherwise, if the compiler environment defined P_tmpdir, that is used.
-Otherwise, under Unix-like OSes /tmp is used; under MS-DOS, the first of
-TEMP, TMP, or root on the current drive is used; under other OSes, the
-current directory.
+involves writing and reading numerous temporary files.
+
+@cmd{SORT CASES} may not be specified following TEMPORARY.
@node Data Selection, Conditionals and Looping, Data Manipulation, Top
@chapter Selecting data for analysis
BY is optional but recommended. Cases which have a zero or system- or
user-missing value are excluded from analysis, but not deleted from the
data stream. Cases with other values are analyzed.
+To filter based on a different condition, use
+transformations such as @cmd{COMPUTE} or @cmd{RECODE} to compute a
+filter variable of the required form, then specify that variable on
+@cmd{FILTER}.
@code{FILTER OFF} turns off case filtering.
Filtering takes place immediately before cases pass to a procedure for
analysis. Only one filter variable may be active at a time. Normally,
case filtering continues until it is explicitly turned off with @code{FILTER
-OFF}. However, if @cmd{FILTER} is placed after TEMPORARY, filtering stops
-after execution of the next procedure or procedure-like command.
+OFF}. However, if @cmd{FILTER} is placed after TEMPORARY, it filters only
+the next procedure or procedure-like command.
@node N OF CASES, PROCESS IF, FILTER, Data Selection
@section N OF CASES
processed by procedures. PSPP currently does not make use of
case count estimates.
+When @cmd{N} is specified after @cmd{TEMPORARY}, it affects only
+the next procedure (@pxref{TEMPORARY}).
+
@node PROCESS IF, SAMPLE, N OF CASES, Data Selection
@section PROCESS IF
@vindex PROCESS IF
effects of executing @cmd{TEMPORARY}, then @cmd{SELECT IF}
(@pxref{SELECT IF}).
+The filtering performed by @cmd{PROCESS IF} takes place immediately
+before cases pass to a procedure for analysis. Because @cmd{PROCESS
+IF} affects only a single procedure, its placement relative to
+@cmd{TEMPORARY} is unimportant.
+
@cmd{PROCESS IF} is deprecated. It is included for compatibility with
old command files. New syntax files should use @cmd{SELECT IF} or
@cmd{FILTER} instead.
SAMPLE num1 [FROM num2].
@end display
-@cmd{SAMPLE} is used to randomly sample a proportion of the cases in
-the active file. @cmd{SAMPLE} is temporary, affecting only the next
-procedure, unless that is a data transformation, such as @cmd{SELECT IF}
-or @cmd{RECODE}.
+@cmd{SAMPLE} randomly samples a proportion of the cases in the active
+file. Unless it follows @cmd{TEMPORARY}, it operates as a
+transformation, permanently removing cases from the active file.
The proportion to sample can be expressed as a single number between 0
and 1. If @code{k} is the number specified, and @code{N} is the number
@var{N} cases in the active file.}
@end enumerate
-@cmd{SAMPLE}, @cmd{SELECT IF}, and @code{PROCESS IF} are performed in
+@cmd{SAMPLE} and @cmd{SELECT IF} are performed in
the order specified by the syntax file.
-@cmd{SAMPLE} is ignored before @code{SORT CASES}.
-
@cmd{SAMPLE} is always performed before @code{N OF CASES}, regardless
-of ordering in the syntax file. @xref{N OF CASES}.
+of ordering in the syntax file (@pxref{N OF CASES}).
The same values for @cmd{SAMPLE} may result in different samples. To
obtain the same sample, use the @code{SET} command to set the random
possible. Cases that are deleted early can be processed more
efficiently in time and space.
+When @cmd{SELECT IF} is specified following @cmd{TEMPORARY}
+(@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
+(@pxref{LAG}).
+
@node SPLIT FILE, TEMPORARY, SELECT IF, Data Selection
@section SPLIT FILE
@vindex SPLIT FILE
Specify OFF to disable @cmd{SPLIT FILE} and resume analysis of the
entire active file as a single group of data.
+When @cmd{SPLIT FILE} is specified after @cmd{TEMPORARY}, it affects only
+the next procedure (@pxref{TEMPORARY}).
+
@node TEMPORARY, WEIGHT, SPLIT FILE, Data Selection
@section TEMPORARY
@vindex TEMPORARY
affect only the execution of the next procedure or procedure-like
command. Their effects will not be saved to the active file.
-The only specification is the command name.
+The only specification on @cmd{TEMPORARY} is the command name.
@cmd{TEMPORARY} may not appear within a @cmd{DO IF} or @cmd{LOOP}
-construct. It may
-appear only once between procedures and procedure-like commands.
+construct. It may appear only once between procedures and
+procedure-like commands.
+
+Scratch variables cannot be used following @cmd{TEMPORARY}.
An example may help to clarify:
variable are interpreted as weighting factors of 0. User-missing
values are not treated specially.
+When @cmd{WEIGHT} is specified after @cmd{TEMPORARY}, it affects only
+the next procedure (@pxref{TEMPORARY}).
+
@cmd{WEIGHT} does not cause cases in the active file to be replicated in
memory.
turn, with the same rules applied. If all expressions evaluate to
false, then the @cmd{ELSE} code block is executed, if it is present.
+When @cmd{DO IF} or @cmd{ELSE IF} is specified following @cmd{TEMPORARY}
+(@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
+(@pxref{LAG}).
+
@node DO REPEAT, LOOP, DO IF, Conditionals and Looping
@section DO REPEAT
@vindex DO REPEAT
@cmd{BREAK} also terminates @cmd{LOOP} execution (@pxref{BREAK}).
+When @cmd{LOOP} or @cmd{END LOOP} is specified following @cmd{TEMPORARY}
+(@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
+(@pxref{LAG}).
+
@node Statistics, Utilities, Conditionals and Looping, Top
@chapter Statistics
* DESCRIPTIVES:: Descriptive statistics.
* FREQUENCIES:: Frequency tables.
* CROSSTABS:: Crosstabulation tables.
+* T-TEST:: Test Hypotheses about means.
@end menu
@node DESCRIPTIVES, FREQUENCIES, Statistics, Statistics
@section DESCRIPTIVES
+@vindex DESCRIPTIVES
@display
DESCRIPTIVES
/VARIABLES=var_list
@node FREQUENCIES, CROSSTABS, DESCRIPTIVES, Statistics
@section FREQUENCIES
+@vindex FREQUENCIES
@display
FREQUENCIES
/VARIABLES=var_list
value is reported.) By default, the mean, standard deviation of the
mean, minimum, and maximum are reported for each variable.
-NTILES causes the specified quartiles to be reported. For instance,
-@code{/NTILES=4} would cause quartiles to be reported. In addition,
-particular percentiles can be requested with the PERCENTILES subcommand.
+PERCENTILES causes the specified percentiles to be reported.
+The percentiles should be presented at a list of numbers between 0
+and 100 inclusive.
+The NTILES subcommand causes the percentiles to be reported at the
+boundaries of the data set divided into the specified number of ranges.
+For instance, @code{/NTILES=4} would cause quartiles to be reported.
+
-@node CROSSTABS, , FREQUENCIES, Statistics
+@node CROSSTABS, T-TEST, FREQUENCIES, Statistics
@section CROSSTABS
+@vindex CROSSTABS
@display
CROSSTABS
/TABLES=var_list BY var_list [BY var_list]@dots{}
number of dimensions is permitted, and any number of variables per
dimension is allowed. The TABLES subcommand may be repeated as many
times as needed. This is the only required subcommand in @dfn{general
-mode}.
+mode}.
Occasionally, one may want to invoke a special mode called @dfn{integer
-mode}. Normally, in general mode, PSPP will automatically determine
+mode}. Normally, in general mode, PSPP automatically determines
what values occur in the data. In integer mode, the user specifies the
range of values that the data assumes. To invoke this mode, specify the
VARIABLES subcommand, giving a range of data values in parentheses for
each variable to be used on the TABLES subcommand. Data values inside
the range are truncated to the nearest integer, then assigned to that
value. If values occur outside this range, they are discarded. When it
-is present, the VARIABLES subcommand must precede the TABLES subcommand.
+is present, the VARIABLES subcommand must precede the TABLES
+subcommand.
+
+In general mode, numeric and string variables may be specified on
+TABLES. Although long string variables are allowed, only their
+initial short-string parts are used. In integer mode, only numeric
+variables are allowed.
The MISSING subcommand determines the handling of user-missing values.
When set to TABLE, the default, missing values are dropped on a table by
an @samp{M} (for ``missing'') and excluded from statistical
calculations.
-Currently the WRITE subcommand is not used.
+Currently the WRITE subcommand is ignored.
The FORMAT subcommand controls the characteristics of the
crosstabulation tables to be displayed. It has a number of possible
Fixes for any of these deficiencies would be welcomed.
+@node T-TEST, , CROSSTABS, Statistics
+@comment node-name, next, previous, up
+@section T-TEST
+
+@vindex T-TEST
+@display
+T-TEST
+ /MISSING=@{ANALYSIS,LISTWISE@} @{EXCLUDE,INCLUDE@}
+ /CRITERIA=CIN(confidence)
+
+
+(One Sample mode.)
+ TESTVAL=test_value
+ /VARIABLES=var_list
+
+
+(Independent Samples mode.)
+ GROUPS=var(value1 [, value2])
+ /VARIABLES=var_list
+
+
+(Paired Samples mode.)
+ PAIRS=var_list [WITH var_list [(PAIRED)] ]
+
+@end display
+
+
+The @cmd{T-TEST} procedure outputs tables used in testing hypotheses about
+means.
+It operates in one of three modes:
+@itemize
+@item One Sample mode.
+@item Independent Groups mode.
+@item Paired mode.
+@end itemize
+
+@noindent
+Each of these modes are described in more detail below.
+There are two optional subcommands which are common to all modes.
+
+The @cmd{/CRITERIA} subcommand tells PSPP the confidence interval used
+in the tests. The default value is 0.95.
+
+
+The @cmd{MISSING} subcommand determines the handling of missing
+variables.
+If INCLUDE is set, then user-missing values are included in the
+calculations, but system-missing values are not.
+If EXCLUDE is set, which is the default, user-missing
+values are excluded as well as system-missing values.
+This is the default.
+
+If LISTWISE is set, then the entire case is excluded from analysis
+whenever any variable specified in the @cmd{/VARIABLES}, @cmd{/PAIRS} or
+@cmd{/GROUPS} subcommands contains a missing value.
+If ANALYSIS is set, then missing values are excluded only in the analysis for
+which they would be needed. This is the default.
+
+
+@menu
+* One Sample Mode:: Testing against a hypothesised mean
+* Independent Samples Mode:: Testing two independent groups for equal mean
+* Paired Samples Mode:: Testing two interdependent groups for equal mean
+@end menu
+
+@node One Sample Mode, Independent Samples Mode, T-TEST, T-TEST
+@subsection One Sample Mode
+
+The @cmd{TESTVAL} subcommand invokes the One Sample mode.
+This mode is used to test a population mean against a hypothesised
+mean.
+The value given to the @cmd{TESTVAL} subcommand is the value against
+which you wish to test.
+In this mode, you must also use the @cmd{/VARIABLES} subcommand to
+tell PSPP which variables you wish to test.
+
+@node Independent Samples Mode, Paired Samples Mode, One Sample Mode, T-TEST
+@comment node-name, next, previous, up
+@subsection Independent Samples Mode
+
+The @cmd{GROUPS} subcommand invokes Independent Samples mode or
+`Groups' mode.
+This mode is used to test whether two groups of values have the
+same population mean.
+In this mode, you must also use the @cmd{/VARIABLES} subcommand to
+tell PSPP the dependent variables you wish to test.
+
+The variable given in the @cmd{GROUPS} subcommand is the independent
+variable which determines to which group the samples belong.
+The values in parentheses are the specific values of the independent
+variable for each group.
+If the parentheses are omitted and no values are given, the default values
+of 1.0 and 2.0 are assumed.
+
+If the independent variable is numeric,
+it is acceptable to specify only one value inside the parentheses.
+If you do this, cases where the independent variable is
+less than or equal to this value belong to the first group, and cases
+greater than this value belong to the second group.
+When using this form of the @cmd{GROUPS} subcommand, missing values in
+the independent variable are excluded on a listwise basis, regardless
+of whether @cmd{/MISSING=LISTWISE} was specified.
+
+
+@node Paired Samples Mode, , Independent Samples Mode, T-TEST
+@comment node-name, next, previous, up
+@subsection Paired Samples Mode
+
+The @cmd{PAIRS} subcommand introduces Paired Samples mode.
+Use this mode when repeated measures have been taken from the same
+samples.
+If the the @code{WITH} keyword is omitted, then tables for all
+combinations of variables given in the @cmd{PAIRS} subcommand are
+generated.
+If the @code{WITH} keyword is given, and the @code{(PAIRED)} keyword
+is also given, then the number of variables preceding @code{WITH}
+must be the same as the number following it.
+In this case, tables for each respective pair of variables are
+generated.
+In the event that the @code{WITH} keyword is given, but the
+@code{(PAIRED)} keyword is omitted, then tables for each combination
+of variable preceding @code{WITH} against variable following
+@code{WITH} are generated.
+
+
@node Utilities, Not Implemented, Statistics, Top
@chapter Utilities
* INCLUDE:: Include a file within the current one.
* QUIT:: Terminate the PSPP session.
* SET:: Adjust PSPP runtime parameters.
+* SHOW:: Display runtime parameters.
* SUBTITLE:: Provide a document subtitle.
* TITLE:: Provide a document title.
@end menu
This command is not valid within a command file.
-@node SET, SUBTITLE, QUIT, Utilities
+@node SET, SHOW, QUIT, Utilities
@section SET
@vindex SET
overwrite files, for instance) but it is an improvement.
@end table
-@node SUBTITLE, TITLE, SET, Utilities
+@node SHOW, SUBTITLE, SET, Utilities
+@comment node-name, next, previous, up
+@section SHOW
+@vindex SHOW
+
+@display
+SHOW
+ /@var{subcommand}
+
+@end display
+
+@cmd{SHOW} can be used to display the current state of PSPP's
+execution parameters. All of the parameters which can be changed
+using @code{SET} @xref{SET}, can be examined using @cmd{SHOW}, by
+using a subcommand with the same name.
+In addition, @code{SHOW} supports the following subcommands:
+
+@table @code
+@item WARRANTY
+Show details of the lack of warranty for PSPP.
+@item COPYING
+Display the terms of PSPP's copyright licence @ref{License}.
+@end table
+
+
+
+@node SUBTITLE, TITLE, SHOW, Utilities
@section SUBTITLE
@vindex SUBTITLE
@table @code
@item int32 rec_type;
-Record type. Always set to 3.
+Record type. Always set to 7.
@item int32 subtype;
Record subtype. Always set to 4.
@table @code
@item int32 rec_type;
-Record type. Always set to 3.
+Record type. Always set to 7.
@item int32 subtype;
-Record subtype. May take any value.
+Record subtype. May take any value. According to Aapi
+H@"am@"al@"ainen, value 5 indicates a set of grouped variables and 6
+indicates date info (probably related to USE).
@item int32 size;
Size of each piece of data in the data part. Should have the value 4 or
* Version and Date Info Record::
* Identification Records::
* Variable Count Record::
+* Case Weight Variable Record::
* Variable Records::
* Value Label Records::
* Portable File Data::
Portable files are arranged as a series of lines of exactly 80
characters each. Each line is terminated by a carriage-return,
-line-feed sequence (henceforth, ``newline''). Newlines are not
-delimiters: they are only used to avoid line-length limitations existing
-on some operating systems.
+line-feed sequence ``new-lines''). New-lines are only used to avoid
+line length limits imposed by some OSes; they are not meaningful.
The file must be terminated with a @samp{Z} character. In addition, if
the final line in the file does not have exactly 80 characters, then it
character set, as explained in the next section. Therefore, the
@samp{Z} character is not necessarily an ASCII @samp{Z}.)
-For the rest of the description of the portable file format, newlines
+For the rest of the description of the portable file format, new-lines
and the trailing @samp{Z}s will be ignored, as if they did not exist,
because they are not an important part of understanding the file
contents.
@item
Variable count.
+@item
+Case weight variable (optional).
+
@item
Variables. Each variable record may optionally be followed by a
missing value record and a variable label record.
through @samp{9} plus capital letters @samp{A} through @samp{T}.
@item
-A fraction, consisting of a radix point (@samp{.}) followed by one or
-more base-30 digits (optional).
+Optional fraction, consisting of a radix point (@samp{.}) followed by
+one or more base-30 digits.
@item
-An exponent, consisting of a plus or minus sign (@samp{+} or @samp{-})
-followed by one or more base-30 digits (optional).
+Optional exponent, consisting of a plus or minus sign (@samp{+} or
+@samp{-}) followed by one or more base-30 digits.
@item
A forward slash (@samp{/}).
@end itemize
-Integer fields take form identical to floating-point fields, but they
+Integer fields take a form identical to floating-point fields, but they
may not contain a fraction.
String fields take the form of a integer field having value @var{n},
character set translation table, followed by an 8-byte tag string.
The 200-byte segment is divided into five 40-byte sections, each of
-which represents the string @code{ASCII SPSS PORT FILE} in a different
-character set encoding. (If the file is encoded in EBCDIC then the
-string is actually @code{EBCDIC SPSS PORT FILE}, and so on.) These
-strings are padded on the right with spaces in their own character set.
+which represents the string @code{@var{charset} SPSS PORT FILE} in a
+different character set encoding, where @var{charset} is the name of
+the character set used in the file, e.g.@: @code{ASCII} or
+@code{EBCDIC}. Each string is padded on the right with spaces in its
+respective character set.
It appears that these strings exist only to inform those who might view
the file on a screen, and that they are not parsed by SPSS products.
consists of a single string field giving additional information on the
product that wrote the portable file.
-@node Variable Count Record, Variable Records, Identification Records, Portable File Format
+@node Variable Count Record, Case Weight Variable Record, Identification Records, Portable File Format
@section Variable Count Record
The variable count record has tag code @samp{4}. It consists of two
dictionary. The purpose of the second is unknown; it contains the value
161 in all portable files examined so far.
-@node Variable Records, Value Label Records, Variable Count Record, Portable File Format
+@node Case Weight Variable Record, Variable Records, Variable Count Record, Portable File Format
+@section Case Weight Variable Record
+
+The case weight variable record is optional. If it is present, it
+indicates the variable used for weighting cases; if it is absent,
+cases are unweighted. It has tag code @samp{6}. It consists of a
+single string field that names the weighting variable.
+
+@node Variable Records, Value Label Records, Case Weight Variable Record, Portable File Format
@section Variable Records
Each variable record represents a single variable. Variable records
projects / pspp-builds.git / blobdiff