zip-reader.c: Fix memory leak
[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 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=@{*,'@var{file_name}',@var{file_handle}@} [MODE=@{REPLACE, ADDVARIABLES@}]
27         /PRESORTED
28         /DOCUMENT
29         /MISSING=COLUMNWISE
30         /BREAK=@var{var_list}
31         /@var{dest_var}['@var{label}']@dots{}=@var{agr_func}(@var{src_vars}, @var{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 @subcmd{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 @subcmd{OUTFILE} to write a portable file is a @pspp{} extension.
46
47 If @subcmd{OUTFILE=*} is given, then the subcommand @subcmd{MODE} may also be
48 specified.
49 The mode subcommand has two possible values: @subcmd{ADDVARIABLES} or @subcmd{REPLACE}.
50 In @subcmd{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 @subcmd{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 @subcmd{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 @subcmd{PRESORTED} to save time.
66 @subcmd{PRESORTED} is assumed if @subcmd{MODE=ADDVARIABLES} is used.
67
68 Specify @subcmd{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 @subcmd{SD} and @subcmd{SD}., two cases) need be
74 non-missing in each group for the aggregate variable to be
75 non-missing.  Specifying @subcmd{/MISSING=COLUMNWISE} inverts this behavior, so
76 that the aggregate variable becomes missing if any aggregated value is
77 missing.
78
79 If @subcmd{PRESORTED}, @subcmd{DOCUMENT}, or @subcmd{MISSING} are specified, they must appear
80 between @subcmd{OUTFILE} and @subcmd{BREAK}.
81
82 At least one break variable must be specified on @subcmd{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 @subcmd{MEAN}, @subcmd{MEDIAN}, @subcmd{SD}, and @subcmd{SUM}
104 aggregation functions may only be
105 applied to numeric variables.  All the rest may be applied to numeric
106 and string variables.
107
108 The available aggregation functions are as follows:
109
110 @table @asis
111 @item @subcmd{FGT(@var{var_name}, @var{value})}
112 Fraction of values greater than the specified constant.  The default
113 format is F5.3.
114
115 @item @subcmd{FIN(@var{var_name}, @var{low}, @var{high})}
116 Fraction of values within the specified inclusive range of constants.
117 The default format is F5.3.
118
119 @item @subcmd{FLT(@var{var_name}, @var{value})}
120 Fraction of values less than the specified constant.  The default
121 format is F5.3.
122
123 @item @subcmd{FIRST(@var{var_name})}
124 First non-missing value in break group.  The aggregation variable
125 receives the complete dictionary information from the source variable.
126 The sort performed by @cmd{AGGREGATE} (and by @cmd{SORT CASES}) is stable, so that
127 the first case with particular values for the break variables before
128 sorting will also be the first case in that break group after sorting.
129
130 @item @subcmd{FOUT(@var{var_name}, @var{low}, @var{high})}
131 Fraction of values strictly outside the specified range of constants.
132 The default format is F5.3.
133
134 @item @subcmd{LAST(@var{var_name})}
135 Last non-missing value in break group.  The aggregation variable
136 receives the complete dictionary information from the source variable.
137 The sort performed by @cmd{AGGREGATE} (and by @cmd{SORT CASES}) is stable, so that
138 the last case with particular values for the break variables before
139 sorting will also be the last case in that break group after sorting.
140
141 @item @subcmd{MAX(@var{var_name})}
142 Maximum value.  The aggregation variable receives the complete
143 dictionary information from the source variable.
144
145 @item @subcmd{MEAN(@var{var_name})}
146 Arithmetic mean.  Limited to numeric values.  The default format is
147 F8.2.
148
149 @item @subcmd{MEDIAN(@var{var_name})}
150 The median value.  Limited to numeric values.  The default format is F8.2.
151
152 @item @subcmd{MIN(@var{var_name})}
153 Minimum value.  The aggregation variable receives the complete
154 dictionary information from the source variable.
155
156 @item @subcmd{N(@var{var_name})}
157 Number of non-missing values.  The default format is F7.0 if weighting
158 is not enabled, F8.2 if it is (@pxref{WEIGHT}).
159
160 @item @subcmd{N}
161 Number of cases aggregated to form this group.  The default format is
162 F7.0 if weighting is not enabled, F8.2 if it is (@pxref{WEIGHT}).
163
164 @item @subcmd{NMISS(@var{var_name})}
165 Number of missing values.  The default format is F7.0 if weighting is
166 not enabled, F8.2 if it is (@pxref{WEIGHT}).
167
168 @item @subcmd{NU(@var{var_name})}
169 Number of non-missing values.  Each case is considered to have a weight
170 of 1, regardless of the current weighting variable (@pxref{WEIGHT}).
171 The default format is F7.0.
172
173 @item @subcmd{NU}
174 Number of cases aggregated to form this group.  Each case is considered
175 to have a weight of 1, regardless of the current weighting variable.
176 The default format is F7.0.
177
178 @item @subcmd{NUMISS(@var{var_name})}
179 Number of missing values.  Each case is considered to have a weight of
180 1, regardless of the current weighting variable.  The default format is F7.0.
181
182 @item @subcmd{PGT(@var{var_name}, @var{value})}
183 Percentage between 0 and 100 of values greater than the specified
184 constant.  The default format is F5.1.
185
186 @item @subcmd{PIN(@var{var_name}, @var{low}, @var{high})}
187 Percentage of values within the specified inclusive range of
188 constants.  The default format is F5.1.
189
190 @item @subcmd{PLT(@var{var_name}, @var{value})}
191 Percentage of values less than the specified constant.  The default
192 format is F5.1.
193
194 @item @subcmd{POUT(@var{var_name}, @var{low}, @var{high})}
195 Percentage of values strictly outside the specified range of
196 constants.  The default format is F5.1.
197
198 @item @subcmd{SD(@var{var_name})}
199 Standard deviation of the mean.  Limited to numeric values.  The
200 default format is F8.2.
201
202 @item @subcmd{SUM(@var{var_name})}
203 Sum.  Limited to numeric values.  The default format is F8.2.
204 @end table
205
206 Aggregation functions compare string values in terms of internal
207 character codes.
208 On most modern computers, this is  @acronym{ASCII} or a superset thereof.
209
210 The aggregation functions listed above exclude all user-missing values
211 from calculations.  To include user-missing values, insert a period
212 (@samp{.}) at the end of the function name.  (e.g.@: @samp{SUM.}).
213 (Be aware that specifying such a function as the last token on a line
214 will cause the period to be interpreted as the end of the command.)
215
216 @cmd{AGGREGATE} both ignores and cancels the current @cmd{SPLIT FILE}
217 settings (@pxref{SPLIT FILE}).
218
219 @node AUTORECODE
220 @section AUTORECODE
221 @vindex AUTORECODE
222
223 @display
224 AUTORECODE VARIABLES=@var{src_vars} INTO @var{dest_vars}
225         [ /DESCENDING ]
226         [ /PRINT ]
227         [ /GROUP ]
228         [ /BLANK = @{VALID, MISSING@} ]
229 @end display
230
231 The @cmd{AUTORECODE} procedure considers the @var{n} values that a variable
232 takes on and maps them onto values 1@dots{}@var{n} on a new numeric
233 variable.
234
235 Subcommand @subcmd{VARIABLES} is the only required subcommand and must come
236 first.  Specify @subcmd{VARIABLES}, an equals sign (@samp{=}), a list of source
237 variables, @subcmd{INTO}, and a list of target variables.  There must the same
238 number of source and target variables.  The target variables must not
239 already exist.
240
241 By default, increasing values of a source variable (for a string, this
242 is based on character code comparisons) are recoded to increasing values
243 of its target variable.  To cause increasing values of a source variable
244 to be recoded to decreasing values of its target variable (@var{n} down
245 to 1), specify @subcmd{DESCENDING}.
246
247 @subcmd{PRINT} is currently ignored.
248
249 The @subcmd{GROUP} subcommand is relevant only if more than one variable is to be
250 recoded.   It causes a single mapping between source and target values to
251 be used, instead of one map per variable.
252
253 If @subcmd{/BLANK=MISSING} is given, then string variables which contain only 
254 whitespace are recoded as SYSMIS.  If @subcmd{/BLANK=VALID} is given then they
255 will be allocated a value like any other.  @subcmd{/BLANK} is not relevant
256 to numeric values. @subcmd{/BLANK=VALID} is the default.
257
258 @cmd{AUTORECODE} is a procedure.  It causes the data to be read.
259
260 @node COMPUTE
261 @section COMPUTE
262 @vindex COMPUTE
263
264 @display
265 COMPUTE @var{variable} = @var{expression}.
266 @end display
267   or
268 @display
269 COMPUTE vector(@var{index}) = @var{expression}.
270 @end display
271
272 @cmd{COMPUTE} assigns the value of an expression to a target
273 variable.  For each case, the expression is evaluated and its value
274 assigned to the target variable.  Numeric and string
275 variables may be assigned.  When a string expression's width differs
276 from the target variable's width, the string result of the expression
277 is truncated or padded with spaces on the right as necessary.  The
278 expression and variable types must match.
279
280 For numeric variables only, the target variable need not already
281 exist.  Numeric variables created by @cmd{COMPUTE} are assigned an
282 @code{F8.2} output format.  String variables must be declared before
283 they can be used as targets for @cmd{COMPUTE}.
284
285 The target variable may be specified as an element of a vector
286 (@pxref{VECTOR}).  In this case, an expression @var{index} must be
287 specified in parentheses following the vector name.  The expression @var{index}
288 must evaluate to a numeric value that, after rounding down
289 to the nearest integer, is a valid index for the named vector.
290
291 Using @cmd{COMPUTE} to assign to a variable specified on @cmd{LEAVE}
292 (@pxref{LEAVE}) resets the variable's left state.  Therefore,
293 @code{LEAVE} should be specified following @cmd{COMPUTE}, not before.
294
295 @cmd{COMPUTE} is a transformation.  It does not cause the active dataset to be
296 read.
297
298 When @cmd{COMPUTE} is specified following @cmd{TEMPORARY}
299 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
300 (@pxref{LAG}).
301
302 @node COUNT
303 @section COUNT
304 @vindex COUNT
305
306 @display
307 COUNT @var{var_name} = @var{var}@dots{} (@var{value}@dots{}).
308
309 Each @var{value} takes one of the following forms:
310         @var{number}
311         @var{string}
312         @var{num1} THRU @var{num2}
313         MISSING
314         SYSMIS
315 where @var{num1} is a numeric expression or the words @subcmd{LO}  or @subcmd{LOWEST}
316       and @var{num2} is a numeric expression  or @subcmd{HI} or @subcmd{HIGHEST}.
317 @end display
318
319 @cmd{COUNT} creates or replaces a numeric @dfn{target} variable that
320 counts the occurrence of a @dfn{criterion} value or set of values over
321 one or more @dfn{test} variables for each case.
322
323 The target variable values are always nonnegative integers.  They are
324 never missing.  The target variable is assigned an F8.2 output format.
325 @xref{Input and Output Formats}.  Any variables, including
326 string variables, may be test variables.
327
328 User-missing values of test variables are treated just like any other
329 values.  They are @strong{not} treated as system-missing values.
330 User-missing values that are criterion values or inside ranges of
331 criterion values are counted as any other values.  However (for numeric
332 variables), keyword @subcmd{MISSING} may be used to refer to all system-
333 and user-missing values.
334
335 @cmd{COUNT} target variables are assigned values in the order
336 specified.  In the command @subcmd{COUNT @var{A}=@var{A} @var{B}(1) /@var{B}=@var{A} @var{B}(2).}, the
337 following actions occur:
338
339 @itemize @minus
340 @item
341 The number of occurrences of 1 between @var{A} and @var{B} is counted.
342
343 @item
344 @var{A} is assigned this value.
345
346 @item
347 The number of occurrences of 1 between @var{B} and the @strong{new}
348 value of @var{A} is counted.
349
350 @item
351 @var{B} is assigned this value.
352 @end itemize
353
354 Despite this ordering, all @cmd{COUNT} criterion variables must exist
355 before the procedure is executed---they may not be created as target
356 variables earlier in the command!  Break such a command into two
357 separate commands.
358
359 The examples below may help to clarify.
360
361 @enumerate A
362 @item
363 Assuming @code{Q0}, @code{Q2}, @dots{}, @code{Q9} are numeric variables,
364 the following commands:
365
366 @enumerate
367 @item
368 Count the number of times the value 1 occurs through these variables
369 for each case and assigns the count to variable @code{QCOUNT}.  
370
371 @item
372 Print out the total number of times the value 1 occurs throughout
373 @emph{all} cases using @cmd{DESCRIPTIVES}.  @xref{DESCRIPTIVES}, for
374 details.
375 @end enumerate
376
377 @example
378 COUNT QCOUNT=Q0 TO Q9(1).
379 DESCRIPTIVES QCOUNT /STATISTICS=SUM.
380 @end example
381
382 @item
383 Given these same variables, the following commands:
384
385 @enumerate
386 @item
387 Count the number of valid values of these variables for each case and
388 assigns the count to variable @code{QVALID}.
389
390 @item
391 Multiplies each value of @code{QVALID} by 10 to obtain a percentage of
392 valid values, using @cmd{COMPUTE}.  @xref{COMPUTE}, for details.
393
394 @item
395 Print out the percentage of valid values across all cases, using
396 @cmd{DESCRIPTIVES}.  @xref{DESCRIPTIVES}, for details.
397 @end enumerate
398
399 @example
400 COUNT QVALID=Q0 TO Q9 (LO THRU HI).
401 COMPUTE QVALID=QVALID*10.
402 DESCRIPTIVES QVALID /STATISTICS=MEAN.
403 @end example
404 @end enumerate
405
406 @node FLIP
407 @section FLIP
408 @vindex FLIP
409
410 @display
411 FLIP /VARIABLES=@var{var_list} /NEWNAMES=@var{var_name}.
412 @end display
413
414 @cmd{FLIP} transposes rows and columns in the active dataset.  It
415 causes cases to be swapped with variables, and vice versa.
416
417 All variables in the transposed active dataset are numeric.  String
418 variables take on the system-missing value in the transposed file.
419
420 @subcmd{N} subcommands are required.  If specified, the @subcmd{VARIABLES} subcommand
421 selects variables to be transformed into cases, and variables not
422 specified are discarded.  If the @subcmd{VARIABLES} subcommand is omitted, all
423 variables are selected for transposition.
424
425 The variables specified by @subcmd{NEWNAMES}, which must be a
426 string variable, is
427 used to give names to the variables created by @cmd{FLIP}.  Only the
428 first 8 characters of the variable are used.  If
429 @subcmd{NEWNAMES} is not
430 specified then the default is a variable named CASE_LBL, if it exists.
431 If it does not then the variables created by @cmd{FLIP} are named VAR000
432 through VAR999, then VAR1000, VAR1001, and so on.
433
434 When a @subcmd{NEWNAMES} variable is available, the names must be canonicalized
435 before becoming variable names.  Invalid characters are replaced by
436 letter @samp{V} in the first position, or by @samp{_} in subsequent
437 positions.  If the name thus generated is not unique, then numeric
438 extensions are added, starting with 1, until a unique name is found or
439 there are no remaining possibilities.  If the latter occurs then the
440 @cmd{FLIP} operation aborts.
441
442 The resultant dictionary contains a CASE_LBL variable, a string
443 variable of width 8, which stores the names of the variables in the
444 dictionary before the transposition.  Variables names longer than 8
445 characters are truncated.  If the active dataset is subsequently
446 transposed using @cmd{FLIP}, this variable can be used to recreate the
447 original variable names.
448
449 @cmd{FLIP} honors @cmd{N OF CASES} (@pxref{N OF CASES}).  It ignores
450 @cmd{TEMPORARY} (@pxref{TEMPORARY}), so that ``temporary''
451 transformations become permanent.
452
453 @node IF
454 @section IF
455 @vindex IF
456
457 @display
458 IF @var{condition} @var{variable}=@var{expression}.
459 @end display
460   or
461 @display
462 IF @var{condition} vector(@var{index})=@var{expression}.
463 @end display
464
465 The @cmd{IF} transformation conditionally assigns the value of a target
466 expression to a target variable, based on the truth of a test
467 expression.
468
469 Specify a boolean-valued expression (@pxref{Expressions}) to be tested
470 following the @cmd{IF} keyword.  This expression is evaluated for each case.
471 If the value is true, then the value of the expression is computed and
472 assigned to the specified variable.  If the value is false or missing,
473 nothing is done.  Numeric and string variables may be
474 assigned.  When a string expression's width differs from the target
475 variable's width, the string result of the expression is truncated or
476 padded with spaces on the right as necessary.  The expression and
477 variable types must match.
478
479 The target variable may be specified as an element of a vector
480 (@pxref{VECTOR}).  In this case, a vector index expression must be
481 specified in parentheses following the vector name.  The index
482 expression must evaluate to a numeric value that, after rounding down
483 to the nearest integer, is a valid index for the named vector.
484
485 Using @cmd{IF} to assign to a variable specified on @cmd{LEAVE}
486 (@pxref{LEAVE}) resets the variable's left state.  Therefore,
487 @code{LEAVE} should be specified following @cmd{IF}, not before.
488
489 When @cmd{IF} is specified following @cmd{TEMPORARY}
490 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
491 (@pxref{LAG}).
492
493 @node RECODE
494 @section RECODE
495 @vindex RECODE
496
497 The @cmd{RECODE} command is used to transform existing values into other,
498 user specified values.
499 The general form is:
500
501 @display
502 RECODE @var{src_vars}
503         (@var{src_value} @var{src_value} @dots{} = @var{dest_value})
504         (@var{src_value} @var{src_value} @dots{} = @var{dest_value})
505         (@var{src_value} @var{src_value} @dots{} = @var{dest_value}) @dots{}
506          [INTO @var{dest_vars}].
507 @end display
508
509 Following the @cmd{RECODE} keyword itself comes @var{src_vars} which is a list
510 of variables whose values are to be transformed.
511 These variables may be string variables or they may be numeric.
512 However the list must be homogeneous; you may not mix string variables and
513 numeric variables in the same recoding.
514
515 After the list of source variables, there should be one or more @dfn{mappings}.
516 Each mapping is enclosed in parentheses, and contains the source values and
517 a destination value separated by a single @samp{=}.
518 The source values are used to specify the values in the dataset which 
519 need to change, and the destination value specifies the new value
520 to which they should be changed.
521 Each @var{src_value} may take one of the following forms:
522 @table @asis
523 @item @var{number}
524 If the source variables are numeric then @var{src_value} may be a literal
525 number.
526 @item @var{string}
527 If the source variables are string variables then @var{src_value} may be a
528 literal string (like all strings, enclosed in single or double quotes).
529 @item @var{num1} THRU @var{num2}
530 This form is valid only when the source variables are numeric.
531 It specifies all values in the range between @var{num1} and @var{num2},
532 including both endpoints of the range.  By convention, @var{num1}
533 should be less than @var{num2}.
534 Open-ended ranges may be specified using @samp{LO} or @samp{LOWEST} 
535 for @var{num1}
536 or @samp{HI} or @samp{HIGHEST} for @var{num2}.
537 @item @samp{MISSING}
538 The literal keyword @samp{MISSING} matches both system missing and user
539 missing values.
540 It is valid for both numeric and string variables.
541 @item @samp{SYSMIS}
542 The literal keyword @samp{SYSMIS} matches system missing
543 values.
544 It is valid for both numeric variables only.
545 @item @samp{ELSE}
546 The @samp{ELSE} keyword may be used to match any values which are
547 not matched by any other @var{src_value} appearing in the command.
548 If this keyword appears, it should be used in the last mapping of the 
549 command.
550 @end table
551
552 After the source variables comes an @samp{=} and then the @var{dest_value}.
553 The @var{dest_value} may take any of the following forms:
554 @table @asis
555 @item @var{number}
556 A literal numeric value to which the source values should be changed.
557 This implies the destination variable must be numeric.
558 @item @var{string}
559 A literal string value (enclosed in quotation marks) to which the source
560 values should be changed.
561 This implies the destination variable must be a string variable.
562 @item @samp{SYSMIS}
563 The keyword @samp{SYSMIS} changes the value to the system missing value.
564 This implies the destination variable must be numeric.
565 @item @samp{COPY}
566 The special keyword @samp{COPY} means that the source value should not be
567 modified, but
568 copied directly to the destination value.
569 This is meaningful only if @samp{INTO @var{dest_vars}} is specified.
570 @end table
571
572 Mappings are considered from left to right.
573 Therefore, if a value is matched by a @var{src_value} from more than 
574 one mapping, the first (leftmost) mapping which matches will be considered.
575 Any subsequent matches will be ignored.
576
577 The clause @samp{INTO @var{dest_vars}} is optional.
578 The behaviour of the command is slightly different depending on whether it
579 appears or not.
580
581 If @samp{INTO @var{dest_vars}} does not appear, then values will be recoded
582 ``in place´´.  This means that the recoded values are written back to the
583 source variables from whence the original values came.
584 In this case, the @var{dest_value} for every mapping must imply a value which
585 has the same type as the @var{src_value}.
586 For example, if the source value is a string value, it is not permissible for
587 @var{dest_value} to be @samp{SYSMIS} or another forms which implies a numeric
588 result.
589 The following example two numeric variables @var{x} and @var{y} are recoded
590 in place.
591 Zero is recoded to 99, the values 1 to 10 inclusive are unchanged,
592 values 1000 and higher are recoded to the system-missing value and all other
593 values are changed to 999:
594 @example
595 recode @var{x} @var{y} 
596         (0 = 99)
597         (1 THRU 10 = COPY)
598         (1000 THRU HIGHEST = SYSMIS)
599         (ELSE = 999).
600 @end example
601
602 If @samp{INTO @var{dest_vars}} is given, then recoded values are written
603 into the variables specified in @var{dest_vars}, which must therefore
604  contain a list of valid variable names.
605 The number of variables in @var{dest_vars} must be the same as the number
606 of variables in @var{src_vars}
607 and the respective order of the variables in @var{dest_vars} corresponds to 
608 the order of @var{src_vars}.
609 That is to say, recoded values whose 
610 original value came from the @var{n}th variable in @var{src_vars} will be
611 placed into the @var{n}th variable in @var{dest_vars}.
612 The source variables will be unchanged.
613 If any mapping implies a string as its destination value, then the respective
614 destination variable must already exist, or 
615 have been declared using @cmd{STRING} or another transformation.
616 Numeric variables however will be automatically created if they don't already
617 exist.
618 The following example deals with two source variables, @var{a} and @var{b}
619 which contain string values.  Hence there are two destination variables
620 @var{v1} and @var{v2}.
621 Any cases where @var{a} or @var{b} contain the values @samp{apple}, 
622 @samp{pear} or @samp{pomegranate} will result in @var{v1} or @var{v2} being
623 filled with the string @samp{fruit} whilst cases with 
624 @samp{tomato}, @samp{lettuce} or @samp{carrot} will result in @samp{vegetable}.
625 Any other values will produce the result @samp{unknown}:
626 @example
627 string @var{v1} (a20).
628 string @var{v2} (a20).
629
630 recode @var{a} @var{b} 
631         ("apple" "pear" "pomegranate" = "fruit")
632         ("tomato" "lettuce" "carrot" = "vegetable")
633         (ELSE = "unknown")
634         into @var{v1} @var{v2}.
635 @end example
636
637 There is one very special mapping, not mentioned above.
638 If the source variable is a string variable
639 then a mapping may be specified as @samp{(CONVERT)}.
640 This mapping, if it appears must be the last mapping given and
641 the @samp{INTO @var{dest_vars}} clause must also be given and 
642 must not refer to a string variable. 
643 @samp{CONVERT} causes a number specified as a string to
644 be converted to a numeric value. 
645 For example it will convert the string @samp{"3"} into the numeric
646 value 3 (note that it will not convert @samp{three} into 3).
647 If the string cannot be parsed as a number, then the system-missing value
648 is assigned instead.
649 In the following example, cases where the value of @var{x} (a string variable)
650 is the empty string, are recoded to 999 and all others are converted to the
651 numeric equivalent of the input value.  The results are placed into the 
652 numeric variable @var{y}:
653 @example
654 recode @var{x} 
655        ("" = 999)
656         (convert)
657         into @var{y}.
658 @end example
659
660 It is possible to specify multiple recodings on a single command.
661 Introduce additional recodings with a slash (@samp{/}) to
662 separate them from the previous recodings:
663 @example
664 recode 
665         @var{a}  (2 = 22) (else = 99) 
666         /@var{b} (1 = 3) into @var{z}
667         .
668 @end example
669 @noindent Here we have two recodings. The first affects the source variable
670 @var{a} and recodes in-place the value 2 into 22 and all other values to 99.
671 The second recoding copies the values of @var{b} into the the variable @var{z}, 
672 changing any instances of 1 into 3.
673
674 @node SORT CASES
675 @section SORT CASES
676 @vindex SORT CASES
677
678 @display
679 SORT CASES BY @var{var_list}[(@{D|A@}] [ @var{var_list}[(@{D|A@}] ] ...
680 @end display
681
682 @cmd{SORT CASES} sorts the active dataset by the values of one or more
683 variables.
684
685 Specify @subcmd{BY} and a list of variables to sort by.  By default, variables
686 are sorted in ascending order.  To override sort order, specify @subcmd{(D)} or
687 @subcmd{(DOWN)} after a list of variables to get descending order, or @subcmd{(A)} or @subcmd{(UP)}
688 for ascending order.  These apply to all the listed variables
689 up until the preceding @subcmd{(A)}, @subcmd{(D)}, @subcmd{(UP)} or @subcmd{(DOWN)}.
690
691 The sort algorithms used by @cmd{SORT CASES} are stable.  That is,
692 records that have equal values of the sort variables will have the
693 same relative order before and after sorting.  As a special case,
694 re-sorting an already sorted file will not affect the ordering of
695 cases.
696
697 @cmd{SORT CASES} is a procedure.  It causes the data to be read.
698
699 @cmd{SORT CASES} attempts to sort the entire active dataset in main memory.
700 If workspace is exhausted, it falls back to a merge sort algorithm that
701 involves creates numerous temporary files.
702
703 @cmd{SORT CASES} may not be specified following @cmd{TEMPORARY}.