-@node Data Manipulation, Data Selection, Variable Attributes, Top
+@node Data Manipulation
@chapter Data transformations
@cindex transformations
The PSPP procedures examined in this chapter manipulate data and
-prepare the active file for later analyses. They do not produce output,
+prepare the active dataset for later analyses. They do not produce output,
as a rule.
@menu
* FLIP:: Exchange variables with cases.
* IF:: Conditionally assigning a calculated value.
* RECODE:: Mapping values from one set to another.
-* SORT CASES:: Sort the active file.
+* SORT CASES:: Sort the active dataset.
@end menu
-@node AGGREGATE, AUTORECODE, Data Manipulation, Data Manipulation
+@node AGGREGATE
@section AGGREGATE
@vindex AGGREGATE
@display
AGGREGATE
- OUTFILE=@{*,'file-name',file_handle@}
+ OUTFILE=@{*,'file-name',file_handle@} [MODE=@{REPLACE, ADDVARIABLES@}]
/PRESORTED
/DOCUMENT
/MISSING=COLUMNWISE
system file, portable file, or scratch file by file name or file
handle (@pxref{File Handles}).
The aggregated cases are written to this file. If @samp{*} is
-specified, then the aggregated cases replace the active file. Use of
-OUTFILE to write a portable file or scratch file is a PSPP extension.
-
-By default, the active file will be sorted based on the break variables
-before aggregation takes place. If the active file is already sorted
+specified, then the aggregated cases replace the active dataset's data.
+Use of OUTFILE to write a portable file or scratch file is a PSPP extension.
+
+If OUTFILE=@samp{*} is given, then the subcommand MODE may also be
+specified.
+The mode subcommand has two possible values: ADDVARIABLES or REPLACE.
+In REPLACE mode, the entire active dataset is replaced by a new dataset
+which contains just the break variables and the destination varibles.
+In this mode, the new file will contain as many cases as there are
+unique combinations of the break variables.
+In ADDVARIABLES mode, the destination variables will be appended to
+the existing active dataset.
+Cases which have identical combinations of values in their break
+variables, will receive identical values for the destination variables.
+The number of cases in the active dataset will remain unchanged.
+Note that if ADDVARIABLES is specified, then the data @emph{must} be
+sorted on the break variables.
+
+By default, the active dataset will be sorted based on the break variables
+before aggregation takes place. If the active dataset is already sorted
or otherwise grouped in terms of the break variables, specify
PRESORTED to save time.
+PRESORTED is assumed if MODE=ADDVARIABLES is used.
-Specify DOCUMENT to copy the documents from the active file into the
+Specify DOCUMENT to copy the documents from the active dataset into the
aggregate file (@pxref{DOCUMENT}). Otherwise, the aggregate file will
not contain any documents, even if the aggregate file replaces the
-active file.
+active dataset.
Normally, only a single case (for SD and SD., two cases) need be
non-missing in each group for the aggregate variable to be
At least one break variable must be specified on BREAK, a
required subcommand. The values of these variables are used to divide
-the active file into groups to be summarized. In addition, at least
+the active dataset into groups to be summarized. In addition, at least
one @var{dest_var} must be specified.
One or more sets of aggregation variables must be specified. Each set
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. The MEAN, SD, and SUM aggregation functions may only be
+variable. The MEAN, MEDIAN, SD, and SUM aggregation functions may only be
applied to numeric variables. All the rest may be applied to numeric
-and short and long string variables.
+and string variables.
The available aggregation functions are as follows:
Arithmetic mean. Limited to numeric values. The default format is
F8.2.
+@item MEDIAN(var_name)
+The median value. Limited to numeric values. The default format is F8.2.
+
@item MIN(var_name)
Minimum value. The aggregation variable receives the complete
dictionary information from the source variable.
@cmd{AGGREGATE} both ignores and cancels the current @cmd{SPLIT FILE}
settings (@pxref{SPLIT FILE}).
-@node AUTORECODE, COMPUTE, AGGREGATE, Data Manipulation
+@node AUTORECODE
@section AUTORECODE
@vindex AUTORECODE
@display
AUTORECODE VARIABLES=src_vars INTO dest_vars
- /DESCENDING
- /PRINT
+ [ /DESCENDING ]
+ [ /PRINT ]
+ [ /GROUP ]
@end display
The @cmd{AUTORECODE} procedure considers the @var{n} values that a variable
PRINT is currently ignored.
+The GROUP subcommand is relevant only if more than one variable is to be
+recoded. It causes a single mapping between source and target values to
+be used, instead of one map per variable.
+
@cmd{AUTORECODE} is a procedure. It causes the data to be read.
-@node COMPUTE, COUNT, AUTORECODE, Data Manipulation
+@node COMPUTE
@section COMPUTE
@vindex COMPUTE
@cmd{COMPUTE} assigns the value of an expression to a target
variable. For each case, the expression is evaluated and its value
-assigned to the target variable. Numeric and short and long string
+assigned to the target variable. Numeric and string
variables may be assigned. When a string expression's width differs
from the target variable's width, the string result of the expression
is truncated or padded with spaces on the right as necessary. The
(@pxref{LEAVE}) resets the variable's left state. Therefore,
@code{LEAVE} should be specified following @cmd{COMPUTE}, not before.
-@cmd{COMPUTE} is a transformation. It does not cause the active file to be
+@cmd{COMPUTE} is a transformation. It does not cause the active dataset 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
+@node COUNT
@section COUNT
@vindex COUNT
The target variable values are always nonnegative integers. They are
never missing. The target variable is assigned an F8.2 output format.
-@xref{Input and Output Formats}. Any variables, including long and short
+@xref{Input and Output Formats}. Any variables, including
string variables, may be test variables.
User-missing values of test variables are treated just like any other
@end example
@end enumerate
-@node FLIP, IF, COUNT, Data Manipulation
+@node FLIP
@section FLIP
@vindex FLIP
FLIP /VARIABLES=var_list /NEWNAMES=var_name.
@end display
-@cmd{FLIP} transposes rows and columns in the active file. It
+@cmd{FLIP} transposes rows and columns in the active dataset. It
causes cases to be swapped with variables, and vice versa.
-All variables in the transposed active file are numeric. String
+All variables in the transposed active dataset are numeric. String
variables take on the system-missing value in the transposed file.
No subcommands are required. If specified, the VARIABLES subcommand
The resultant dictionary contains a CASE_LBL variable, a string
variable of width 8, which stores the names of the variables in the
dictionary before the transposition. Variables names longer than 8
-characters are truncated. If the active file is subsequently
+characters are truncated. If the active dataset is subsequently
transposed using @cmd{FLIP}, this variable can be used to recreate the
original variable names.
@cmd{TEMPORARY} (@pxref{TEMPORARY}), so that ``temporary''
transformations become permanent.
-@node IF, RECODE, FLIP, Data Manipulation
+@node IF
@section IF
@vindex IF
following the IF keyword. This expression is evaluated for each case.
If the value is true, then the value of the expression is computed and
assigned to the specified variable. If the value is false or missing,
-nothing is done. Numeric and short and long string variables may be
+nothing is done. Numeric and string variables may be
assigned. When a string expression's width differs from the target
variable's width, the string result of the expression is truncated or
padded with spaces on the right as necessary. The expression and
(@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
(@pxref{LAG}).
-@node RECODE, SORT CASES, IF, Data Manipulation
+@node RECODE
@section RECODE
@vindex RECODE
@cmd{RECODE} translates data from one range of values to
another, via flexible user-specified mappings. Data may be remapped
-in-place or copied to new variables. Numeric, short string, and long
+in-place or copied to new variables. Numeric and
string data can be recoded.
Specify the list of source variables, followed by one or more mapping
system missing value only. ELSE is a catch-all that matches anything.
It should be the last src_value specified.
-Numeric and string dest_value's should also be self-explanatory. COPY
-causes the input values to be copied to the output. This is only value
+Numeric and string dest_value's should be self-explanatory. COPY
+causes the input values to be copied to the output. This is only valid
if the source and target variables are of the same type. SYSMIS
indicates the system-missing value.
Introduce additional recodings with a slash (@samp{/}) to
separate them from the previous recodings.
-@node SORT CASES, , RECODE, Data Manipulation
+@node SORT CASES
@section SORT CASES
@vindex SORT CASES
@display
-SORT CASES BY var_list.
+SORT CASES BY var_list[(@{D|A@}] [ var_list[(@{D|A@}] ] ...
@end display
-@cmd{SORT CASES} sorts the active file by the values of one or more
+@cmd{SORT CASES} sorts the active dataset by the values of one or more
variables.
Specify BY and a list of variables to sort by. By default, variables
are sorted in ascending order. To override sort order, specify (D) or
(DOWN) after a list of variables to get descending order, or (A) or (UP)
-for ascending order. These apply to the entire list of variables
-preceding them.
+for ascending order. These apply to all the listed variables
+up until the preceding (A), (D), (UP) or (DOWN).
The sort algorithms used by @cmd{SORT CASES} are stable. That is,
records that have equal values of the sort variables will have the
@cmd{SORT CASES} is a procedure. It causes the data to be read.
-@cmd{SORT CASES} attempts to sort the entire active file in main memory.
+@cmd{SORT CASES} attempts to sort the entire active dataset in main memory.
If workspace is exhausted, it falls back to a merge sort algorithm that
involves creates numerous temporary files.
@cmd{SORT CASES} may not be specified following TEMPORARY.
-@setfilename ignored
projects / pspp-builds.git / blobdiff