1 @c PSPP - a program for statistical analysis.
2 @c Copyright (C) 2017 Free Software Foundation, Inc.
3 @c Permission is granted to copy, distribute and/or modify this document
4 @c under the terms of the GNU Free Documentation License, Version 1.3
5 @c or any later version published by the Free Software Foundation;
6 @c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
7 @c A copy of the license is included in the section entitled "GNU
8 @c Free Documentation License".
10 @node Data Manipulation
11 @chapter Data transformations
12 @cindex transformations
14 The @pspp{} procedures examined in this chapter manipulate data and
15 prepare the active dataset for later analyses. They do not produce output,
19 * AGGREGATE:: Summarize multiple cases into a single case.
20 * AUTORECODE:: Automatic recoding of variables.
21 * COMPUTE:: Assigning a variable a calculated value.
22 * COUNT:: Counting variables with particular values.
23 * FLIP:: Exchange variables with cases.
24 * IF:: Conditionally assigning a calculated value.
25 * RECODE:: Mapping values from one set to another.
26 * SORT CASES:: Sort the active dataset.
35 OUTFILE=@{*,'@var{file_name}',@var{file_handle}@} [MODE=@{REPLACE, ADDVARIABLES@}]
40 /@var{dest_var}['@var{label}']@dots{}=@var{agr_func}(@var{src_vars}, @var{args}@dots{})@dots{}
43 @cmd{AGGREGATE} summarizes groups of cases into single cases.
44 Cases are divided into groups that have the same values for one or more
45 variables called @dfn{break variables}. Several functions are available
46 for summarizing case contents.
48 The @subcmd{OUTFILE} subcommand is required and must appear first. Specify a
49 system file or portable file by file name or file
50 handle (@pxref{File Handles}), or a dataset by its name
52 The aggregated cases are written to this file. If @samp{*} is
53 specified, then the aggregated cases replace the active dataset's data.
54 Use of @subcmd{OUTFILE} to write a portable file is a @pspp{} extension.
56 If @subcmd{OUTFILE=*} is given, then the subcommand @subcmd{MODE} may also be
58 The mode subcommand has two possible values: @subcmd{ADDVARIABLES} or @subcmd{REPLACE}.
59 In @subcmd{REPLACE} mode, the entire active dataset is replaced by a new dataset
60 which contains just the break variables and the destination varibles.
61 In this mode, the new file will contain as many cases as there are
62 unique combinations of the break variables.
63 In @subcmd{ADDVARIABLES} mode, the destination variables will be appended to
64 the existing active dataset.
65 Cases which have identical combinations of values in their break
66 variables, will receive identical values for the destination variables.
67 The number of cases in the active dataset will remain unchanged.
68 Note that if @subcmd{ADDVARIABLES} is specified, then the data @emph{must} be
69 sorted on the break variables.
71 By default, the active dataset will be sorted based on the break variables
72 before aggregation takes place. If the active dataset is already sorted
73 or otherwise grouped in terms of the break variables, specify
74 @subcmd{PRESORTED} to save time.
75 @subcmd{PRESORTED} is assumed if @subcmd{MODE=ADDVARIABLES} is used.
77 Specify @subcmd{DOCUMENT} to copy the documents from the active dataset into the
78 aggregate file (@pxref{DOCUMENT}). Otherwise, the aggregate file will
79 not contain any documents, even if the aggregate file replaces the
82 Normally, only a single case (for @subcmd{SD} and @subcmd{SD}., two cases) need be
83 non-missing in each group for the aggregate variable to be
84 non-missing. Specifying @subcmd{/MISSING=COLUMNWISE} inverts this behavior, so
85 that the aggregate variable becomes missing if any aggregated value is
88 If @subcmd{PRESORTED}, @subcmd{DOCUMENT}, or @subcmd{MISSING} are specified, they must appear
89 between @subcmd{OUTFILE} and @subcmd{BREAK}.
91 At least one break variable must be specified on @subcmd{BREAK}, a
92 required subcommand. The values of these variables are used to divide
93 the active dataset into groups to be summarized. In addition, at least
94 one @var{dest_var} must be specified.
96 One or more sets of aggregation variables must be specified. Each set
97 comprises a list of aggregation variables, an equals sign (@samp{=}),
98 the name of an aggregation function (see the list below), and a list
99 of source variables in parentheses. Some aggregation functions expect
100 additional arguments following the source variable names.
102 Aggregation variables typically are created with no variable label,
103 value labels, or missing values. Their default print and write
104 formats depend on the aggregation function used, with details given in
105 the table below. A variable label for an aggregation variable may be
106 specified just after the variable's name in the aggregation variable
109 Each set must have exactly as many source variables as aggregation
110 variables. Each aggregation variable receives the results of applying
111 the specified aggregation function to the corresponding source
112 variable. The @subcmd{MEAN}, @subcmd{MEDIAN}, @subcmd{SD}, and @subcmd{SUM}
113 aggregation functions may only be
114 applied to numeric variables. All the rest may be applied to numeric
115 and string variables.
117 The available aggregation functions are as follows:
120 @item @subcmd{FGT(@var{var_name}, @var{value})}
121 Fraction of values greater than the specified constant. The default
124 @item @subcmd{FIN(@var{var_name}, @var{low}, @var{high})}
125 Fraction of values within the specified inclusive range of constants.
126 The default format is F5.3.
128 @item @subcmd{FLT(@var{var_name}, @var{value})}
129 Fraction of values less than the specified constant. The default
132 @item @subcmd{FIRST(@var{var_name})}
133 First non-missing value in break group. The aggregation variable
134 receives the complete dictionary information from the source variable.
135 The sort performed by @cmd{AGGREGATE} (and by @cmd{SORT CASES}) is stable, so that
136 the first case with particular values for the break variables before
137 sorting will also be the first case in that break group after sorting.
139 @item @subcmd{FOUT(@var{var_name}, @var{low}, @var{high})}
140 Fraction of values strictly outside the specified range of constants.
141 The default format is F5.3.
143 @item @subcmd{LAST(@var{var_name})}
144 Last non-missing value in break group. The aggregation variable
145 receives the complete dictionary information from the source variable.
146 The sort performed by @cmd{AGGREGATE} (and by @cmd{SORT CASES}) is stable, so that
147 the last case with particular values for the break variables before
148 sorting will also be the last case in that break group after sorting.
150 @item @subcmd{MAX(@var{var_name})}
151 Maximum value. The aggregation variable receives the complete
152 dictionary information from the source variable.
154 @item @subcmd{MEAN(@var{var_name})}
155 Arithmetic mean. Limited to numeric values. The default format is
158 @item @subcmd{MEDIAN(@var{var_name})}
159 The median value. Limited to numeric values. The default format is F8.2.
161 @item @subcmd{MIN(@var{var_name})}
162 Minimum value. The aggregation variable receives the complete
163 dictionary information from the source variable.
165 @item @subcmd{N(@var{var_name})}
166 Number of non-missing values. The default format is F7.0 if weighting
167 is not enabled, F8.2 if it is (@pxref{WEIGHT}).
170 Number of cases aggregated to form this group. The default format is
171 F7.0 if weighting is not enabled, F8.2 if it is (@pxref{WEIGHT}).
173 @item @subcmd{NMISS(@var{var_name})}
174 Number of missing values. The default format is F7.0 if weighting is
175 not enabled, F8.2 if it is (@pxref{WEIGHT}).
177 @item @subcmd{NU(@var{var_name})}
178 Number of non-missing values. Each case is considered to have a weight
179 of 1, regardless of the current weighting variable (@pxref{WEIGHT}).
180 The default format is F7.0.
183 Number of cases aggregated to form this group. Each case is considered
184 to have a weight of 1, regardless of the current weighting variable.
185 The default format is F7.0.
187 @item @subcmd{NUMISS(@var{var_name})}
188 Number of missing values. Each case is considered to have a weight of
189 1, regardless of the current weighting variable. The default format is F7.0.
191 @item @subcmd{PGT(@var{var_name}, @var{value})}
192 Percentage between 0 and 100 of values greater than the specified
193 constant. The default format is F5.1.
195 @item @subcmd{PIN(@var{var_name}, @var{low}, @var{high})}
196 Percentage of values within the specified inclusive range of
197 constants. The default format is F5.1.
199 @item @subcmd{PLT(@var{var_name}, @var{value})}
200 Percentage of values less than the specified constant. The default
203 @item @subcmd{POUT(@var{var_name}, @var{low}, @var{high})}
204 Percentage of values strictly outside the specified range of
205 constants. The default format is F5.1.
207 @item @subcmd{SD(@var{var_name})}
208 Standard deviation of the mean. Limited to numeric values. The
209 default format is F8.2.
211 @item @subcmd{SUM(@var{var_name})}
212 Sum. Limited to numeric values. The default format is F8.2.
215 Aggregation functions compare string values in terms of internal
217 On most modern computers, this is @acronym{ASCII} or a superset thereof.
219 The aggregation functions listed above exclude all user-missing values
220 from calculations. To include user-missing values, insert a period
221 (@samp{.}) at the end of the function name. (e.g.@: @samp{SUM.}).
222 (Be aware that specifying such a function as the last token on a line
223 will cause the period to be interpreted as the end of the command.)
225 @cmd{AGGREGATE} both ignores and cancels the current @cmd{SPLIT FILE}
226 settings (@pxref{SPLIT FILE}).
233 AUTORECODE VARIABLES=@var{src_vars} INTO @var{dest_vars}
237 [ /BLANK = @{VALID, MISSING@} ]
240 The @cmd{AUTORECODE} procedure considers the @var{n} values that a variable
241 takes on and maps them onto values 1@dots{}@var{n} on a new numeric
244 Subcommand @subcmd{VARIABLES} is the only required subcommand and must come
245 first. Specify @subcmd{VARIABLES}, an equals sign (@samp{=}), a list of source
246 variables, @subcmd{INTO}, and a list of target variables. There must the same
247 number of source and target variables. The target variables must not
250 @cmd{AUTORECODE} ordinarily assigns each increasing non-missing value
251 of a source variable (for a string, this is based on character code
252 comparisons) to consecutive values of its target variable. For
253 example, the smallest non-missing value of the source variable is
254 recoded to value 1, the next smallest to 2, and so on. If the source
255 variable has user-missing values, they are recoded to
256 consecutive values just above the non-missing values. For example, if
257 a source variables has seven distinct non-missing values, then the
258 smallest missing value would be recoded to 8, the next smallest to 9,
261 Use @subcmd{DESCENDING} to reverse the sort order for non-missing
262 values, so that the largest non-missing value is recoded to 1, the
263 second-largest to 2, and so on. Even with @subcmd{DESCENDING},
264 user-missing values are still recoded in ascending order just above
265 the non-missing values.
267 The system-missing value is always recoded into the system-missing
268 variable in target variables.
270 If a source value has a value label, then that value label is retained
271 for the new value in the target variable. Otherwise, the source value
272 itself becomes each new value's label.
274 Variable labels are copied from the source to target variables.
276 @subcmd{PRINT} is currently ignored.
278 The @subcmd{GROUP} subcommand is relevant only if more than one variable is to be
279 recoded. It causes a single mapping between source and target values to
280 be used, instead of one map per variable. With @subcmd{GROUP},
281 user-missing values are taken from the first source variable that has
282 any user-missing values.
284 If @subcmd{/BLANK=MISSING} is given, then string variables which contain only
285 whitespace are recoded as SYSMIS. If @subcmd{/BLANK=VALID} is given then they
286 will be allocated a value like any other. @subcmd{/BLANK} is not relevant
287 to numeric values. @subcmd{/BLANK=VALID} is the default.
289 @cmd{AUTORECODE} is a procedure. It causes the data to be read.
296 COMPUTE @var{variable} = @var{expression}.
300 COMPUTE vector(@var{index}) = @var{expression}.
303 @cmd{COMPUTE} assigns the value of an expression to a target
304 variable. For each case, the expression is evaluated and its value
305 assigned to the target variable. Numeric and string
306 variables may be assigned. When a string expression's width differs
307 from the target variable's width, the string result of the expression
308 is truncated or padded with spaces on the right as necessary. The
309 expression and variable types must match.
311 For numeric variables only, the target variable need not already
312 exist. Numeric variables created by @cmd{COMPUTE} are assigned an
313 @code{F8.2} output format. String variables must be declared before
314 they can be used as targets for @cmd{COMPUTE}.
316 The target variable may be specified as an element of a vector
317 (@pxref{VECTOR}). In this case, an expression @var{index} must be
318 specified in parentheses following the vector name. The expression @var{index}
319 must evaluate to a numeric value that, after rounding down
320 to the nearest integer, is a valid index for the named vector.
322 Using @cmd{COMPUTE} to assign to a variable specified on @cmd{LEAVE}
323 (@pxref{LEAVE}) resets the variable's left state. Therefore,
324 @code{LEAVE} should be specified following @cmd{COMPUTE}, not before.
326 @cmd{COMPUTE} is a transformation. It does not cause the active dataset to be
329 When @cmd{COMPUTE} is specified following @cmd{TEMPORARY}
330 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
338 COUNT @var{var_name} = @var{var}@dots{} (@var{value}@dots{})
339 [/@var{var_name} = @var{var}@dots{} (@var{value}@dots{})]@dots{}
341 Each @var{value} takes one of the following forms:
344 @var{num1} THRU @var{num2}
347 where @var{num1} is a numeric expression or the words @subcmd{LO} or @subcmd{LOWEST}
348 and @var{num2} is a numeric expression or @subcmd{HI} or @subcmd{HIGHEST}.
351 @cmd{COUNT} creates or replaces a numeric @dfn{target} variable that
352 counts the occurrence of a @dfn{criterion} value or set of values over
353 one or more @dfn{test} variables for each case.
355 The target variable values are always nonnegative integers. They are
356 never missing. The target variable is assigned an F8.2 output format.
357 @xref{Input and Output Formats}. Any variables, including
358 string variables, may be test variables.
360 User-missing values of test variables are treated just like any other
361 values. They are @strong{not} treated as system-missing values.
362 User-missing values that are criterion values or inside ranges of
363 criterion values are counted as any other values. However (for numeric
364 variables), keyword @subcmd{MISSING} may be used to refer to all system-
365 and user-missing values.
367 @cmd{COUNT} target variables are assigned values in the order
368 specified. In the command @subcmd{COUNT @var{A}=@var{A} @var{B}(1) /@var{B}=@var{A} @var{B}(2).}, the
369 following actions occur:
373 The number of occurrences of 1 between @var{A} and @var{B} is counted.
376 @var{A} is assigned this value.
379 The number of occurrences of 1 between @var{B} and the @strong{new}
380 value of @var{A} is counted.
383 @var{B} is assigned this value.
386 Despite this ordering, all @cmd{COUNT} criterion variables must exist
387 before the procedure is executed---they may not be created as target
388 variables earlier in the command! Break such a command into two
391 The examples below may help to clarify.
395 Assuming @code{Q0}, @code{Q2}, @dots{}, @code{Q9} are numeric variables,
396 the following commands:
400 Count the number of times the value 1 occurs through these variables
401 for each case and assigns the count to variable @code{QCOUNT}.
404 Print out the total number of times the value 1 occurs throughout
405 @emph{all} cases using @cmd{DESCRIPTIVES}. @xref{DESCRIPTIVES}, for
410 COUNT QCOUNT=Q0 TO Q9(1).
411 DESCRIPTIVES QCOUNT /STATISTICS=SUM.
415 Given these same variables, the following commands:
419 Count the number of valid values of these variables for each case and
420 assigns the count to variable @code{QVALID}.
423 Multiplies each value of @code{QVALID} by 10 to obtain a percentage of
424 valid values, using @cmd{COMPUTE}. @xref{COMPUTE}, for details.
427 Print out the percentage of valid values across all cases, using
428 @cmd{DESCRIPTIVES}. @xref{DESCRIPTIVES}, for details.
432 COUNT QVALID=Q0 TO Q9 (LO THRU HI).
433 COMPUTE QVALID=QVALID*10.
434 DESCRIPTIVES QVALID /STATISTICS=MEAN.
443 FLIP /VARIABLES=@var{var_list} /NEWNAMES=@var{var_name}.
446 @cmd{FLIP} transposes rows and columns in the active dataset. It
447 causes cases to be swapped with variables, and vice versa.
449 All variables in the transposed active dataset are numeric. String
450 variables take on the system-missing value in the transposed file.
452 @subcmd{N} subcommands are required. If specified, the @subcmd{VARIABLES} subcommand
453 selects variables to be transformed into cases, and variables not
454 specified are discarded. If the @subcmd{VARIABLES} subcommand is omitted, all
455 variables are selected for transposition.
457 The variables specified by @subcmd{NEWNAMES}, which must be a
459 used to give names to the variables created by @cmd{FLIP}. Only the
460 first 8 characters of the variable are used. If
461 @subcmd{NEWNAMES} is not
462 specified then the default is a variable named CASE_LBL, if it exists.
463 If it does not then the variables created by @cmd{FLIP} are named VAR000
464 through VAR999, then VAR1000, VAR1001, and so on.
466 When a @subcmd{NEWNAMES} variable is available, the names must be canonicalized
467 before becoming variable names. Invalid characters are replaced by
468 letter @samp{V} in the first position, or by @samp{_} in subsequent
469 positions. If the name thus generated is not unique, then numeric
470 extensions are added, starting with 1, until a unique name is found or
471 there are no remaining possibilities. If the latter occurs then the
472 @cmd{FLIP} operation aborts.
474 The resultant dictionary contains a CASE_LBL variable, a string
475 variable of width 8, which stores the names of the variables in the
476 dictionary before the transposition. Variables names longer than 8
477 characters are truncated. If the active dataset is subsequently
478 transposed using @cmd{FLIP}, this variable can be used to recreate the
479 original variable names.
481 @cmd{FLIP} honors @cmd{N OF CASES} (@pxref{N OF CASES}). It ignores
482 @cmd{TEMPORARY} (@pxref{TEMPORARY}), so that ``temporary''
483 transformations become permanent.
490 IF @var{condition} @var{variable}=@var{expression}.
494 IF @var{condition} vector(@var{index})=@var{expression}.
497 The @cmd{IF} transformation conditionally assigns the value of a target
498 expression to a target variable, based on the truth of a test
501 Specify a boolean-valued expression (@pxref{Expressions}) to be tested
502 following the @cmd{IF} keyword. This expression is evaluated for each case.
503 If the value is true, then the value of the expression is computed and
504 assigned to the specified variable. If the value is false or missing,
505 nothing is done. Numeric and string variables may be
506 assigned. When a string expression's width differs from the target
507 variable's width, the string result of the expression is truncated or
508 padded with spaces on the right as necessary. The expression and
509 variable types must match.
511 The target variable may be specified as an element of a vector
512 (@pxref{VECTOR}). In this case, a vector index expression must be
513 specified in parentheses following the vector name. The index
514 expression must evaluate to a numeric value that, after rounding down
515 to the nearest integer, is a valid index for the named vector.
517 Using @cmd{IF} to assign to a variable specified on @cmd{LEAVE}
518 (@pxref{LEAVE}) resets the variable's left state. Therefore,
519 @code{LEAVE} should be specified following @cmd{IF}, not before.
521 When @cmd{IF} is specified following @cmd{TEMPORARY}
522 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
529 The @cmd{RECODE} command is used to transform existing values into other,
530 user specified values.
534 RECODE @var{src_vars}
535 (@var{src_value} @var{src_value} @dots{} = @var{dest_value})
536 (@var{src_value} @var{src_value} @dots{} = @var{dest_value})
537 (@var{src_value} @var{src_value} @dots{} = @var{dest_value}) @dots{}
538 [INTO @var{dest_vars}].
541 Following the @cmd{RECODE} keyword itself comes @var{src_vars} which is a list
542 of variables whose values are to be transformed.
543 These variables may be string variables or they may be numeric.
544 However the list must be homogeneous; you may not mix string variables and
545 numeric variables in the same recoding.
547 After the list of source variables, there should be one or more @dfn{mappings}.
548 Each mapping is enclosed in parentheses, and contains the source values and
549 a destination value separated by a single @samp{=}.
550 The source values are used to specify the values in the dataset which
551 need to change, and the destination value specifies the new value
552 to which they should be changed.
553 Each @var{src_value} may take one of the following forms:
556 If the source variables are numeric then @var{src_value} may be a literal
559 If the source variables are string variables then @var{src_value} may be a
560 literal string (like all strings, enclosed in single or double quotes).
561 @item @var{num1} THRU @var{num2}
562 This form is valid only when the source variables are numeric.
563 It specifies all values in the range between @var{num1} and @var{num2},
564 including both endpoints of the range. By convention, @var{num1}
565 should be less than @var{num2}.
566 Open-ended ranges may be specified using @samp{LO} or @samp{LOWEST}
568 or @samp{HI} or @samp{HIGHEST} for @var{num2}.
570 The literal keyword @samp{MISSING} matches both system missing and user
572 It is valid for both numeric and string variables.
574 The literal keyword @samp{SYSMIS} matches system missing
576 It is valid for both numeric variables only.
578 The @samp{ELSE} keyword may be used to match any values which are
579 not matched by any other @var{src_value} appearing in the command.
580 If this keyword appears, it should be used in the last mapping of the
584 After the source variables comes an @samp{=} and then the @var{dest_value}.
585 The @var{dest_value} may take any of the following forms:
588 A literal numeric value to which the source values should be changed.
589 This implies the destination variable must be numeric.
591 A literal string value (enclosed in quotation marks) to which the source
592 values should be changed.
593 This implies the destination variable must be a string variable.
595 The keyword @samp{SYSMIS} changes the value to the system missing value.
596 This implies the destination variable must be numeric.
598 The special keyword @samp{COPY} means that the source value should not be
600 copied directly to the destination value.
601 This is meaningful only if @samp{INTO @var{dest_vars}} is specified.
604 Mappings are considered from left to right.
605 Therefore, if a value is matched by a @var{src_value} from more than
606 one mapping, the first (leftmost) mapping which matches will be considered.
607 Any subsequent matches will be ignored.
609 The clause @samp{INTO @var{dest_vars}} is optional.
610 The behaviour of the command is slightly different depending on whether it
613 If @samp{INTO @var{dest_vars}} does not appear, then values will be recoded
615 This means that the recoded values are written back to the
616 source variables from whence the original values came.
617 In this case, the @var{dest_value} for every mapping must imply a value which
618 has the same type as the @var{src_value}.
619 For example, if the source value is a string value, it is not permissible for
620 @var{dest_value} to be @samp{SYSMIS} or another forms which implies a numeric
622 It is also not permissible for @var{dest_value} to be longer than the width
623 of the source variable.
625 The following example two numeric variables @var{x} and @var{y} are recoded
627 Zero is recoded to 99, the values 1 to 10 inclusive are unchanged,
628 values 1000 and higher are recoded to the system-missing value and all other
629 values are changed to 999:
631 recode @var{x} @var{y}
634 (1000 THRU HIGHEST = SYSMIS)
638 If @samp{INTO @var{dest_vars}} is given, then recoded values are written
639 into the variables specified in @var{dest_vars}, which must therefore
640 contain a list of valid variable names.
641 The number of variables in @var{dest_vars} must be the same as the number
642 of variables in @var{src_vars}
643 and the respective order of the variables in @var{dest_vars} corresponds to
644 the order of @var{src_vars}.
645 That is to say, recoded values whose
646 original value came from the @var{n}th variable in @var{src_vars} will be
647 placed into the @var{n}th variable in @var{dest_vars}.
648 The source variables will be unchanged.
649 If any mapping implies a string as its destination value, then the respective
650 destination variable must already exist, or
651 have been declared using @cmd{STRING} or another transformation.
652 Numeric variables however will be automatically created if they don't already
654 The following example deals with two source variables, @var{a} and @var{b}
655 which contain string values. Hence there are two destination variables
656 @var{v1} and @var{v2}.
657 Any cases where @var{a} or @var{b} contain the values @samp{apple},
658 @samp{pear} or @samp{pomegranate} will result in @var{v1} or @var{v2} being
659 filled with the string @samp{fruit} whilst cases with
660 @samp{tomato}, @samp{lettuce} or @samp{carrot} will result in @samp{vegetable}.
661 Any other values will produce the result @samp{unknown}:
663 string @var{v1} (a20).
664 string @var{v2} (a20).
666 recode @var{a} @var{b}
667 ("apple" "pear" "pomegranate" = "fruit")
668 ("tomato" "lettuce" "carrot" = "vegetable")
670 into @var{v1} @var{v2}.
673 There is one very special mapping, not mentioned above.
674 If the source variable is a string variable
675 then a mapping may be specified as @samp{(CONVERT)}.
676 This mapping, if it appears must be the last mapping given and
677 the @samp{INTO @var{dest_vars}} clause must also be given and
678 must not refer to a string variable.
679 @samp{CONVERT} causes a number specified as a string to
680 be converted to a numeric value.
681 For example it will convert the string @samp{"3"} into the numeric
682 value 3 (note that it will not convert @samp{three} into 3).
683 If the string cannot be parsed as a number, then the system-missing value
685 In the following example, cases where the value of @var{x} (a string variable)
686 is the empty string, are recoded to 999 and all others are converted to the
687 numeric equivalent of the input value. The results are placed into the
688 numeric variable @var{y}:
696 It is possible to specify multiple recodings on a single command.
697 Introduce additional recodings with a slash (@samp{/}) to
698 separate them from the previous recodings:
701 @var{a} (2 = 22) (else = 99)
702 /@var{b} (1 = 3) into @var{z}
705 @noindent Here we have two recodings. The first affects the source variable
706 @var{a} and recodes in-place the value 2 into 22 and all other values to 99.
707 The second recoding copies the values of @var{b} into the variable @var{z},
708 changing any instances of 1 into 3.
715 SORT CASES BY @var{var_list}[(@{D|A@}] [ @var{var_list}[(@{D|A@}] ] ...
718 @cmd{SORT CASES} sorts the active dataset by the values of one or more
721 Specify @subcmd{BY} and a list of variables to sort by. By default, variables
722 are sorted in ascending order. To override sort order, specify @subcmd{(D)} or
723 @subcmd{(DOWN)} after a list of variables to get descending order, or @subcmd{(A)} or @subcmd{(UP)}
724 for ascending order. These apply to all the listed variables
725 up until the preceding @subcmd{(A)}, @subcmd{(D)}, @subcmd{(UP)} or @subcmd{(DOWN)}.
727 The sort algorithms used by @cmd{SORT CASES} are stable. That is,
728 records that have equal values of the sort variables will have the
729 same relative order before and after sorting. As a special case,
730 re-sorting an already sorted file will not affect the ordering of
733 @cmd{SORT CASES} is a procedure. It causes the data to be read.
735 @cmd{SORT CASES} attempts to sort the entire active dataset in main memory.
736 If workspace is exhausted, it falls back to a merge sort algorithm that
737 involves creates numerous temporary files.
739 @cmd{SORT CASES} may not be specified following @cmd{TEMPORARY}.