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