use moments.c to compute moments

[pspp-builds.git] / doc / transformation.texi

diff --git a/doc/transformation.texi b/doc/transformation.texi
index 7ad217b3bd03bc227e11a8cdf6cab953c06b81ef..d8b08a45c7f99ef5cdbcca584f0e326523d8655a 100644 (file)
--- a/doc/transformation.texi
+++ b/doc/transformation.texi
@@ -23,7 +23,7 @@ as a rule.
 
 @display
 AGGREGATE 
 
 @display
 AGGREGATE 

-        OUTFILE=@{*,'filename'@}          
+        OUTFILE=@{*,'file-name',file_handle@}

         /PRESORTED
         /DOCUMENT
         /MISSING=COLUMNWISE
         /PRESORTED
         /DOCUMENT
         /MISSING=COLUMNWISE


@@ -37,9 +37,11 @@ variables called @dfn{break variables}.  Several functions are available
 for summarizing case contents.
 
 The OUTFILE subcommand is required and must appear first.  Specify a
 for summarizing case contents.
 
 The OUTFILE subcommand is required and must appear first.  Specify a

-system file by file name string or file handle (@pxref{FILE HANDLE}).
+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
 The aggregated cases are written to this file.  If @samp{*} is

-specified, then the aggregated cases replace the active file.
+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
 
 By default, the active file will be sorted based on the break variables
 before aggregation takes place.  If the active file is already sorted


@@ -103,6 +105,9 @@ format is F5.3.
 @item FIRST(var_name)
 First non-missing value in break group.  The aggregation variable
 receives the complete dictionary information from the source variable.
 @item FIRST(var_name)
 First non-missing value in break group.  The aggregation variable
 receives the complete dictionary information from the source variable.

+The sort performed by AGGREGATE (and by SORT CASES) is stable, so that
+the first case with particular values for the break variables before
+sorting will also be the first case in that break group after sorting.

 
 @item FOUT(var_name, low, high)
 Fraction of values strictly outside the specified range of constants.
 
 @item FOUT(var_name, low, high)
 Fraction of values strictly outside the specified range of constants.


@@ -111,6 +116,9 @@ The default format is F5.3.
 @item LAST(var_name)
 Last non-missing value in break group.  The aggregation variable
 receives the complete dictionary information from the source variable.
 @item LAST(var_name)
 Last non-missing value in break group.  The aggregation variable
 receives the complete dictionary information from the source variable.

+The sort performed by AGGREGATE (and by SORT CASES) is stable, so that
+the last case with particular values for the break variables before
+sorting will also be the last case in that break group after sorting.

 
 @item MAX(var_name)
 Maximum value.  The aggregation variable receives the complete
 
 @item MAX(var_name)
 Maximum value.  The aggregation variable receives the complete


@@ -279,7 +287,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.
 
 The target variable values are always nonnegative integers.  They are
 never missing.  The target variable is assigned an F8.2 output format.

-@xref{Input/Output Formats}.  Any variables, including long and short
+@xref{Input and Output Formats}.  Any variables, including long and short

 string variables, may be test variables.
 
 User-missing values of test variables are treated just like any other
 string variables, may be test variables.
 
 User-missing values of test variables are treated just like any other


@@ -374,13 +382,14 @@ 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.
 
 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
-transposition.
+No subcommands are required.  If specified, the VARIABLES subcommand
+selects variables to be transformed into cases, and variables not
+specified are discarded.  If the VARIABLES subcommand is omitted, all
+variables are selected for transposition.

 
 The variables specified by NEWNAMES, which must be a string variable, is
 
 The variables specified by NEWNAMES, which must be a string variable, is

-used to give names to the variables created by @cmd{FLIP}.  If
+used to give names to the variables created by @cmd{FLIP}.  Only the
+first 8 characters of the variable are used.  If

 NEWNAMES is not
 specified then the default is a variable named CASE_LBL, if it exists.
 If it does not then the variables created by FLIP are named VAR000
 NEWNAMES is not
 specified then the default is a variable named CASE_LBL, if it exists.
 If it does not then the variables created by FLIP are named VAR000


@@ -394,13 +403,15 @@ extensions are added, starting with 1, until a unique name is found or
 there are no remaining possibilities.  If the latter occurs then the
 FLIP operation aborts.
 
 there are no remaining possibilities.  If the latter occurs then the
 FLIP operation aborts.
 

-The resultant dictionary contains a CASE_LBL variable, which stores the
-names of the variables in the dictionary before the transposition.  If
-the active file is subsequently transposed using @cmd{FLIP}, this
-variable can
-be used to recreate the original variable names.
+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
+transposed using @cmd{FLIP}, this variable can be used to recreate the
+original variable names.

 
 

-FLIP honors N OF CASES.  It ignores TEMPORARY, so that ``temporary''
+FLIP honors @cmd{N OF CASES} (@pxref{N OF CASES}).  It ignores
+@cmd{TEMPORARY} (@pxref{TEMPORARY}), so that ``temporary''

 transformations become permanent.
 
 @node IF, RECODE, FLIP, Data Manipulation
 transformations become permanent.
 
 @node IF, RECODE, FLIP, Data Manipulation


@@ -526,11 +537,17 @@ are sorted in ascending order.  To override sort order, specify (D) or
 for ascending order.  These apply to the entire list of variables
 preceding them.
 
 for ascending order.  These apply to the entire list of variables
 preceding them.
 

+The sort algorithms used by @cmd{SORT CASES} are stable.  That is,
+records that have equal values of the sort variables will have the
+same relative order before and after sorting.  As a special case,
+re-sorting an already sorted file will not affect the ordering of
+cases.
+

 @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} is a procedure.  It causes the data to be read.
 
 @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.
+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
 
 @cmd{SORT CASES} may not be specified following TEMPORARY.  
 @setfilename ignored