1 @c PSPP - a program for statistical analysis.
2 @c Copyright (C) 2017, 2020 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 contains as many cases as there are
62 unique combinations of the break variables.
63 In @subcmd{ADDVARIABLES} mode, the destination variables are appended to
64 the existing active dataset.
65 Cases which have identical combinations of values in their break
66 variables, receive identical values for the destination variables.
67 The number of cases in the active dataset remains 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 is 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 does
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.
137 the first case with particular values for the break variables before
138 sorting is also the first case in that break group after sorting.
140 @item @subcmd{FOUT(@var{var_name}, @var{low}, @var{high})}
141 Fraction of values strictly outside the specified range of constants.
142 The default format is F5.3.
144 @item @subcmd{LAST(@var{var_name})}
145 Last non-missing value in break group. The aggregation variable
146 receives the complete dictionary information from the source variable.
147 The sort performed by @cmd{AGGREGATE} (and by @cmd{SORT CASES}) is stable.
149 @item @subcmd{MAX(@var{var_name})}
150 Maximum value. The aggregation variable receives the complete
151 dictionary information from the source variable.
153 @item @subcmd{MEAN(@var{var_name})}
154 Arithmetic mean. Limited to numeric values. The default format is
157 @item @subcmd{MEDIAN(@var{var_name})}
158 The median value. Limited to numeric values. The default format is F8.2.
160 @item @subcmd{MIN(@var{var_name})}
161 Minimum value. The aggregation variable receives the complete
162 dictionary information from the source variable.
164 @item @subcmd{N(@var{var_name})}
165 Number of non-missing values. The default format is F7.0 if weighting
166 is not enabled, F8.2 if it is (@pxref{WEIGHT}).
169 Number of cases aggregated to form this group. The default format is
170 F7.0 if weighting is not enabled, F8.2 if it is (@pxref{WEIGHT}).
172 @item @subcmd{NMISS(@var{var_name})}
173 Number of missing values. The default format is F7.0 if weighting is
174 not enabled, F8.2 if it is (@pxref{WEIGHT}).
176 @item @subcmd{NU(@var{var_name})}
177 Number of non-missing values. Each case is considered to have a weight
178 of 1, regardless of the current weighting variable (@pxref{WEIGHT}).
179 The default format is F7.0.
182 Number of cases aggregated to form this group. Each case is considered
183 to have a weight of 1, regardless of the current weighting variable.
184 The default format is F7.0.
186 @item @subcmd{NUMISS(@var{var_name})}
187 Number of missing values. Each case is considered to have a weight of
188 1, regardless of the current weighting variable. The default format is F7.0.
190 @item @subcmd{PGT(@var{var_name}, @var{value})}
191 Percentage between 0 and 100 of values greater than the specified
192 constant. The default format is F5.1.
194 @item @subcmd{PIN(@var{var_name}, @var{low}, @var{high})}
195 Percentage of values within the specified inclusive range of
196 constants. The default format is F5.1.
198 @item @subcmd{PLT(@var{var_name}, @var{value})}
199 Percentage of values less than the specified constant. The default
202 @item @subcmd{POUT(@var{var_name}, @var{low}, @var{high})}
203 Percentage of values strictly outside the specified range of
204 constants. The default format is F5.1.
206 @item @subcmd{SD(@var{var_name})}
207 Standard deviation of the mean. Limited to numeric values. The
208 default format is F8.2.
210 @item @subcmd{SUM(@var{var_name})}
211 Sum. Limited to numeric values. The default format is F8.2.
214 Aggregation functions compare string values in terms of internal
216 On most modern computers, this is @acronym{ASCII} or a superset thereof.
218 The aggregation functions listed above exclude all user-missing values
219 from calculations. To include user-missing values, insert a period
220 (@samp{.}) at the end of the function name. (@i{e.g.}@: @samp{SUM.}).
221 (Be aware that specifying such a function as the last token on a line
222 causes the period to be interpreted as the end of the command.)
224 @cmd{AGGREGATE} both ignores and cancels the current @cmd{SPLIT FILE}
225 settings (@pxref{SPLIT FILE}).
232 AUTORECODE VARIABLES=@var{src_vars} INTO @var{dest_vars}
236 [ /BLANK = @{VALID, MISSING@} ]
239 The @cmd{AUTORECODE} procedure considers the @var{n} values that a variable
240 takes on and maps them onto values 1@dots{}@var{n} on a new numeric
243 Subcommand @subcmd{VARIABLES} is the only required subcommand and must come
244 first. Specify @subcmd{VARIABLES}, an equals sign (@samp{=}), a list of source
245 variables, @subcmd{INTO}, and a list of target variables. There must the same
246 number of source and target variables. The target variables must not
249 @cmd{AUTORECODE} ordinarily assigns each increasing non-missing value
250 of a source variable (for a string, this is based on character code
251 comparisons) to consecutive values of its target variable. For
252 example, the smallest non-missing value of the source variable is
253 recoded to value 1, the next smallest to 2, and so on. If the source
254 variable has user-missing values, they are recoded to
255 consecutive values just above the non-missing values. For example, if
256 a source variables has seven distinct non-missing values, then the
257 smallest missing value would be recoded to 8, the next smallest to 9,
260 Use @subcmd{DESCENDING} to reverse the sort order for non-missing
261 values, so that the largest non-missing value is recoded to 1, the
262 second-largest to 2, and so on. Even with @subcmd{DESCENDING},
263 user-missing values are still recoded in ascending order just above
264 the non-missing values.
266 The system-missing value is always recoded into the system-missing
267 variable in target variables.
269 If a source value has a value label, then that value label is retained
270 for the new value in the target variable. Otherwise, the source value
271 itself becomes each new value's label.
273 Variable labels are copied from the source to target variables.
275 @subcmd{PRINT} is currently ignored.
277 The @subcmd{GROUP} subcommand is relevant only if more than one variable is to be
278 recoded. It causes a single mapping between source and target values to
279 be used, instead of one map per variable. With @subcmd{GROUP},
280 user-missing values are taken from the first source variable that has
281 any user-missing values.
283 If @subcmd{/BLANK=MISSING} is given, then string variables which contain only
284 whitespace are recoded as SYSMIS. If @subcmd{/BLANK=VALID} is specified then they
285 are allocated a value like any other. @subcmd{/BLANK} is not relevant
286 to numeric values. @subcmd{/BLANK=VALID} is the default.
288 @cmd{AUTORECODE} is a procedure. It causes the data to be read.
290 @subsection Autorecode Example
292 In the file @file{personnel.sav}, the variable @exvar{occupation} is a string
293 variable. Except for data of a purely commentary nature, string variables
294 are generally a bad idea. One reason is that data entry errors are easily
295 overlooked. This has happened in @file{personnel.sav}; one entry which should
296 read ``Scientist'' has been mistyped as ``Scrientist''. In @ref{autorecode:ex}
297 first, this error is corrected by the @cmd{DO IF} clause,
298 @footnote{One must use care when correcting such data input errors rather than
299 msimply marking them as missing. For example, if an occupation has been entered
300 ``Barister'', did the person mean ``Barrister'' or did she mean ``Barista''?}
301 then we use @cmd{AUTORECODE} to
302 create a new numeric variable which takes recoded values of @exvar{occupation}.
303 Finally, we remove the old variable and rename the new variable to
304 the name of the old variable.
306 @float Example, autorecode:ex
307 @psppsyntax {autorecode.sps}
308 @caption {Changing a string variable to a numeric variable using @cmd{AUTORECODE}
309 after correcting a data entry error}
313 Notice in @ref{autorecode:res}, how the new variable has been automatically
314 allocated value labels which correspond to the strings of the old variable.
315 This means that in future analyses the descriptive strings are reported instead
316 of the numeric values.
318 @float Result, autorecode:res
319 @psppoutput {autorecode}
320 @caption {The properties of the @exvar{occupation} variable following @cmd{AUTORECODE}}
329 COMPUTE @var{variable} = @var{expression}.
333 COMPUTE vector(@var{index}) = @var{expression}.
336 @cmd{COMPUTE} assigns the value of an expression to a target
337 variable. For each case, the expression is evaluated and its value
338 assigned to the target variable. Numeric and string
339 variables may be assigned. When a string expression's width differs
340 from the target variable's width, the string result of the expression
341 is truncated or padded with spaces on the right as necessary. The
342 expression and variable types must match.
344 For numeric variables only, the target variable need not already
345 exist. Numeric variables created by @cmd{COMPUTE} are assigned an
346 @code{F8.2} output format. String variables must be declared before
347 they can be used as targets for @cmd{COMPUTE}.
349 The target variable may be specified as an element of a vector
350 (@pxref{VECTOR}). In this case, an expression @var{index} must be
351 specified in parentheses following the vector name. The expression @var{index}
352 must evaluate to a numeric value that, after rounding down
353 to the nearest integer, is a valid index for the named vector.
355 Using @cmd{COMPUTE} to assign to a variable specified on @cmd{LEAVE}
356 (@pxref{LEAVE}) resets the variable's left state. Therefore,
357 @code{LEAVE} should be specified following @cmd{COMPUTE}, not before.
359 @cmd{COMPUTE} is a transformation. It does not cause the active dataset to be
362 When @cmd{COMPUTE} is specified following @cmd{TEMPORARY}
363 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
366 @subsection Compute Examples
368 The dataset @file{physiology.sav} contains the height and weight of persons.
369 For some purposes, neither height nor weight alone is of interest.
370 Epidemiologists are often more interested in the @dfn{body mass index} which
371 can sometimes be used as a predictor for clinical conditions.
372 The body mass index is defined as the weight of the person in kilograms divided
373 by the square of the person's height in metres.
374 @footnote{Since BMI is a quantity with a ratio scale and has units, the term ``index''
375 is a misnomer, but that is what it is called.}
377 @float Example, bmi:ex
378 @psppsyntax {compute.sps}
379 @caption {Computing the body mass index from @exvar{weight} and @exvar{height}}
382 @ref{bmi:ex} shows how you can use @cmd{COMPUTE} to generate a new variable called
383 @exvar{bmi} and have every case's value calculated from the existing values of
384 @exvar{weight} and @exvar{height}.
385 It also shows how you can add a label to this new variable (@pxref{VARIABLE LABELS}),
386 so that a more descriptive label appears in subsequent analyses, and this can be seen
387 in the ouput from the @cmd{DESCRIPTIVES} command in @ref{bmi:res}.
389 The expression which follows the @samp{=} sign can be as complicated as necessary.
390 @xref{Expressions} for a precise description of the language accepted.
392 @float Results, bmi:res
393 @psppoutput {compute}
394 @caption {An analysis which includes @exvar{bmi} in its results}
404 COUNT @var{var_name} = @var{var}@dots{} (@var{value}@dots{})
405 [/@var{var_name} = @var{var}@dots{} (@var{value}@dots{})]@dots{}
407 Each @var{value} takes one of the following forms:
410 @var{num1} THRU @var{num2}
413 where @var{num1} is a numeric expression or the words @subcmd{LO} or @subcmd{LOWEST}
414 and @var{num2} is a numeric expression or @subcmd{HI} or @subcmd{HIGHEST}.
417 @cmd{COUNT} creates or replaces a numeric @dfn{target} variable that
418 counts the occurrence of a @dfn{criterion} value or set of values over
419 one or more @dfn{test} variables for each case.
421 The target variable values are always nonnegative integers. They are
422 never missing. The target variable is assigned an F8.2 output format.
423 @xref{Input and Output Formats}. Any variables, including
424 string variables, may be test variables.
426 User-missing values of test variables are treated just like any other
427 values. They are @strong{not} treated as system-missing values.
428 User-missing values that are criterion values or inside ranges of
429 criterion values are counted as any other values. However (for numeric
430 variables), keyword @subcmd{MISSING} may be used to refer to all system-
431 and user-missing values.
433 @cmd{COUNT} target variables are assigned values in the order
434 specified. In the command @subcmd{COUNT @var{A}=@var{A} @var{B}(1) /@var{B}=@var{A} @var{B}(2).}, the
435 following actions occur:
439 The number of occurrences of 1 between @var{A} and @var{B} is counted.
442 @var{A} is assigned this value.
445 The number of occurrences of 1 between @var{B} and the @strong{new}
446 value of @var{A} is counted.
449 @var{B} is assigned this value.
452 Despite this ordering, all @cmd{COUNT} criterion variables must exist
453 before the procedure is executed---they may not be created as target
454 variables earlier in the command! Break such a command into two
457 @subsection Count Examples
459 In the survey results in dataset @file{hotel.sav} a manager wishes
460 to know how many respondents answered with low valued answers to questions
461 @exvar{v1}, @exvar{v2} and @exvar{v3}. This can be found using the code
462 in @ref{count:ex}. Specifically, this code creates a new variable, and
463 populates it with the number of values in @exvar{v1}--@exvar{v2} which
466 @float Example, count:ex
467 @psppsyntax {count.sps}
468 @caption {Counting low values to responses @exvar{v1}, @exvar{v2} and @exvar{v3}}
471 In @ref{count:ex} the @cmd{COUNT} transformation creates a new variable, @exvar{low_counts} and
472 its values are shown using the @cmd{LIST} command.
474 In @ref{count:res} we can see the values of @exvar{low_counts} after the @cmd{COUNT}
475 transformation has completed. The first value is 1, because there is only one
476 variable amoung @exvar{v1}, @exvar{v2} and @exvar{3} which has a value of 2 or less.
477 The second value is 2, because both @exvar{v1} and @exvar{v2} are 2 or less.
479 @float Result, count:res
481 @caption {The values of @exvar{v1}, @exvar{v2}, @exvar{v3} and @exvar{low_counts} after
482 the @cmd{COUNT} transformation has run}
491 FLIP /VARIABLES=@var{var_list} /NEWNAMES=@var{var_name}.
494 @cmd{FLIP} transposes rows and columns in the active dataset. It
495 causes cases to be swapped with variables, and vice versa.
497 All variables in the transposed active dataset are numeric. String
498 variables take on the system-missing value in the transposed file.
500 @subcmd{N} subcommands are required. If specified, the @subcmd{VARIABLES} subcommand
501 selects variables to be transformed into cases, and variables not
502 specified are discarded. If the @subcmd{VARIABLES} subcommand is omitted, all
503 variables are selected for transposition.
505 The variables specified by @subcmd{NEWNAMES}, which must be a
507 used to give names to the variables created by @cmd{FLIP}. Only the
508 first 8 characters of the variable are used. If
509 @subcmd{NEWNAMES} is not
510 specified then the default is a variable named @exvar{CASE_LBL}, if it exists.
511 If it does not then the variables created by @cmd{FLIP} are named VAR000
512 through VAR999, then VAR1000, VAR1001, and so on.
514 When a @subcmd{NEWNAMES} variable is available, the names must be canonicalized
515 before becoming variable names. Invalid characters are replaced by
516 letter @samp{V} in the first position, or by @samp{_} in subsequent
517 positions. If the name thus generated is not unique, then numeric
518 extensions are added, starting with 1, until a unique name is found or
519 there are no remaining possibilities. If the latter occurs then the
520 @cmd{FLIP} operation aborts.
522 The resultant dictionary contains a @exvar{CASE_LBL} variable, a string
523 variable of width 8, which stores the names of the variables in the
524 dictionary before the transposition. Variables names longer than 8
525 characters are truncated. If @cmd{FLIP} is called again on
526 this dataset, the @exvar{CASE_LBL} variable can be passed to the @subcmd{NEWNAMES}
527 subcommand to recreate the original variable names.
529 @cmd{FLIP} honors @cmd{N OF CASES} (@pxref{N OF CASES}). It ignores
530 @cmd{TEMPORARY} (@pxref{TEMPORARY}), so that ``temporary''
531 transformations become permanent.
533 @subsection Flip Examples
536 In @ref{flip:ex}, data has been entered using @cmd{DATA LIST} (@pxref{DATA LIST})
537 such that the first variable in the dataset is a string variable containing
538 a description of the other data for the case.
539 Clearly this is not a convenient arrangement for performing statistical analyses,
540 so it would have been better to think a little more carefully about how the data
541 should have been arranged.
542 However often the data is provided by some third party source, and you have
543 no control over the form.
544 Fortunately, we can use @cmd{FLIP} to exchange the variables
545 and cases in the active dataset.
547 @float Example, flip:ex
548 @psppsyntax {flip.sps}
549 @caption {Using @cmd{FLIP} to exchange variables and cases in a dataset}
552 As you can see in @ref{flip:res} before the @cmd{FLIP} command has run there
553 are seven variables (six containing data and one for the heading) and three cases.
554 Afterwards there are four variables (one per case, plus the @exvar{CASE_LBL} variable)
556 You can delete the @exvar{CASE_LBL} variable (@pxref{DELETE VARIABLES}) if you don't need it.
558 @float Results, flip:res
560 @caption {The results of using @cmd{FLIP} to exchange variables and cases in a dataset}
569 IF @var{condition} @var{variable}=@var{expression}.
573 IF @var{condition} vector(@var{index})=@var{expression}.
576 The @cmd{IF} transformation conditionally assigns the value of a target
577 expression to a target variable, based on the truth of a test
580 Specify a boolean-valued expression (@pxref{Expressions}) to be tested
581 following the @cmd{IF} keyword. This expression is evaluated for each case.
582 If the value is true, then the value of the expression is computed and
583 assigned to the specified variable. If the value is false or missing,
584 nothing is done. Numeric and string variables may be
585 assigned. When a string expression's width differs from the target
586 variable's width, the string result of the expression is truncated or
587 padded with spaces on the right as necessary. The expression and
588 variable types must match.
590 The target variable may be specified as an element of a vector
591 (@pxref{VECTOR}). In this case, a vector index expression must be
592 specified in parentheses following the vector name. The index
593 expression must evaluate to a numeric value that, after rounding down
594 to the nearest integer, is a valid index for the named vector.
596 Using @cmd{IF} to assign to a variable specified on @cmd{LEAVE}
597 (@pxref{LEAVE}) resets the variable's left state. Therefore,
598 @code{LEAVE} should be specified following @cmd{IF}, not before.
600 When @cmd{IF} is specified following @cmd{TEMPORARY}
601 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
608 The @cmd{RECODE} command is used to transform existing values into other,
609 user specified values.
613 RECODE @var{src_vars}
614 (@var{src_value} @var{src_value} @dots{} = @var{dest_value})
615 (@var{src_value} @var{src_value} @dots{} = @var{dest_value})
616 (@var{src_value} @var{src_value} @dots{} = @var{dest_value}) @dots{}
617 [INTO @var{dest_vars}].
620 Following the @cmd{RECODE} keyword itself comes @var{src_vars} which is a list
621 of variables whose values are to be transformed.
622 These variables may be string variables or they may be numeric.
623 However the list must be homogeneous; you may not mix string variables and
624 numeric variables in the same recoding.
626 After the list of source variables, there should be one or more @dfn{mappings}.
627 Each mapping is enclosed in parentheses, and contains the source values and
628 a destination value separated by a single @samp{=}.
629 The source values are used to specify the values in the dataset which
630 need to change, and the destination value specifies the new value
631 to which they should be changed.
632 Each @var{src_value} may take one of the following forms:
635 If the source variables are numeric then @var{src_value} may be a literal
638 If the source variables are string variables then @var{src_value} may be a
639 literal string (like all strings, enclosed in single or double quotes).
640 @item @var{num1} THRU @var{num2}
641 This form is valid only when the source variables are numeric.
642 It specifies all values in the range between @var{num1} and @var{num2},
643 including both endpoints of the range. By convention, @var{num1}
644 should be less than @var{num2}.
645 Open-ended ranges may be specified using @samp{LO} or @samp{LOWEST}
647 or @samp{HI} or @samp{HIGHEST} for @var{num2}.
649 The literal keyword @samp{MISSING} matches both system missing and user
651 It is valid for both numeric and string variables.
653 The literal keyword @samp{SYSMIS} matches system missing
655 It is valid for both numeric variables only.
657 The @samp{ELSE} keyword may be used to match any values which are
658 not matched by any other @var{src_value} appearing in the command.
659 If this keyword appears, it should be used in the last mapping of the
663 After the source variables comes an @samp{=} and then the @var{dest_value}.
664 The @var{dest_value} may take any of the following forms:
667 A literal numeric value to which the source values should be changed.
668 This implies the destination variable must be numeric.
670 A literal string value (enclosed in quotation marks) to which the source
671 values should be changed.
672 This implies the destination variable must be a string variable.
674 The keyword @samp{SYSMIS} changes the value to the system missing value.
675 This implies the destination variable must be numeric.
677 The special keyword @samp{COPY} means that the source value should not be
679 copied directly to the destination value.
680 This is meaningful only if @samp{INTO @var{dest_vars}} is specified.
683 Mappings are considered from left to right.
684 Therefore, if a value is matched by a @var{src_value} from more than
685 one mapping, the first (leftmost) mapping which matches is considered.
686 Any subsequent matches are ignored.
688 The clause @samp{INTO @var{dest_vars}} is optional.
689 The behaviour of the command is slightly different depending on whether it
692 If @samp{INTO @var{dest_vars}} does not appear, then values are recoded
694 This means that the recoded values are written back to the
695 source variables from whence the original values came.
696 In this case, the @var{dest_value} for every mapping must imply a value which
697 has the same type as the @var{src_value}.
698 For example, if the source value is a string value, it is not permissible for
699 @var{dest_value} to be @samp{SYSMIS} or another forms which implies a numeric
701 It is also not permissible for @var{dest_value} to be longer than the width
702 of the source variable.
704 The following example two numeric variables @var{x} and @var{y} are recoded
706 Zero is recoded to 99, the values 1 to 10 inclusive are unchanged,
707 values 1000 and higher are recoded to the system-missing value and all other
708 values are changed to 999:
710 recode @var{x} @var{y}
713 (1000 THRU HIGHEST = SYSMIS)
717 If @samp{INTO @var{dest_vars}} is given, then recoded values are written
718 into the variables specified in @var{dest_vars}, which must therefore
719 contain a list of valid variable names.
720 The number of variables in @var{dest_vars} must be the same as the number
721 of variables in @var{src_vars}
722 and the respective order of the variables in @var{dest_vars} corresponds to
723 the order of @var{src_vars}.
724 That is to say, the recoded value whose
725 original value came from the @var{n}th variable in @var{src_vars} is
726 placed into the @var{n}th variable in @var{dest_vars}.
727 The source variables are unchanged.
728 If any mapping implies a string as its destination value, then the respective
729 destination variable must already exist, or
730 have been declared using @cmd{STRING} or another transformation.
731 Numeric variables however are automatically created if they don't already
733 The following example deals with two source variables, @var{a} and @var{b}
734 which contain string values. Hence there are two destination variables
735 @var{v1} and @var{v2}.
736 Any cases where @var{a} or @var{b} contain the values @samp{apple},
737 @samp{pear} or @samp{pomegranate} result in @var{v1} or @var{v2} being
738 filled with the string @samp{fruit} whilst cases with
739 @samp{tomato}, @samp{lettuce} or @samp{carrot} result in @samp{vegetable}.
740 Any other values produce the result @samp{unknown}:
742 string @var{v1} (a20).
743 string @var{v2} (a20).
745 recode @var{a} @var{b}
746 ("apple" "pear" "pomegranate" = "fruit")
747 ("tomato" "lettuce" "carrot" = "vegetable")
749 into @var{v1} @var{v2}.
752 There is one very special mapping, not mentioned above.
753 If the source variable is a string variable
754 then a mapping may be specified as @samp{(CONVERT)}.
755 This mapping, if it appears must be the last mapping given and
756 the @samp{INTO @var{dest_vars}} clause must also be given and
757 must not refer to a string variable.
758 @samp{CONVERT} causes a number specified as a string to
759 be converted to a numeric value.
760 For example it converts the string @samp{"3"} into the numeric
761 value 3 (note that it does not convert @samp{three} into 3).
762 If the string cannot be parsed as a number, then the system-missing value
764 In the following example, cases where the value of @var{x} (a string variable)
765 is the empty string, are recoded to 999 and all others are converted to the
766 numeric equivalent of the input value. The results are placed into the
767 numeric variable @var{y}:
775 It is possible to specify multiple recodings on a single command.
776 Introduce additional recodings with a slash (@samp{/}) to
777 separate them from the previous recodings:
780 @var{a} (2 = 22) (else = 99)
781 /@var{b} (1 = 3) into @var{z}
784 @noindent Here we have two recodings. The first affects the source variable
785 @var{a} and recodes in-place the value 2 into 22 and all other values to 99.
786 The second recoding copies the values of @var{b} into the variable @var{z},
787 changing any instances of 1 into 3.
794 SORT CASES BY @var{var_list}[(@{D|A@}] [ @var{var_list}[(@{D|A@}] ] ...
797 @cmd{SORT CASES} sorts the active dataset by the values of one or more
800 Specify @subcmd{BY} and a list of variables to sort by. By default, variables
801 are sorted in ascending order. To override sort order, specify @subcmd{(D)} or
802 @subcmd{(DOWN)} after a list of variables to get descending order, or @subcmd{(A)}
804 for ascending order. These apply to all the listed variables
805 up until the preceding @subcmd{(A)}, @subcmd{(D)}, @subcmd{(UP)} or @subcmd{(DOWN)}.
807 The sort algorithms used by @cmd{SORT CASES} are stable. This means
808 records which have equal values of the sort variables have the
809 same relative order before and after sorting. Thus,
810 re-sorting an already sorted file does not affect the ordering of
813 @cmd{SORT CASES} is a procedure. It causes the data to be read.
815 @cmd{SORT CASES} attempts to sort the entire active dataset in main memory.
816 If workspace is exhausted, it falls back to a merge sort algorithm that
817 involves creates numerous temporary files.
819 @cmd{SORT CASES} may not be specified following @cmd{TEMPORARY}.
821 @subsection Sorting Example