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