Autorecode: Add the /GROUP subcommand

[pspp] / doc / transformation.texi

diff --git a/doc/transformation.texi b/doc/transformation.texi
index 2a52ad17f72049b8fe4b036836a4bcd3bb3c7454..6964facd31c9695adcb93c7959e9f5439b9cc516 100644 (file)
--- a/doc/transformation.texi
+++ b/doc/transformation.texi
@@ -23,7 +23,7 @@ as a rule.
 
 @display
 AGGREGATE 
-        OUTFILE=@{*,'file-name',file_handle@}
+        OUTFILE=@{*,'file-name',file_handle@} [MODE=@{REPLACE, ADDVARIABLES@}]
         /PRESORTED
         /DOCUMENT
         /MISSING=COLUMNWISE
@@ -40,13 +40,29 @@ The OUTFILE subcommand is required and must appear first.  Specify a
 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.
+specified, then the aggregated cases replace the active file.
+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 file is replaced by a new file
+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 file.
+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 file will remain unchanged.
+Note that if ADDVARIABLES is specified, then the data @emph{must} be
+sorted on the break variables.
 
 By default, the active file will be sorted based on the break variables
 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.
+PRESORTED is assumed if MODE=ADDVARIABLES is used.
 
 Specify DOCUMENT to copy the documents from the active file into the
 aggregate file (@pxref{DOCUMENT}).  Otherwise, the aggregate file will
@@ -85,7 +101,7 @@ variables.  Each aggregation variable receives the results of applying
 the specified aggregation function to the corresponding source
 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:
 
@@ -203,8 +219,9 @@ settings (@pxref{SPLIT FILE}).
 
 @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
@@ -225,6 +242,10 @@ to 1), specify DESCENDING.
 
 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
@@ -239,7 +260,7 @@ COMPUTE vector(index) = expression.
 
 @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
@@ -290,7 +311,7 @@ one or more @dfn{test} variables for each case.
 
 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
@@ -435,7 +456,7 @@ Specify a boolean-valued expression (@pxref{Expressions}) to be tested
 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
@@ -481,7 +502,7 @@ dest_value may take the following forms:
 
 @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
@@ -553,4 +574,3 @@ 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