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.
291 @subsection Autorecode Example
293 In the file @file{personnel.sav}, the variable @exvar{occupation} is a string
294 variable. Except for data of a purely commentary nature, string variables
295 are generally a bad idea. One reason is that data entry errors are easily
296 overlooked. This has happened in @file{personnel.sav}; one entry which should
297 read ``Scientist'' has been mistyped as ``Scrientist''. In @ref{autorecode:ex}
298 first, this error will be corrected,
299 @footnote{One must use care when correcting such data input errors rather than
300 msimply marking them as missing. For example, if an occupation has been entered
301 ``Barister'', did the person mean ``Barrister'' or did she mean ``Barista''?}
302 then we will use @cmd{AUTORECODE} to
303 create a new numeric variable which takes recoded values of @exvar{occupation}.
304 Finally, we will remove the old variable and rename the new variable to
305 the name of the old variable.
307 @float Example, autorecode:ex
308 @psppsyntax {autorecode.sps}
309 @caption {Changing a string variable to a numeric variable using @cmd{AUTORECODE}
310 after correcting a data entry error}
314 Notice in @ref{autorecode:res}, how the new variable has been automatically
315 allocated value labels which correspond to the strings of the old variable.
316 This means that in future analyses the descriptive strings are reported instead
317 of the numeric values.
319 @float Result, autorecode:res
320 @psppoutput {autorecode}
321 @caption {The properties of the @exvar{occupation} variable following @cmd{AUTORECODE}}
330 COMPUTE @var{variable} = @var{expression}.
334 COMPUTE vector(@var{index}) = @var{expression}.
337 @cmd{COMPUTE} assigns the value of an expression to a target
338 variable. For each case, the expression is evaluated and its value
339 assigned to the target variable. Numeric and string
340 variables may be assigned. When a string expression's width differs
341 from the target variable's width, the string result of the expression
342 is truncated or padded with spaces on the right as necessary. The
343 expression and variable types must match.
345 For numeric variables only, the target variable need not already
346 exist. Numeric variables created by @cmd{COMPUTE} are assigned an
347 @code{F8.2} output format. String variables must be declared before
348 they can be used as targets for @cmd{COMPUTE}.
350 The target variable may be specified as an element of a vector
351 (@pxref{VECTOR}). In this case, an expression @var{index} must be
352 specified in parentheses following the vector name. The expression @var{index}
353 must evaluate to a numeric value that, after rounding down
354 to the nearest integer, is a valid index for the named vector.
356 Using @cmd{COMPUTE} to assign to a variable specified on @cmd{LEAVE}
357 (@pxref{LEAVE}) resets the variable's left state. Therefore,
358 @code{LEAVE} should be specified following @cmd{COMPUTE}, not before.
360 @cmd{COMPUTE} is a transformation. It does not cause the active dataset to be
363 When @cmd{COMPUTE} is specified following @cmd{TEMPORARY}
364 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
367 @subsection Compute Examples
369 The dataset @file{physiology.sav} contains the height and weight of persons.
370 For some purposes, neither height nor weight alone is of interest.
371 Epidemiologists are often more interested in the @dfn{body mass index} which
372 can sometimes be used as a predictor for clinical conditions.
373 The body mass index is defined as the weight of the person in kg divided
374 by the square of the person's height in metres.
375 @footnote{Since BMI is a quantity with a ratio scale and has units, the term ``index''
376 is a misnomer, but that is what it is called.}
378 @float Example, bmi:ex
379 @psppsyntax {compute.sps}
380 @caption {Computing the body mass index from @exvar{weight} and @exvar{height}}
383 @ref{bmi:ex} shows how you can use @cmd{COMPUTE} to generate a new variable called
384 @exvar{bmi} and have every case's value calculated from the existing values of
385 @exvar{weight} and @exvar{height}.
386 It also shows how you can add a label to this new variable (@pxref{VARIABLE LABELS}),
387 so that a more descriptive label appears in subsequent analyses, and this can be seen
388 in the ouput from the @cmd{DESCRIPTIVES} command in @ref{bmi:res}.
390 The expression which follows the @samp{=} sign can be as complicated as necessary.
391 @xref{Expressions} for a precise description of the language accepted.
393 @float Results, bmi:res
394 @psppoutput {compute}
395 @caption {An analysis which includes @exvar{bmi} in its results}
405 COUNT @var{var_name} = @var{var}@dots{} (@var{value}@dots{})
406 [/@var{var_name} = @var{var}@dots{} (@var{value}@dots{})]@dots{}
408 Each @var{value} takes one of the following forms:
411 @var{num1} THRU @var{num2}
414 where @var{num1} is a numeric expression or the words @subcmd{LO} or @subcmd{LOWEST}
415 and @var{num2} is a numeric expression or @subcmd{HI} or @subcmd{HIGHEST}.
418 @cmd{COUNT} creates or replaces a numeric @dfn{target} variable that
419 counts the occurrence of a @dfn{criterion} value or set of values over
420 one or more @dfn{test} variables for each case.
422 The target variable values are always nonnegative integers. They are
423 never missing. The target variable is assigned an F8.2 output format.
424 @xref{Input and Output Formats}. Any variables, including
425 string variables, may be test variables.
427 User-missing values of test variables are treated just like any other
428 values. They are @strong{not} treated as system-missing values.
429 User-missing values that are criterion values or inside ranges of
430 criterion values are counted as any other values. However (for numeric
431 variables), keyword @subcmd{MISSING} may be used to refer to all system-
432 and user-missing values.
434 @cmd{COUNT} target variables are assigned values in the order
435 specified. In the command @subcmd{COUNT @var{A}=@var{A} @var{B}(1) /@var{B}=@var{A} @var{B}(2).}, the
436 following actions occur:
440 The number of occurrences of 1 between @var{A} and @var{B} is counted.
443 @var{A} is assigned this value.
446 The number of occurrences of 1 between @var{B} and the @strong{new}
447 value of @var{A} is counted.
450 @var{B} is assigned this value.
453 Despite this ordering, all @cmd{COUNT} criterion variables must exist
454 before the procedure is executed---they may not be created as target
455 variables earlier in the command! Break such a command into two
458 @subsection Count Examples
460 In the survey results in dataset @file{hotel.sav} a manager wishes
461 to know how many respondents answered with low valued answers to questions
462 @exvar{v1}, @exvar{v2} and @exvar{v3}. This can be found using the code
463 in @ref{count:ex}. Specifically, this code creates a new variable, and
464 populates it with the number of values in @exvar{v1}--@exvar{v2} which
467 @float Example, count:ex
468 @psppsyntax {count.sps}
469 @caption {Counting low values to responses @exvar{v1}, @exvar{v2} and @exvar{v3}}
472 In @ref{count:ex} the @cmd{COUNT} transformation creates a new variable, @exvar{low_counts} and
473 its values are shown using the @cmd{LIST} command.
475 In @ref{count:res} we can see the values of @exvar{low_counts} after the @cmd{COUNT}
476 transformation has completed. The first value is 1, because there is only one
477 variable amoung @exvar{v1}, @exvar{v2} and @exvar{3} which has a value of 2 or less.
478 The second value is 2, because both @exvar{v1} and @exvar{v2} are 2 or less.
480 @float Result, count:res
482 @caption {The values of @exvar{v1}, @exvar{v2}, @exvar{v3} and @exvar{low_counts} after
483 the @cmd{COUNT} transformation has run}
492 FLIP /VARIABLES=@var{var_list} /NEWNAMES=@var{var_name}.
495 @cmd{FLIP} transposes rows and columns in the active dataset. It
496 causes cases to be swapped with variables, and vice versa.
498 All variables in the transposed active dataset are numeric. String
499 variables take on the system-missing value in the transposed file.
501 @subcmd{N} subcommands are required. If specified, the @subcmd{VARIABLES} subcommand
502 selects variables to be transformed into cases, and variables not
503 specified are discarded. If the @subcmd{VARIABLES} subcommand is omitted, all
504 variables are selected for transposition.
506 The variables specified by @subcmd{NEWNAMES}, which must be a
508 used to give names to the variables created by @cmd{FLIP}. Only the
509 first 8 characters of the variable are used. If
510 @subcmd{NEWNAMES} is not
511 specified then the default is a variable named @exvar{CASE_LBL}, if it exists.
512 If it does not then the variables created by @cmd{FLIP} are named VAR000
513 through VAR999, then VAR1000, VAR1001, and so on.
515 When a @subcmd{NEWNAMES} variable is available, the names must be canonicalized
516 before becoming variable names. Invalid characters are replaced by
517 letter @samp{V} in the first position, or by @samp{_} in subsequent
518 positions. If the name thus generated is not unique, then numeric
519 extensions are added, starting with 1, until a unique name is found or
520 there are no remaining possibilities. If the latter occurs then the
521 @cmd{FLIP} operation aborts.
523 The resultant dictionary contains a @exvar{CASE_LBL} variable, a string
524 variable of width 8, which stores the names of the variables in the
525 dictionary before the transposition. Variables names longer than 8
526 characters are truncated. If @cmd{FLIP} is called again on
527 this dataset, the @exvar{CASE_LBL} variable can be passed to the @subcmd{NEWNAMES}
528 subcommand to recreate the original variable names.
530 @cmd{FLIP} honors @cmd{N OF CASES} (@pxref{N OF CASES}). It ignores
531 @cmd{TEMPORARY} (@pxref{TEMPORARY}), so that ``temporary''
532 transformations become permanent.
534 @subsection Flip Examples
537 In @ref{flip:ex}, data has been entered using @cmd{DATA LIST} (@pxref{DATA LIST})
538 such that the first variable in the dataset is a string variable containing
539 a description of the other data for the case.
540 Clearly this is not a convenient arrangement for performing statistical analyses,
541 so it would have been better to think a little more carefully about how the data
542 should have been arranged.
543 However often the data is provided by some third party source, and you have
544 no control over the form.
545 Fortunately, we can use @cmd{FLIP} to exchange the variables
546 and cases in the active dataset.
548 @float Example, flip:ex
549 @psppsyntax {flip.sps}
550 @caption {Using @cmd{FLIP} to exchange variables and cases in a dataset}
553 As you can see in @ref{flip:res} before the @cmd{FLIP} command has run there
554 are seven variables (six containing data and one for the heading) and three cases.
555 Afterwards there are four variables (one per case, plus the @exvar{CASE_LBL} variable)
557 You can delete the @exvar{CASE_LBL} variable (@pxref{DELETE VARIABLES}) if you don't need it.
559 @float Results, flip:res
561 @caption {The results of using @cmd{FLIP} to exchange variables and cases in a dataset}
570 IF @var{condition} @var{variable}=@var{expression}.
574 IF @var{condition} vector(@var{index})=@var{expression}.
577 The @cmd{IF} transformation conditionally assigns the value of a target
578 expression to a target variable, based on the truth of a test
581 Specify a boolean-valued expression (@pxref{Expressions}) to be tested
582 following the @cmd{IF} keyword. This expression is evaluated for each case.
583 If the value is true, then the value of the expression is computed and
584 assigned to the specified variable. If the value is false or missing,
585 nothing is done. Numeric and string variables may be
586 assigned. When a string expression's width differs from the target
587 variable's width, the string result of the expression is truncated or
588 padded with spaces on the right as necessary. The expression and
589 variable types must match.
591 The target variable may be specified as an element of a vector
592 (@pxref{VECTOR}). In this case, a vector index expression must be
593 specified in parentheses following the vector name. The index
594 expression must evaluate to a numeric value that, after rounding down
595 to the nearest integer, is a valid index for the named vector.
597 Using @cmd{IF} to assign to a variable specified on @cmd{LEAVE}
598 (@pxref{LEAVE}) resets the variable's left state. Therefore,
599 @code{LEAVE} should be specified following @cmd{IF}, not before.
601 When @cmd{IF} is specified following @cmd{TEMPORARY}
602 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
609 The @cmd{RECODE} command is used to transform existing values into other,
610 user specified values.
614 RECODE @var{src_vars}
615 (@var{src_value} @var{src_value} @dots{} = @var{dest_value})
616 (@var{src_value} @var{src_value} @dots{} = @var{dest_value})
617 (@var{src_value} @var{src_value} @dots{} = @var{dest_value}) @dots{}
618 [INTO @var{dest_vars}].
621 Following the @cmd{RECODE} keyword itself comes @var{src_vars} which is a list
622 of variables whose values are to be transformed.
623 These variables may be string variables or they may be numeric.
624 However the list must be homogeneous; you may not mix string variables and
625 numeric variables in the same recoding.
627 After the list of source variables, there should be one or more @dfn{mappings}.
628 Each mapping is enclosed in parentheses, and contains the source values and
629 a destination value separated by a single @samp{=}.
630 The source values are used to specify the values in the dataset which
631 need to change, and the destination value specifies the new value
632 to which they should be changed.
633 Each @var{src_value} may take one of the following forms:
636 If the source variables are numeric then @var{src_value} may be a literal
639 If the source variables are string variables then @var{src_value} may be a
640 literal string (like all strings, enclosed in single or double quotes).
641 @item @var{num1} THRU @var{num2}
642 This form is valid only when the source variables are numeric.
643 It specifies all values in the range between @var{num1} and @var{num2},
644 including both endpoints of the range. By convention, @var{num1}
645 should be less than @var{num2}.
646 Open-ended ranges may be specified using @samp{LO} or @samp{LOWEST}
648 or @samp{HI} or @samp{HIGHEST} for @var{num2}.
650 The literal keyword @samp{MISSING} matches both system missing and user
652 It is valid for both numeric and string variables.
654 The literal keyword @samp{SYSMIS} matches system missing
656 It is valid for both numeric variables only.
658 The @samp{ELSE} keyword may be used to match any values which are
659 not matched by any other @var{src_value} appearing in the command.
660 If this keyword appears, it should be used in the last mapping of the
664 After the source variables comes an @samp{=} and then the @var{dest_value}.
665 The @var{dest_value} may take any of the following forms:
668 A literal numeric value to which the source values should be changed.
669 This implies the destination variable must be numeric.
671 A literal string value (enclosed in quotation marks) to which the source
672 values should be changed.
673 This implies the destination variable must be a string variable.
675 The keyword @samp{SYSMIS} changes the value to the system missing value.
676 This implies the destination variable must be numeric.
678 The special keyword @samp{COPY} means that the source value should not be
680 copied directly to the destination value.
681 This is meaningful only if @samp{INTO @var{dest_vars}} is specified.
684 Mappings are considered from left to right.
685 Therefore, if a value is matched by a @var{src_value} from more than
686 one mapping, the first (leftmost) mapping which matches will be considered.
687 Any subsequent matches will be ignored.
689 The clause @samp{INTO @var{dest_vars}} is optional.
690 The behaviour of the command is slightly different depending on whether it
693 If @samp{INTO @var{dest_vars}} does not appear, then values will be recoded
695 This means that the recoded values are written back to the
696 source variables from whence the original values came.
697 In this case, the @var{dest_value} for every mapping must imply a value which
698 has the same type as the @var{src_value}.
699 For example, if the source value is a string value, it is not permissible for
700 @var{dest_value} to be @samp{SYSMIS} or another forms which implies a numeric
702 It is also not permissible for @var{dest_value} to be longer than the width
703 of the source variable.
705 The following example two numeric variables @var{x} and @var{y} are recoded
707 Zero is recoded to 99, the values 1 to 10 inclusive are unchanged,
708 values 1000 and higher are recoded to the system-missing value and all other
709 values are changed to 999:
711 recode @var{x} @var{y}
714 (1000 THRU HIGHEST = SYSMIS)
718 If @samp{INTO @var{dest_vars}} is given, then recoded values are written
719 into the variables specified in @var{dest_vars}, which must therefore
720 contain a list of valid variable names.
721 The number of variables in @var{dest_vars} must be the same as the number
722 of variables in @var{src_vars}
723 and the respective order of the variables in @var{dest_vars} corresponds to
724 the order of @var{src_vars}.
725 That is to say, recoded values whose
726 original value came from the @var{n}th variable in @var{src_vars} will be
727 placed into the @var{n}th variable in @var{dest_vars}.
728 The source variables will be unchanged.
729 If any mapping implies a string as its destination value, then the respective
730 destination variable must already exist, or
731 have been declared using @cmd{STRING} or another transformation.
732 Numeric variables however will be automatically created if they don't already
734 The following example deals with two source variables, @var{a} and @var{b}
735 which contain string values. Hence there are two destination variables
736 @var{v1} and @var{v2}.
737 Any cases where @var{a} or @var{b} contain the values @samp{apple},
738 @samp{pear} or @samp{pomegranate} will result in @var{v1} or @var{v2} being
739 filled with the string @samp{fruit} whilst cases with
740 @samp{tomato}, @samp{lettuce} or @samp{carrot} will result in @samp{vegetable}.
741 Any other values will produce the result @samp{unknown}:
743 string @var{v1} (a20).
744 string @var{v2} (a20).
746 recode @var{a} @var{b}
747 ("apple" "pear" "pomegranate" = "fruit")
748 ("tomato" "lettuce" "carrot" = "vegetable")
750 into @var{v1} @var{v2}.
753 There is one very special mapping, not mentioned above.
754 If the source variable is a string variable
755 then a mapping may be specified as @samp{(CONVERT)}.
756 This mapping, if it appears must be the last mapping given and
757 the @samp{INTO @var{dest_vars}} clause must also be given and
758 must not refer to a string variable.
759 @samp{CONVERT} causes a number specified as a string to
760 be converted to a numeric value.
761 For example it will convert the string @samp{"3"} into the numeric
762 value 3 (note that it will not convert @samp{three} into 3).
763 If the string cannot be parsed as a number, then the system-missing value
765 In the following example, cases where the value of @var{x} (a string variable)
766 is the empty string, are recoded to 999 and all others are converted to the
767 numeric equivalent of the input value. The results are placed into the
768 numeric variable @var{y}:
776 It is possible to specify multiple recodings on a single command.
777 Introduce additional recodings with a slash (@samp{/}) to
778 separate them from the previous recodings:
781 @var{a} (2 = 22) (else = 99)
782 /@var{b} (1 = 3) into @var{z}
785 @noindent Here we have two recodings. The first affects the source variable
786 @var{a} and recodes in-place the value 2 into 22 and all other values to 99.
787 The second recoding copies the values of @var{b} into the variable @var{z},
788 changing any instances of 1 into 3.
795 SORT CASES BY @var{var_list}[(@{D|A@}] [ @var{var_list}[(@{D|A@}] ] ...
798 @cmd{SORT CASES} sorts the active dataset by the values of one or more
801 Specify @subcmd{BY} and a list of variables to sort by. By default, variables
802 are sorted in ascending order. To override sort order, specify @subcmd{(D)} or
803 @subcmd{(DOWN)} after a list of variables to get descending order, or @subcmd{(A)}
805 for ascending order. These apply to all the listed variables
806 up until the preceding @subcmd{(A)}, @subcmd{(D)}, @subcmd{(UP)} or @subcmd{(DOWN)}.
808 The sort algorithms used by @cmd{SORT CASES} are stable. That is,
809 records that have equal values of the sort variables will have the
810 same relative order before and after sorting. As a special case,
811 re-sorting an already sorted file will not affect the ordering of
814 @cmd{SORT CASES} is a procedure. It causes the data to be read.
816 @cmd{SORT CASES} attempts to sort the entire active dataset in main memory.
817 If workspace is exhausted, it falls back to a merge sort algorithm that
818 involves creates numerous temporary files.
820 @cmd{SORT CASES} may not be specified following @cmd{TEMPORARY}.
822 @subsection Sorting Example