DEBUG EVALUATE: Eliminate lexical corner case, rewrite tests in Autotest.
[pspp] / doc / transformation.texi
1 @node Data Manipulation
2 @chapter Data transformations
3 @cindex transformations
4
5 The PSPP procedures examined in this chapter manipulate data and
6 prepare the active file for later analyses.  They do not produce output,
7 as a rule.
8
9 @menu
10 * AGGREGATE::                   Summarize multiple cases into a single case.
11 * AUTORECODE::                  Automatic recoding of variables.
12 * COMPUTE::                     Assigning a variable a calculated value.
13 * COUNT::                       Counting variables with particular values.
14 * FLIP::                        Exchange variables with cases.
15 * IF::                          Conditionally assigning a calculated value.
16 * RECODE::                      Mapping values from one set to another.
17 * SORT CASES::                  Sort the active file.
18 @end menu
19
20 @node AGGREGATE
21 @section AGGREGATE
22 @vindex AGGREGATE
23
24 @display
25 AGGREGATE 
26         OUTFILE=@{*,'file-name',file_handle@}
27         /PRESORTED
28         /DOCUMENT
29         /MISSING=COLUMNWISE
30         /BREAK=var_list
31         /dest_var['label']@dots{}=agr_func(src_vars, args@dots{})@dots{}
32 @end display
33
34 @cmd{AGGREGATE} summarizes groups of cases into single cases.
35 Cases are divided into groups that have the same values for one or more
36 variables called @dfn{break variables}.  Several functions are available
37 for summarizing case contents.
38
39 The OUTFILE subcommand is required and must appear first.  Specify a
40 system file, portable file, or scratch file by file name or file
41 handle (@pxref{File Handles}).
42 The aggregated cases are written to this file.  If @samp{*} is
43 specified, then the aggregated cases replace the active file.  Use of
44 OUTFILE to write a portable file or scratch file is a PSPP extension.
45
46 By default, the active file will be sorted based on the break variables
47 before aggregation takes place.  If the active file is already sorted
48 or otherwise grouped in terms of the break variables, specify
49 PRESORTED to save time.
50
51 Specify DOCUMENT to copy the documents from the active file into the
52 aggregate file (@pxref{DOCUMENT}).  Otherwise, the aggregate file will
53 not contain any documents, even if the aggregate file replaces the
54 active file.
55
56 Normally, only a single case (for SD and SD., two cases) need be
57 non-missing in each group for the aggregate variable to be
58 non-missing.  Specifying /MISSING=COLUMNWISE inverts this behavior, so
59 that the aggregate variable becomes missing if any aggregated value is
60 missing.
61
62 If PRESORTED, DOCUMENT, or MISSING are specified, they must appear
63 between OUTFILE and BREAK.
64
65 At least one break variable must be specified on BREAK, a
66 required subcommand.  The values of these variables are used to divide
67 the active file into groups to be summarized.  In addition, at least
68 one @var{dest_var} must be specified.
69
70 One or more sets of aggregation variables must be specified.  Each set
71 comprises a list of aggregation variables, an equals sign (@samp{=}),
72 the name of an aggregation function (see the list below), and a list
73 of source variables in parentheses.  Some aggregation functions expect
74 additional arguments following the source variable names.
75
76 Aggregation variables typically are created with no variable label,
77 value labels, or missing values.  Their default print and write
78 formats depend on the aggregation function used, with details given in
79 the table below.  A variable label for an aggregation variable may be
80 specified just after the variable's name in the aggregation variable
81 list.
82
83 Each set must have exactly as many source variables as aggregation
84 variables.  Each aggregation variable receives the results of applying
85 the specified aggregation function to the corresponding source
86 variable.  The MEAN, MEDIAN, SD, and SUM aggregation functions may only be
87 applied to numeric variables.  All the rest may be applied to numeric
88 and string variables.
89
90 The available aggregation functions are as follows:
91
92 @table @asis
93 @item FGT(var_name, value)
94 Fraction of values greater than the specified constant.  The default
95 format is F5.3.
96
97 @item FIN(var_name, low, high)
98 Fraction of values within the specified inclusive range of constants.
99 The default format is F5.3.
100
101 @item FLT(var_name, value)
102 Fraction of values less than the specified constant.  The default
103 format is F5.3.
104
105 @item FIRST(var_name)
106 First non-missing value in break group.  The aggregation variable
107 receives the complete dictionary information from the source variable.
108 The sort performed by AGGREGATE (and by SORT CASES) is stable, so that
109 the first case with particular values for the break variables before
110 sorting will also be the first case in that break group after sorting.
111
112 @item FOUT(var_name, low, high)
113 Fraction of values strictly outside the specified range of constants.
114 The default format is F5.3.
115
116 @item LAST(var_name)
117 Last non-missing value in break group.  The aggregation variable
118 receives the complete dictionary information from the source variable.
119 The sort performed by AGGREGATE (and by SORT CASES) is stable, so that
120 the last case with particular values for the break variables before
121 sorting will also be the last case in that break group after sorting.
122
123 @item MAX(var_name)
124 Maximum value.  The aggregation variable receives the complete
125 dictionary information from the source variable.
126
127 @item MEAN(var_name)
128 Arithmetic mean.  Limited to numeric values.  The default format is
129 F8.2.
130
131 @item MEDIAN(var_name)
132 The median value.  Limited to numeric values.  The default format is F8.2.
133
134 @item MIN(var_name)
135 Minimum value.  The aggregation variable receives the complete
136 dictionary information from the source variable.
137
138 @item N(var_name)
139 Number of non-missing values.  The default format is F7.0 if weighting
140 is not enabled, F8.2 if it is (@pxref{WEIGHT}).
141
142 @item N
143 Number of cases aggregated to form this group.  The default format is
144 F7.0 if weighting is not enabled, F8.2 if it is (@pxref{WEIGHT}).
145
146 @item NMISS(var_name)
147 Number of missing values.  The default format is F7.0 if weighting is
148 not enabled, F8.2 if it is (@pxref{WEIGHT}).
149
150 @item NU(var_name)
151 Number of non-missing values.  Each case is considered to have a weight
152 of 1, regardless of the current weighting variable (@pxref{WEIGHT}).
153 The default format is F7.0.
154
155 @item NU
156 Number of cases aggregated to form this group.  Each case is considered
157 to have a weight of 1, regardless of the current weighting variable.
158 The default format is F7.0.
159
160 @item NUMISS(var_name)
161 Number of missing values.  Each case is considered to have a weight of
162 1, regardless of the current weighting variable.  The default format is F7.0.
163
164 @item PGT(var_name, value)
165 Percentage between 0 and 100 of values greater than the specified
166 constant.  The default format is F5.1.
167
168 @item PIN(var_name, low, high)
169 Percentage of values within the specified inclusive range of
170 constants.  The default format is F5.1.
171
172 @item PLT(var_name, value)
173 Percentage of values less than the specified constant.  The default
174 format is F5.1.
175
176 @item POUT(var_name, low, high)
177 Percentage of values strictly outside the specified range of
178 constants.  The default format is F5.1.
179
180 @item SD(var_name)
181 Standard deviation of the mean.  Limited to numeric values.  The
182 default format is F8.2.
183
184 @item SUM(var_name)
185 Sum.  Limited to numeric values.  The default format is F8.2.
186 @end table
187
188 Aggregation functions compare string values in terms of internal
189 character codes.  On most modern computers, this is a form of ASCII.
190
191 The aggregation functions listed above exclude all user-missing values
192 from calculations.  To include user-missing values, insert a period
193 (@samp{.}) at the end of the function name.  (e.g.@: @samp{SUM.}).
194 (Be aware that specifying such a function as the last token on a line
195 will cause the period to be interpreted as the end of the command.)
196
197 @cmd{AGGREGATE} both ignores and cancels the current @cmd{SPLIT FILE}
198 settings (@pxref{SPLIT FILE}).
199
200 @node AUTORECODE
201 @section AUTORECODE
202 @vindex AUTORECODE
203
204 @display
205 AUTORECODE VARIABLES=src_vars INTO dest_vars
206         /DESCENDING
207         /PRINT
208 @end display
209
210 The @cmd{AUTORECODE} procedure considers the @var{n} values that a variable
211 takes on and maps them onto values 1@dots{}@var{n} on a new numeric
212 variable.
213
214 Subcommand VARIABLES is the only required subcommand and must come
215 first.  Specify VARIABLES, an equals sign (@samp{=}), a list of source
216 variables, INTO, and a list of target variables.  There must the same
217 number of source and target variables.  The target variables must not
218 already exist.
219
220 By default, increasing values of a source variable (for a string, this
221 is based on character code comparisons) are recoded to increasing values
222 of its target variable.  To cause increasing values of a source variable
223 to be recoded to decreasing values of its target variable (@var{n} down
224 to 1), specify DESCENDING.
225
226 PRINT is currently ignored.
227
228 @cmd{AUTORECODE} is a procedure.  It causes the data to be read.
229
230 @node COMPUTE
231 @section COMPUTE
232 @vindex COMPUTE
233
234 @display
235 COMPUTE variable = expression.
236   or
237 COMPUTE vector(index) = expression.
238 @end display
239
240 @cmd{COMPUTE} assigns the value of an expression to a target
241 variable.  For each case, the expression is evaluated and its value
242 assigned to the target variable.  Numeric and string
243 variables may be assigned.  When a string expression's width differs
244 from the target variable's width, the string result of the expression
245 is truncated or padded with spaces on the right as necessary.  The
246 expression and variable types must match.
247
248 For numeric variables only, the target variable need not already
249 exist.  Numeric variables created by @cmd{COMPUTE} are assigned an
250 @code{F8.2} output format.  String variables must be declared before
251 they can be used as targets for @cmd{COMPUTE}.
252
253 The target variable may be specified as an element of a vector
254 (@pxref{VECTOR}).  In this case, a vector index expression must be
255 specified in parentheses following the vector name.  The index
256 expression must evaluate to a numeric value that, after rounding down
257 to the nearest integer, is a valid index for the named vector.
258
259 Using @cmd{COMPUTE} to assign to a variable specified on @cmd{LEAVE}
260 (@pxref{LEAVE}) resets the variable's left state.  Therefore,
261 @code{LEAVE} should be specified following @cmd{COMPUTE}, not before.
262
263 @cmd{COMPUTE} is a transformation.  It does not cause the active file to be
264 read.
265
266 When @cmd{COMPUTE} is specified following @cmd{TEMPORARY}
267 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
268 (@pxref{LAG}).
269
270 @node COUNT
271 @section COUNT
272 @vindex COUNT
273
274 @display
275 COUNT var_name = var@dots{} (value@dots{}).
276
277 Each value takes one of the following forms:
278         number
279         string
280         num1 THRU num2
281         MISSING
282         SYSMIS
283 In addition, num1 and num2 can be LO or LOWEST, or HI or HIGHEST,
284 respectively.
285 @end display
286
287 @cmd{COUNT} creates or replaces a numeric @dfn{target} variable that
288 counts the occurrence of a @dfn{criterion} value or set of values over
289 one or more @dfn{test} variables for each case.
290
291 The target variable values are always nonnegative integers.  They are
292 never missing.  The target variable is assigned an F8.2 output format.
293 @xref{Input and Output Formats}.  Any variables, including
294 string variables, may be test variables.
295
296 User-missing values of test variables are treated just like any other
297 values.  They are @strong{not} treated as system-missing values.
298 User-missing values that are criterion values or inside ranges of
299 criterion values are counted as any other values.  However (for numeric
300 variables), keyword MISSING may be used to refer to all system-
301 and user-missing values.
302
303 @cmd{COUNT} target variables are assigned values in the order
304 specified.  In the command @code{COUNT A=A B(1) /B=A B(2).}, the
305 following actions occur:
306
307 @itemize @minus
308 @item
309 The number of occurrences of 1 between @code{A} and @code{B} is counted.
310
311 @item
312 @code{A} is assigned this value.
313
314 @item
315 The number of occurrences of 1 between @code{B} and the @strong{new}
316 value of @code{A} is counted.
317
318 @item
319 @code{B} is assigned this value.
320 @end itemize
321
322 Despite this ordering, all @cmd{COUNT} criterion variables must exist
323 before the procedure is executed---they may not be created as target
324 variables earlier in the command!  Break such a command into two
325 separate commands.
326
327 The examples below may help to clarify.
328
329 @enumerate A
330 @item
331 Assuming @code{Q0}, @code{Q2}, @dots{}, @code{Q9} are numeric variables,
332 the following commands:
333
334 @enumerate
335 @item
336 Count the number of times the value 1 occurs through these variables
337 for each case and assigns the count to variable @code{QCOUNT}.  
338
339 @item
340 Print out the total number of times the value 1 occurs throughout
341 @emph{all} cases using @cmd{DESCRIPTIVES}.  @xref{DESCRIPTIVES}, for
342 details.
343 @end enumerate
344
345 @example
346 COUNT QCOUNT=Q0 TO Q9(1).
347 DESCRIPTIVES QCOUNT /STATISTICS=SUM.
348 @end example
349
350 @item
351 Given these same variables, the following commands:
352
353 @enumerate
354 @item
355 Count the number of valid values of these variables for each case and
356 assigns the count to variable @code{QVALID}.
357
358 @item
359 Multiplies each value of @code{QVALID} by 10 to obtain a percentage of
360 valid values, using @cmd{COMPUTE}.  @xref{COMPUTE}, for details.
361
362 @item
363 Print out the percentage of valid values across all cases, using
364 @cmd{DESCRIPTIVES}.  @xref{DESCRIPTIVES}, for details.
365 @end enumerate
366
367 @example
368 COUNT QVALID=Q0 TO Q9 (LO THRU HI).
369 COMPUTE QVALID=QVALID*10.
370 DESCRIPTIVES QVALID /STATISTICS=MEAN.
371 @end example
372 @end enumerate
373
374 @node FLIP
375 @section FLIP
376 @vindex FLIP
377
378 @display
379 FLIP /VARIABLES=var_list /NEWNAMES=var_name.
380 @end display
381
382 @cmd{FLIP} transposes rows and columns in the active file.  It
383 causes cases to be swapped with variables, and vice versa.
384
385 All variables in the transposed active file are numeric.  String
386 variables take on the system-missing value in the transposed file.
387
388 No subcommands are required.  If specified, the VARIABLES subcommand
389 selects variables to be transformed into cases, and variables not
390 specified are discarded.  If the VARIABLES subcommand is omitted, all
391 variables are selected for transposition.
392
393 The variables specified by NEWNAMES, which must be a string variable, is
394 used to give names to the variables created by @cmd{FLIP}.  Only the
395 first 8 characters of the variable are used.  If
396 NEWNAMES is not
397 specified then the default is a variable named CASE_LBL, if it exists.
398 If it does not then the variables created by FLIP are named VAR000
399 through VAR999, then VAR1000, VAR1001, and so on.
400
401 When a NEWNAMES variable is available, the names must be canonicalized
402 before becoming variable names.  Invalid characters are replaced by
403 letter @samp{V} in the first position, or by @samp{_} in subsequent
404 positions.  If the name thus generated is not unique, then numeric
405 extensions are added, starting with 1, until a unique name is found or
406 there are no remaining possibilities.  If the latter occurs then the
407 FLIP operation aborts.
408
409 The resultant dictionary contains a CASE_LBL variable, a string
410 variable of width 8, which stores the names of the variables in the
411 dictionary before the transposition.  Variables names longer than 8
412 characters are truncated.  If the active file is subsequently
413 transposed using @cmd{FLIP}, this variable can be used to recreate the
414 original variable names.
415
416 FLIP honors @cmd{N OF CASES} (@pxref{N OF CASES}).  It ignores
417 @cmd{TEMPORARY} (@pxref{TEMPORARY}), so that ``temporary''
418 transformations become permanent.
419
420 @node IF
421 @section IF
422 @vindex IF
423
424 @display
425 IF condition variable=expression.
426   or
427 IF condition vector(index)=expression.
428 @end display
429
430 The @cmd{IF} transformation conditionally assigns the value of a target
431 expression to a target variable, based on the truth of a test
432 expression.
433
434 Specify a boolean-valued expression (@pxref{Expressions}) to be tested
435 following the IF keyword.  This expression is evaluated for each case.
436 If the value is true, then the value of the expression is computed and
437 assigned to the specified variable.  If the value is false or missing,
438 nothing is done.  Numeric and string variables may be
439 assigned.  When a string expression's width differs from the target
440 variable's width, the string result of the expression is truncated or
441 padded with spaces on the right as necessary.  The expression and
442 variable types must match.
443
444 The target variable may be specified as an element of a vector
445 (@pxref{VECTOR}).  In this case, a vector index expression must be
446 specified in parentheses following the vector name.  The index
447 expression must evaluate to a numeric value that, after rounding down
448 to the nearest integer, is a valid index for the named vector.
449
450 Using @cmd{IF} to assign to a variable specified on @cmd{LEAVE}
451 (@pxref{LEAVE}) resets the variable's left state.  Therefore,
452 @code{LEAVE} should be specified following @cmd{IF}, not before.
453
454 When @cmd{IF} is specified following @cmd{TEMPORARY}
455 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
456 (@pxref{LAG}).
457
458 @node RECODE
459 @section RECODE
460 @vindex RECODE
461
462 @display
463 RECODE var_list (src_value@dots{}=dest_value)@dots{} [INTO var_list].
464
465 src_value may take the following forms:
466         number
467         string
468         num1 THRU num2
469         MISSING
470         SYSMIS
471         ELSE
472 Open-ended ranges may be specified using LO or LOWEST for num1
473 or HI or HIGHEST for num2.
474
475 dest_value may take the following forms:
476         num
477         string
478         SYSMIS
479         COPY
480 @end display
481
482 @cmd{RECODE} translates data from one range of values to
483 another, via flexible user-specified mappings.  Data may be remapped
484 in-place or copied to new variables.  Numeric and
485 string data can be recoded.
486
487 Specify the list of source variables, followed by one or more mapping
488 specifications each enclosed in parentheses.  If the data is to be
489 copied to new variables, specify INTO, then the list of target
490 variables.  String target variables must already have been declared
491 using @cmd{STRING} or another transformation, but numeric target
492 variables can
493 be created on the fly.  There must be exactly as many target variables
494 as source variables.  Each source variable is remapped into its
495 corresponding target variable.
496
497 When INTO is not used, the input and output variables must be of the
498 same type.  Otherwise, string values can be recoded into numeric values,
499 and vice versa.  When this is done and there is no mapping for a
500 particular value, either a value consisting of all spaces or the
501 system-missing value is assigned, depending on variable type.
502
503 Mappings are considered from left to right.  The first src_value that
504 matches the value of the source variable causes the target variable to
505 receive the value indicated by the dest_value.  Literal number, string,
506 and range src_value's should be self-explanatory.  MISSING as a
507 src_value matches any user- or system-missing value.  SYSMIS matches the
508 system missing value only.  ELSE is a catch-all that matches anything.
509 It should be the last src_value specified.
510
511 Numeric and string dest_value's should be self-explanatory.  COPY
512 causes the input values to be copied to the output.  This is only valid
513 if the source and target variables are of the same type.  SYSMIS
514 indicates the system-missing value.
515
516 If the source variables are strings and the target variables are
517 numeric, then there is one additional mapping available: (CONVERT),
518 which must be the last specified mapping.  CONVERT causes a number
519 specified as a string to be converted to a numeric value.  If the string
520 cannot be parsed as a number, then the system-missing value is assigned.
521
522 Multiple recodings can be specified on a single @cmd{RECODE} invocation.
523 Introduce additional recodings with a slash (@samp{/}) to
524 separate them from the previous recodings.
525
526 @node SORT CASES
527 @section SORT CASES
528 @vindex SORT CASES
529
530 @display
531 SORT CASES BY var_list[(@{D|A@}] [ var_list[(@{D|A@}] ] ...
532 @end display
533
534 @cmd{SORT CASES} sorts the active file by the values of one or more
535 variables.
536
537 Specify BY and a list of variables to sort by.  By default, variables
538 are sorted in ascending order.  To override sort order, specify (D) or
539 (DOWN) after a list of variables to get descending order, or (A) or (UP)
540 for ascending order.  These apply to all the listed variables
541 up until the preceding (A), (D), (UP) or (DOWN).
542
543 The sort algorithms used by @cmd{SORT CASES} are stable.  That is,
544 records that have equal values of the sort variables will have the
545 same relative order before and after sorting.  As a special case,
546 re-sorting an already sorted file will not affect the ordering of
547 cases.
548
549 @cmd{SORT CASES} is a procedure.  It causes the data to be read.
550
551 @cmd{SORT CASES} attempts to sort the entire active file in main memory.
552 If workspace is exhausted, it falls back to a merge sort algorithm that
553 involves creates numerous temporary files.
554
555 @cmd{SORT CASES} may not be specified following TEMPORARY.