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}).
227 @subsection Aggregate Example
229 The @file{personnel.sav} dataset provides the occupations and salaries of
230 many individuals. For many purposes however such detailed information is
231 not interesting, but often the aggregated statistics of each occupation are
232 of interest. In @ref{aggregate:ex} the @cmd{AGGREGATE} command is used
233 to calculate the mean, the median and the standard deviation of each
236 @float Example, aggregate:ex
237 @psppsyntax {aggregate.sps}
238 @caption {Calculating aggregated statistics from the @file{personnel.sav} file.}
241 Since we chose the @samp{MODE = REPLACE} option, in @ref{aggregate:res} cases
242 for the individual persons are no longer present. They have each been replaced
243 by a single case per aggregated value.
245 @float Results, aggregate:res
246 @psppoutput {aggregate}
247 @caption {Aggregated mean, median and standard deviation per @exvar{occupation}.}
250 Note that some values for the standard deviation are blank.
251 This is because there is only one case with the respective
260 AUTORECODE VARIABLES=@var{src_vars} INTO @var{dest_vars}
264 [ /BLANK = @{VALID, MISSING@} ]
267 The @cmd{AUTORECODE} procedure considers the @var{n} values that a variable
268 takes on and maps them onto values 1@dots{}@var{n} on a new numeric
271 Subcommand @subcmd{VARIABLES} is the only required subcommand and must come
272 first. Specify @subcmd{VARIABLES}, an equals sign (@samp{=}), a list of source
273 variables, @subcmd{INTO}, and a list of target variables. There must the same
274 number of source and target variables. The target variables must not
277 @cmd{AUTORECODE} ordinarily assigns each increasing non-missing value
278 of a source variable (for a string, this is based on character code
279 comparisons) to consecutive values of its target variable. For
280 example, the smallest non-missing value of the source variable is
281 recoded to value 1, the next smallest to 2, and so on. If the source
282 variable has user-missing values, they are recoded to
283 consecutive values just above the non-missing values. For example, if
284 a source variables has seven distinct non-missing values, then the
285 smallest missing value would be recoded to 8, the next smallest to 9,
288 Use @subcmd{DESCENDING} to reverse the sort order for non-missing
289 values, so that the largest non-missing value is recoded to 1, the
290 second-largest to 2, and so on. Even with @subcmd{DESCENDING},
291 user-missing values are still recoded in ascending order just above
292 the non-missing values.
294 The system-missing value is always recoded into the system-missing
295 variable in target variables.
297 If a source value has a value label, then that value label is retained
298 for the new value in the target variable. Otherwise, the source value
299 itself becomes each new value's label.
301 Variable labels are copied from the source to target variables.
303 @subcmd{PRINT} is currently ignored.
305 The @subcmd{GROUP} subcommand is relevant only if more than one variable is to be
306 recoded. It causes a single mapping between source and target values to
307 be used, instead of one map per variable. With @subcmd{GROUP},
308 user-missing values are taken from the first source variable that has
309 any user-missing values.
311 If @subcmd{/BLANK=MISSING} is given, then string variables which contain only
312 whitespace are recoded as SYSMIS. If @subcmd{/BLANK=VALID} is specified then they
313 are allocated a value like any other. @subcmd{/BLANK} is not relevant
314 to numeric values. @subcmd{/BLANK=VALID} is the default.
316 @cmd{AUTORECODE} is a procedure. It causes the data to be read.
318 @subsection Autorecode Example
320 In the file @file{personnel.sav}, the variable @exvar{occupation} is a string
321 variable. Except for data of a purely commentary nature, string variables
322 are generally a bad idea. One reason is that data entry errors are easily
323 overlooked. This has happened in @file{personnel.sav}; one entry which should
324 read ``Scientist'' has been mistyped as ``Scrientist''. In @ref{autorecode:ex}
325 first, this error is corrected by the @cmd{DO IF} clause,
326 @footnote{One must use care when correcting such data input errors rather than
327 msimply marking them as missing. For example, if an occupation has been entered
328 ``Barister'', did the person mean ``Barrister'' or did she mean ``Barista''?}
329 then we use @cmd{AUTORECODE} to
330 create a new numeric variable which takes recoded values of @exvar{occupation}.
331 Finally, we remove the old variable and rename the new variable to
332 the name of the old variable.
334 @float Example, autorecode:ex
335 @psppsyntax {autorecode.sps}
336 @caption {Changing a string variable to a numeric variable using @cmd{AUTORECODE}
337 after correcting a data entry error}
341 Notice in @ref{autorecode:res}, how the new variable has been automatically
342 allocated value labels which correspond to the strings of the old variable.
343 This means that in future analyses the descriptive strings are reported instead
344 of the numeric values.
346 @float Result, autorecode:res
347 @psppoutput {autorecode}
348 @caption {The properties of the @exvar{occupation} variable following @cmd{AUTORECODE}}
357 COMPUTE @var{variable} = @var{expression}.
361 COMPUTE vector(@var{index}) = @var{expression}.
364 @cmd{COMPUTE} assigns the value of an expression to a target
365 variable. For each case, the expression is evaluated and its value
366 assigned to the target variable. Numeric and string
367 variables may be assigned. When a string expression's width differs
368 from the target variable's width, the string result of the expression
369 is truncated or padded with spaces on the right as necessary. The
370 expression and variable types must match.
372 For numeric variables only, the target variable need not already
373 exist. Numeric variables created by @cmd{COMPUTE} are assigned an
374 @code{F8.2} output format. String variables must be declared before
375 they can be used as targets for @cmd{COMPUTE}.
377 The target variable may be specified as an element of a vector
378 (@pxref{VECTOR}). In this case, an expression @var{index} must be
379 specified in parentheses following the vector name. The expression @var{index}
380 must evaluate to a numeric value that, after rounding down
381 to the nearest integer, is a valid index for the named vector.
383 Using @cmd{COMPUTE} to assign to a variable specified on @cmd{LEAVE}
384 (@pxref{LEAVE}) resets the variable's left state. Therefore,
385 @code{LEAVE} should be specified following @cmd{COMPUTE}, not before.
387 @cmd{COMPUTE} is a transformation. It does not cause the active dataset to be
390 When @cmd{COMPUTE} is specified following @cmd{TEMPORARY}
391 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
394 @subsection Compute Examples
396 The dataset @file{physiology.sav} contains the height and weight of persons.
397 For some purposes, neither height nor weight alone is of interest.
398 Epidemiologists are often more interested in the @dfn{body mass index} which
399 can sometimes be used as a predictor for clinical conditions.
400 The body mass index is defined as the weight of the person in kilograms divided
401 by the square of the person's height in metres.
402 @footnote{Since BMI is a quantity with a ratio scale and has units, the term ``index''
403 is a misnomer, but that is what it is called.}
405 @float Example, bmi:ex
406 @psppsyntax {compute.sps}
407 @caption {Computing the body mass index from @exvar{weight} and @exvar{height}}
410 @ref{bmi:ex} shows how you can use @cmd{COMPUTE} to generate a new variable called
411 @exvar{bmi} and have every case's value calculated from the existing values of
412 @exvar{weight} and @exvar{height}.
413 It also shows how you can add a label to this new variable (@pxref{VARIABLE LABELS}),
414 so that a more descriptive label appears in subsequent analyses, and this can be seen
415 in the ouput from the @cmd{DESCRIPTIVES} command in @ref{bmi:res}.
417 The expression which follows the @samp{=} sign can be as complicated as necessary.
418 @xref{Expressions} for a precise description of the language accepted.
420 @float Results, bmi:res
421 @psppoutput {compute}
422 @caption {An analysis which includes @exvar{bmi} in its results}
432 COUNT @var{var_name} = @var{var}@dots{} (@var{value}@dots{})
433 [/@var{var_name} = @var{var}@dots{} (@var{value}@dots{})]@dots{}
435 Each @var{value} takes one of the following forms:
438 @var{num1} THRU @var{num2}
441 where @var{num1} is a numeric expression or the words @subcmd{LO} or @subcmd{LOWEST}
442 and @var{num2} is a numeric expression or @subcmd{HI} or @subcmd{HIGHEST}.
445 @cmd{COUNT} creates or replaces a numeric @dfn{target} variable that
446 counts the occurrence of a @dfn{criterion} value or set of values over
447 one or more @dfn{test} variables for each case.
449 The target variable values are always nonnegative integers. They are
450 never missing. The target variable is assigned an F8.2 output format.
451 @xref{Input and Output Formats}. Any variables, including
452 string variables, may be test variables.
454 User-missing values of test variables are treated just like any other
455 values. They are @strong{not} treated as system-missing values.
456 User-missing values that are criterion values or inside ranges of
457 criterion values are counted as any other values. However (for numeric
458 variables), keyword @subcmd{MISSING} may be used to refer to all system-
459 and user-missing values.
461 @cmd{COUNT} target variables are assigned values in the order
462 specified. In the command @subcmd{COUNT @var{A}=@var{A} @var{B}(1) /@var{B}=@var{A} @var{B}(2).}, the
463 following actions occur:
467 The number of occurrences of 1 between @var{A} and @var{B} is counted.
470 @var{A} is assigned this value.
473 The number of occurrences of 1 between @var{B} and the @strong{new}
474 value of @var{A} is counted.
477 @var{B} is assigned this value.
480 Despite this ordering, all @cmd{COUNT} criterion variables must exist
481 before the procedure is executed---they may not be created as target
482 variables earlier in the command! Break such a command into two
485 @subsection Count Examples
487 In the survey results in dataset @file{hotel.sav} a manager wishes
488 to know how many respondents answered with low valued answers to questions
489 @exvar{v1}, @exvar{v2} and @exvar{v3}. This can be found using the code
490 in @ref{count:ex}. Specifically, this code creates a new variable, and
491 populates it with the number of values in @exvar{v1}--@exvar{v2} which
494 @float Example, count:ex
495 @psppsyntax {count.sps}
496 @caption {Counting low values to responses @exvar{v1}, @exvar{v2} and @exvar{v3}}
499 In @ref{count:ex} the @cmd{COUNT} transformation creates a new variable, @exvar{low_counts} and
500 its values are shown using the @cmd{LIST} command.
502 In @ref{count:res} we can see the values of @exvar{low_counts} after the @cmd{COUNT}
503 transformation has completed. The first value is 1, because there is only one
504 variable amoung @exvar{v1}, @exvar{v2} and @exvar{3} which has a value of 2 or less.
505 The second value is 2, because both @exvar{v1} and @exvar{v2} are 2 or less.
507 @float Result, count:res
509 @caption {The values of @exvar{v1}, @exvar{v2}, @exvar{v3} and @exvar{low_counts} after
510 the @cmd{COUNT} transformation has run}
519 FLIP /VARIABLES=@var{var_list} /NEWNAMES=@var{var_name}.
522 @cmd{FLIP} transposes rows and columns in the active dataset. It
523 causes cases to be swapped with variables, and vice versa.
525 All variables in the transposed active dataset are numeric. String
526 variables take on the system-missing value in the transposed file.
528 @subcmd{N} subcommands are required. If specified, the @subcmd{VARIABLES} subcommand
529 selects variables to be transformed into cases, and variables not
530 specified are discarded. If the @subcmd{VARIABLES} subcommand is omitted, all
531 variables are selected for transposition.
533 The variables specified by @subcmd{NEWNAMES}, which must be a
535 used to give names to the variables created by @cmd{FLIP}. Only the
536 first 8 characters of the variable are used. If
537 @subcmd{NEWNAMES} is not
538 specified then the default is a variable named @exvar{CASE_LBL}, if it exists.
539 If it does not then the variables created by @cmd{FLIP} are named VAR000
540 through VAR999, then VAR1000, VAR1001, and so on.
542 When a @subcmd{NEWNAMES} variable is available, the names must be canonicalized
543 before becoming variable names. Invalid characters are replaced by
544 letter @samp{V} in the first position, or by @samp{_} in subsequent
545 positions. If the name thus generated is not unique, then numeric
546 extensions are added, starting with 1, until a unique name is found or
547 there are no remaining possibilities. If the latter occurs then the
548 @cmd{FLIP} operation aborts.
550 The resultant dictionary contains a @exvar{CASE_LBL} variable, a string
551 variable of width 8, which stores the names of the variables in the
552 dictionary before the transposition. Variables names longer than 8
553 characters are truncated. If @cmd{FLIP} is called again on
554 this dataset, the @exvar{CASE_LBL} variable can be passed to the @subcmd{NEWNAMES}
555 subcommand to recreate the original variable names.
557 @cmd{FLIP} honors @cmd{N OF CASES} (@pxref{N OF CASES}). It ignores
558 @cmd{TEMPORARY} (@pxref{TEMPORARY}), so that ``temporary''
559 transformations become permanent.
561 @subsection Flip Examples
564 In @ref{flip:ex}, data has been entered using @cmd{DATA LIST} (@pxref{DATA LIST})
565 such that the first variable in the dataset is a string variable containing
566 a description of the other data for the case.
567 Clearly this is not a convenient arrangement for performing statistical analyses,
568 so it would have been better to think a little more carefully about how the data
569 should have been arranged.
570 However often the data is provided by some third party source, and you have
571 no control over the form.
572 Fortunately, we can use @cmd{FLIP} to exchange the variables
573 and cases in the active dataset.
575 @float Example, flip:ex
576 @psppsyntax {flip.sps}
577 @caption {Using @cmd{FLIP} to exchange variables and cases in a dataset}
580 As you can see in @ref{flip:res} before the @cmd{FLIP} command has run there
581 are seven variables (six containing data and one for the heading) and three cases.
582 Afterwards there are four variables (one per case, plus the @exvar{CASE_LBL} variable)
584 You can delete the @exvar{CASE_LBL} variable (@pxref{DELETE VARIABLES}) if you don't need it.
586 @float Results, flip:res
588 @caption {The results of using @cmd{FLIP} to exchange variables and cases in a dataset}
597 IF @var{condition} @var{variable}=@var{expression}.
601 IF @var{condition} vector(@var{index})=@var{expression}.
604 The @cmd{IF} transformation conditionally assigns the value of a target
605 expression to a target variable, based on the truth of a test
608 Specify a boolean-valued expression (@pxref{Expressions}) to be tested
609 following the @cmd{IF} keyword. This expression is evaluated for each case.
610 If the value is true, then the value of the expression is computed and
611 assigned to the specified variable. If the value is false or missing,
612 nothing is done. Numeric and string variables may be
613 assigned. When a string expression's width differs from the target
614 variable's width, the string result of the expression is truncated or
615 padded with spaces on the right as necessary. The expression and
616 variable types must match.
618 The target variable may be specified as an element of a vector
619 (@pxref{VECTOR}). In this case, a vector index expression must be
620 specified in parentheses following the vector name. The index
621 expression must evaluate to a numeric value that, after rounding down
622 to the nearest integer, is a valid index for the named vector.
624 Using @cmd{IF} to assign to a variable specified on @cmd{LEAVE}
625 (@pxref{LEAVE}) resets the variable's left state. Therefore,
626 @code{LEAVE} should be specified following @cmd{IF}, not before.
628 When @cmd{IF} is specified following @cmd{TEMPORARY}
629 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
636 The @cmd{RECODE} command is used to transform existing values into other,
637 user specified values.
641 RECODE @var{src_vars}
642 (@var{src_value} @var{src_value} @dots{} = @var{dest_value})
643 (@var{src_value} @var{src_value} @dots{} = @var{dest_value})
644 (@var{src_value} @var{src_value} @dots{} = @var{dest_value}) @dots{}
645 [INTO @var{dest_vars}].
648 Following the @cmd{RECODE} keyword itself comes @var{src_vars} which is a list
649 of variables whose values are to be transformed.
650 These variables may be string variables or they may be numeric.
651 However the list must be homogeneous; you may not mix string variables and
652 numeric variables in the same recoding.
654 After the list of source variables, there should be one or more @dfn{mappings}.
655 Each mapping is enclosed in parentheses, and contains the source values and
656 a destination value separated by a single @samp{=}.
657 The source values are used to specify the values in the dataset which
658 need to change, and the destination value specifies the new value
659 to which they should be changed.
660 Each @var{src_value} may take one of the following forms:
663 If the source variables are numeric then @var{src_value} may be a literal
666 If the source variables are string variables then @var{src_value} may be a
667 literal string (like all strings, enclosed in single or double quotes).
668 @item @var{num1} THRU @var{num2}
669 This form is valid only when the source variables are numeric.
670 It specifies all values in the range between @var{num1} and @var{num2},
671 including both endpoints of the range. By convention, @var{num1}
672 should be less than @var{num2}.
673 Open-ended ranges may be specified using @samp{LO} or @samp{LOWEST}
675 or @samp{HI} or @samp{HIGHEST} for @var{num2}.
677 The literal keyword @samp{MISSING} matches both system missing and user
679 It is valid for both numeric and string variables.
681 The literal keyword @samp{SYSMIS} matches system missing
683 It is valid for both numeric variables only.
685 The @samp{ELSE} keyword may be used to match any values which are
686 not matched by any other @var{src_value} appearing in the command.
687 If this keyword appears, it should be used in the last mapping of the
691 After the source variables comes an @samp{=} and then the @var{dest_value}.
692 The @var{dest_value} may take any of the following forms:
695 A literal numeric value to which the source values should be changed.
696 This implies the destination variable must be numeric.
698 A literal string value (enclosed in quotation marks) to which the source
699 values should be changed.
700 This implies the destination variable must be a string variable.
702 The keyword @samp{SYSMIS} changes the value to the system missing value.
703 This implies the destination variable must be numeric.
705 The special keyword @samp{COPY} means that the source value should not be
707 copied directly to the destination value.
708 This is meaningful only if @samp{INTO @var{dest_vars}} is specified.
711 Mappings are considered from left to right.
712 Therefore, if a value is matched by a @var{src_value} from more than
713 one mapping, the first (leftmost) mapping which matches is considered.
714 Any subsequent matches are ignored.
716 The clause @samp{INTO @var{dest_vars}} is optional.
717 The behaviour of the command is slightly different depending on whether it
720 If @samp{INTO @var{dest_vars}} does not appear, then values are recoded
722 This means that the recoded values are written back to the
723 source variables from whence the original values came.
724 In this case, the @var{dest_value} for every mapping must imply a value which
725 has the same type as the @var{src_value}.
726 For example, if the source value is a string value, it is not permissible for
727 @var{dest_value} to be @samp{SYSMIS} or another forms which implies a numeric
729 It is also not permissible for @var{dest_value} to be longer than the width
730 of the source variable.
732 The following example two numeric variables @var{x} and @var{y} are recoded
734 Zero is recoded to 99, the values 1 to 10 inclusive are unchanged,
735 values 1000 and higher are recoded to the system-missing value and all other
736 values are changed to 999:
738 recode @var{x} @var{y}
741 (1000 THRU HIGHEST = SYSMIS)
745 If @samp{INTO @var{dest_vars}} is given, then recoded values are written
746 into the variables specified in @var{dest_vars}, which must therefore
747 contain a list of valid variable names.
748 The number of variables in @var{dest_vars} must be the same as the number
749 of variables in @var{src_vars}
750 and the respective order of the variables in @var{dest_vars} corresponds to
751 the order of @var{src_vars}.
752 That is to say, the recoded value whose
753 original value came from the @var{n}th variable in @var{src_vars} is
754 placed into the @var{n}th variable in @var{dest_vars}.
755 The source variables are unchanged.
756 If any mapping implies a string as its destination value, then the respective
757 destination variable must already exist, or
758 have been declared using @cmd{STRING} or another transformation.
759 Numeric variables however are automatically created if they don't already
761 The following example deals with two source variables, @var{a} and @var{b}
762 which contain string values. Hence there are two destination variables
763 @var{v1} and @var{v2}.
764 Any cases where @var{a} or @var{b} contain the values @samp{apple},
765 @samp{pear} or @samp{pomegranate} result in @var{v1} or @var{v2} being
766 filled with the string @samp{fruit} whilst cases with
767 @samp{tomato}, @samp{lettuce} or @samp{carrot} result in @samp{vegetable}.
768 Any other values produce the result @samp{unknown}:
770 string @var{v1} (a20).
771 string @var{v2} (a20).
773 recode @var{a} @var{b}
774 ("apple" "pear" "pomegranate" = "fruit")
775 ("tomato" "lettuce" "carrot" = "vegetable")
777 into @var{v1} @var{v2}.
780 There is one very special mapping, not mentioned above.
781 If the source variable is a string variable
782 then a mapping may be specified as @samp{(CONVERT)}.
783 This mapping, if it appears must be the last mapping given and
784 the @samp{INTO @var{dest_vars}} clause must also be given and
785 must not refer to a string variable.
786 @samp{CONVERT} causes a number specified as a string to
787 be converted to a numeric value.
788 For example it converts the string @samp{"3"} into the numeric
789 value 3 (note that it does not convert @samp{three} into 3).
790 If the string cannot be parsed as a number, then the system-missing value
792 In the following example, cases where the value of @var{x} (a string variable)
793 is the empty string, are recoded to 999 and all others are converted to the
794 numeric equivalent of the input value. The results are placed into the
795 numeric variable @var{y}:
803 It is possible to specify multiple recodings on a single command.
804 Introduce additional recodings with a slash (@samp{/}) to
805 separate them from the previous recodings:
808 @var{a} (2 = 22) (else = 99)
809 /@var{b} (1 = 3) into @var{z}
812 @noindent Here we have two recodings. The first affects the source variable
813 @var{a} and recodes in-place the value 2 into 22 and all other values to 99.
814 The second recoding copies the values of @var{b} into the variable @var{z},
815 changing any instances of 1 into 3.
822 SORT CASES BY @var{var_list}[(@{D|A@}] [ @var{var_list}[(@{D|A@}] ] ...
825 @cmd{SORT CASES} sorts the active dataset by the values of one or more
828 Specify @subcmd{BY} and a list of variables to sort by. By default, variables
829 are sorted in ascending order. To override sort order, specify @subcmd{(D)} or
830 @subcmd{(DOWN)} after a list of variables to get descending order, or @subcmd{(A)}
832 for ascending order. These apply to all the listed variables
833 up until the preceding @subcmd{(A)}, @subcmd{(D)}, @subcmd{(UP)} or @subcmd{(DOWN)}.
835 The sort algorithms used by @cmd{SORT CASES} are stable. This means
836 records which have equal values of the sort variables have the
837 same relative order before and after sorting. Thus,
838 re-sorting an already sorted file does not affect the ordering of
841 @cmd{SORT CASES} is a procedure. It causes the data to be read.
843 @cmd{SORT CASES} attempts to sort the entire active dataset in main memory.
844 If workspace is exhausted, it falls back to a merge sort algorithm which
845 creates numerous temporary files.
847 @cmd{SORT CASES} may not be specified following @cmd{TEMPORARY}.
849 @subsection Sorting Example
851 In @ref{sort-cases:ex} the data from the file @file {physiology.sav} is sorted
852 by two variables, @i{viz@:} @exvar{sex} in descending order and @exvar{temperature} in
855 @float Example, sort-cases:ex
856 @psppsyntax {sort-cases.sps}
857 @caption {Sorting cases by two variables.}
860 In @ref{sort-cases:res} you can see that all the cases with a @exvar{sex} of
861 @samp{1} (female) appear before those with a sex of @samp{0} (male).
862 This is because they have been sorted in descending order.
863 Within each sex, the data is sorted on the @exvar{temperature} variable,
864 this time in ascending order.
866 @float Results, sort-cases:res
867 @psppoutput {sort-cases}
868 @caption {The @file{physiology.sav} file after sorting.}
871 Note that @cmd{SORT CASES}, like all other transformations, affects only the active file.
872 It does not have any effect upon the @file{physiology.sav} file itself. For that, you
873 would have to rewrite the file using the @cmd{SAVE} command (@pxref{SAVE}).