X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Ftransformation.texi;h=cad85b3fb9689124893bec391ba654b5ee73ee03;hb=4056e461fd8f8d9ba7feca63c73d2f50a2048b63;hp=5ee7febef0f78d79fc5f12c9d9ac8fc5e200041e;hpb=a12aeb43c5edf27b0ef2be5c2d7db30214a31a2b;p=pspp diff --git a/doc/transformation.texi b/doc/transformation.texi index 5ee7febef0..cad85b3fb9 100644 --- a/doc/transformation.texi +++ b/doc/transformation.texi @@ -31,7 +31,7 @@ as a rule. @vindex AGGREGATE @display -AGGREGATE +AGGREGATE OUTFILE=@{*,'@var{file_name}',@var{file_handle}@} [MODE=@{REPLACE, ADDVARIABLES@}] /PRESORTED /DOCUMENT @@ -60,7 +60,7 @@ In @subcmd{REPLACE} mode, the entire active dataset is replaced by a new dataset which contains just the break variables and the destination varibles. In this mode, the new file will contain as many cases as there are unique combinations of the break variables. -In @subcmd{ADDVARIABLES} mode, the destination variables will be appended to +In @subcmd{ADDVARIABLES} mode, the destination variables will be appended to the existing active dataset. Cases which have identical combinations of values in their break variables, will receive identical values for the destination variables. @@ -218,7 +218,7 @@ On most modern computers, this is @acronym{ASCII} or a superset thereof. The aggregation functions listed above exclude all user-missing values from calculations. To include user-missing values, insert a period -(@samp{.}) at the end of the function name. (e.g.@: @samp{SUM.}). +(@samp{.}) at the end of the function name. (@i{e.g.}@: @samp{SUM.}). (Be aware that specifying such a function as the last token on a line will cause the period to be interpreted as the end of the command.) @@ -267,6 +267,12 @@ the non-missing values. The system-missing value is always recoded into the system-missing variable in target variables. +If a source value has a value label, then that value label is retained +for the new value in the target variable. Otherwise, the source value +itself becomes each new value's label. + +Variable labels are copied from the source to target variables. + @subcmd{PRINT} is currently ignored. The @subcmd{GROUP} subcommand is relevant only if more than one variable is to be @@ -275,13 +281,47 @@ be used, instead of one map per variable. With @subcmd{GROUP}, user-missing values are taken from the first source variable that has any user-missing values. -If @subcmd{/BLANK=MISSING} is given, then string variables which contain only +If @subcmd{/BLANK=MISSING} is given, then string variables which contain only whitespace are recoded as SYSMIS. If @subcmd{/BLANK=VALID} is given then they will be allocated a value like any other. @subcmd{/BLANK} is not relevant to numeric values. @subcmd{/BLANK=VALID} is the default. @cmd{AUTORECODE} is a procedure. It causes the data to be read. +@subsection Autorecode Example + +In the file @file{personnel.sav}, the variable @exvar{occupation} is a string +variable. Except for data of a purely commentary nature, string variables +are generally a bad idea. One reason is that data entry errors are easily +overlooked. This has happened in @file{personnel.sav}; one entry which should +read ``Scientist'' has been mistyped as ``Scrientist''. In @ref{autorecode:ex} +first, this error will be corrected, +@footnote{One must use care when correcting such data input errors rather than +msimply marking them as missing. For example, if an occupation has been entered +``Barister'', did the person mean ``Barrister'' or did she mean ``Barista''?} +then we will use @cmd{AUTORECODE} to +create a new numeric variable which takes recoded values of @exvar{occupation}. +Finally, we will remove the old variable and rename the new variable to +the name of the old variable. + +@float Example, autorecode:ex +@psppsyntax {autorecode.sps} +@caption {Changing a string variable to a numeric variable using @cmd{AUTORECODE} +after correcting a data entry error} +@end float + + +Notice in @ref{autorecode:res}, how the new variable has been automatically +allocated value labels which correspond to the strings of the old variable. +This means that in future analyses the descriptive strings are reported instead +of the numeric values. + +@float Result, autorecode:res +@psppoutput {autorecode} +@caption {The properties of the @exvar{occupation} variable following @cmd{AUTORECODE}} +@end float + + @node COMPUTE @section COMPUTE @vindex COMPUTE @@ -324,6 +364,39 @@ When @cmd{COMPUTE} is specified following @cmd{TEMPORARY} (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used (@pxref{LAG}). +@subsection Compute Examples + +The dataset @file{physiology.sav} contains the height and weight of persons. +For some purposes, neither height nor weight alone is of interest. +Epidemiologists are often more interested in the @dfn{body mass index} which +can sometimes be used as a predictor for clinical conditions. +The body mass index is defined as the weight of the person in kg divided +by the square of the person's height in metres. +@footnote{Since BMI is a quantity with a ratio scale and has units, the term ``index'' +is a misnomer, but that is what it is called.} + +@float Example, bmi:ex +@psppsyntax {compute.sps} +@caption {Computing the body mass index from @exvar{weight} and @exvar{height}} +@end float + +@ref{bmi:ex} shows how you can use @cmd{COMPUTE} to generate a new variable called +@exvar{bmi} and have every case's value calculated from the existing values of +@exvar{weight} and @exvar{height}. +It also shows how you can add a label to this new variable (@pxref{VARIABLE LABELS}), +so that a more descriptive label appears in subsequent analyses, and this can be seen +in the ouput from the @cmd{DESCRIPTIVES} command in @ref{bmi:res}. + +The expression which follows the @samp{=} sign can be as complicated as necessary. +@xref{Expressions} for a precise description of the language accepted. + +@float Results, bmi:res +@psppoutput {compute} +@caption {An analysis which includes @exvar{bmi} in its results} +@end float + + + @node COUNT @section COUNT @vindex COUNT @@ -382,52 +455,34 @@ before the procedure is executed---they may not be created as target variables earlier in the command! Break such a command into two separate commands. -The examples below may help to clarify. - -@enumerate A -@item -Assuming @code{Q0}, @code{Q2}, @dots{}, @code{Q9} are numeric variables, -the following commands: - -@enumerate -@item -Count the number of times the value 1 occurs through these variables -for each case and assigns the count to variable @code{QCOUNT}. - -@item -Print out the total number of times the value 1 occurs throughout -@emph{all} cases using @cmd{DESCRIPTIVES}. @xref{DESCRIPTIVES}, for -details. -@end enumerate +@subsection Count Examples -@example -COUNT QCOUNT=Q0 TO Q9(1). -DESCRIPTIVES QCOUNT /STATISTICS=SUM. -@end example +In the survey results in dataset @file{hotel.sav} a manager wishes +to know how many respondents answered with low valued answers to questions +@exvar{v1}, @exvar{v2} and @exvar{v3}. This can be found using the code +in @ref{count:ex}. Specifically, this code creates a new variable, and +populates it with the number of values in @exvar{v1}--@exvar{v2} which +are 2 or lower. -@item -Given these same variables, the following commands: +@float Example, count:ex +@psppsyntax {count.sps} +@caption {Counting low values to responses @exvar{v1}, @exvar{v2} and @exvar{v3}} +@end float -@enumerate -@item -Count the number of valid values of these variables for each case and -assigns the count to variable @code{QVALID}. +In @ref{count:ex} the @cmd{COUNT} transformation creates a new variable, @exvar{low_counts} and +its values are shown using the @cmd{LIST} command. -@item -Multiplies each value of @code{QVALID} by 10 to obtain a percentage of -valid values, using @cmd{COMPUTE}. @xref{COMPUTE}, for details. +In @ref{count:res} we can see the values of @exvar{low_counts} after the @cmd{COUNT} +transformation has completed. The first value is 1, because there is only one +variable amoung @exvar{v1}, @exvar{v2} and @exvar{3} which has a value of 2 or less. +The second value is 2, because both @exvar{v1} and @exvar{v2} are 2 or less. -@item -Print out the percentage of valid values across all cases, using -@cmd{DESCRIPTIVES}. @xref{DESCRIPTIVES}, for details. -@end enumerate +@float Result, count:res +@psppoutput {count} +@caption {The values of @exvar{v1}, @exvar{v2}, @exvar{v3} and @exvar{low_counts} after +the @cmd{COUNT} transformation has run} +@end float -@example -COUNT QVALID=Q0 TO Q9 (LO THRU HI). -COMPUTE QVALID=QVALID*10. -DESCRIPTIVES QVALID /STATISTICS=MEAN. -@end example -@end enumerate @node FLIP @section FLIP @@ -453,7 +508,7 @@ string variable, is used to give names to the variables created by @cmd{FLIP}. Only the first 8 characters of the variable are used. If @subcmd{NEWNAMES} is not -specified then the default is a variable named CASE_LBL, if it exists. +specified then the default is a variable named @exvar{CASE_LBL}, if it exists. If it does not then the variables created by @cmd{FLIP} are named VAR000 through VAR999, then VAR1000, VAR1001, and so on. @@ -465,17 +520,48 @@ extensions are added, starting with 1, until a unique name is found or there are no remaining possibilities. If the latter occurs then the @cmd{FLIP} operation aborts. -The resultant dictionary contains a CASE_LBL variable, a string +The resultant dictionary contains a @exvar{CASE_LBL} variable, a string variable of width 8, which stores the names of the variables in the dictionary before the transposition. Variables names longer than 8 -characters are truncated. If the active dataset is subsequently -transposed using @cmd{FLIP}, this variable can be used to recreate the -original variable names. +characters are truncated. If @cmd{FLIP} is called again on +this dataset, the @exvar{CASE_LBL} variable can be passed to the @subcmd{NEWNAMES} +subcommand to recreate the original variable names. @cmd{FLIP} honors @cmd{N OF CASES} (@pxref{N OF CASES}). It ignores @cmd{TEMPORARY} (@pxref{TEMPORARY}), so that ``temporary'' transformations become permanent. +@subsection Flip Examples + + +In @ref{flip:ex}, data has been entered using @cmd{DATA LIST} (@pxref{DATA LIST}) +such that the first variable in the dataset is a string variable containing +a description of the other data for the case. +Clearly this is not a convenient arrangement for performing statistical analyses, +so it would have been better to think a little more carefully about how the data +should have been arranged. +However often the data is provided by some third party source, and you have +no control over the form. +Fortunately, we can use @cmd{FLIP} to exchange the variables +and cases in the active dataset. + +@float Example, flip:ex +@psppsyntax {flip.sps} +@caption {Using @cmd{FLIP} to exchange variables and cases in a dataset} +@end float + +As you can see in @ref{flip:res} before the @cmd{FLIP} command has run there +are seven variables (six containing data and one for the heading) and three cases. +Afterwards there are four variables (one per case, plus the @exvar{CASE_LBL} variable) +and six cases. +You can delete the @exvar{CASE_LBL} variable (@pxref{DELETE VARIABLES}) if you don't need it. + +@float Results, flip:res +@psppoutput {flip} +@caption {The results of using @cmd{FLIP} to exchange variables and cases in a dataset} +@end float + + @node IF @section IF @vindex IF @@ -541,7 +627,7 @@ numeric variables in the same recoding. After the list of source variables, there should be one or more @dfn{mappings}. Each mapping is enclosed in parentheses, and contains the source values and a destination value separated by a single @samp{=}. -The source values are used to specify the values in the dataset which +The source values are used to specify the values in the dataset which need to change, and the destination value specifies the new value to which they should be changed. Each @var{src_value} may take one of the following forms: @@ -557,7 +643,7 @@ This form is valid only when the source variables are numeric. It specifies all values in the range between @var{num1} and @var{num2}, including both endpoints of the range. By convention, @var{num1} should be less than @var{num2}. -Open-ended ranges may be specified using @samp{LO} or @samp{LOWEST} +Open-ended ranges may be specified using @samp{LO} or @samp{LOWEST} for @var{num1} or @samp{HI} or @samp{HIGHEST} for @var{num2}. @item @samp{MISSING} @@ -571,7 +657,7 @@ It is valid for both numeric variables only. @item @samp{ELSE} The @samp{ELSE} keyword may be used to match any values which are not matched by any other @var{src_value} appearing in the command. -If this keyword appears, it should be used in the last mapping of the +If this keyword appears, it should be used in the last mapping of the command. @end table @@ -596,7 +682,7 @@ This is meaningful only if @samp{INTO @var{dest_vars}} is specified. @end table Mappings are considered from left to right. -Therefore, if a value is matched by a @var{src_value} from more than +Therefore, if a value is matched by a @var{src_value} from more than one mapping, the first (leftmost) mapping which matches will be considered. Any subsequent matches will be ignored. @@ -622,7 +708,7 @@ Zero is recoded to 99, the values 1 to 10 inclusive are unchanged, values 1000 and higher are recoded to the system-missing value and all other values are changed to 999: @example -recode @var{x} @var{y} +recode @var{x} @var{y} (0 = 99) (1 THRU 10 = COPY) (1000 THRU HIGHEST = SYSMIS) @@ -634,30 +720,30 @@ into the variables specified in @var{dest_vars}, which must therefore contain a list of valid variable names. The number of variables in @var{dest_vars} must be the same as the number of variables in @var{src_vars} -and the respective order of the variables in @var{dest_vars} corresponds to +and the respective order of the variables in @var{dest_vars} corresponds to the order of @var{src_vars}. -That is to say, recoded values whose +That is to say, recoded values whose original value came from the @var{n}th variable in @var{src_vars} will be placed into the @var{n}th variable in @var{dest_vars}. The source variables will be unchanged. If any mapping implies a string as its destination value, then the respective -destination variable must already exist, or +destination variable must already exist, or have been declared using @cmd{STRING} or another transformation. Numeric variables however will be automatically created if they don't already exist. The following example deals with two source variables, @var{a} and @var{b} which contain string values. Hence there are two destination variables @var{v1} and @var{v2}. -Any cases where @var{a} or @var{b} contain the values @samp{apple}, +Any cases where @var{a} or @var{b} contain the values @samp{apple}, @samp{pear} or @samp{pomegranate} will result in @var{v1} or @var{v2} being -filled with the string @samp{fruit} whilst cases with +filled with the string @samp{fruit} whilst cases with @samp{tomato}, @samp{lettuce} or @samp{carrot} will result in @samp{vegetable}. Any other values will produce the result @samp{unknown}: @example string @var{v1} (a20). string @var{v2} (a20). -recode @var{a} @var{b} +recode @var{a} @var{b} ("apple" "pear" "pomegranate" = "fruit") ("tomato" "lettuce" "carrot" = "vegetable") (ELSE = "unknown") @@ -668,20 +754,20 @@ There is one very special mapping, not mentioned above. If the source variable is a string variable then a mapping may be specified as @samp{(CONVERT)}. This mapping, if it appears must be the last mapping given and -the @samp{INTO @var{dest_vars}} clause must also be given and -must not refer to a string variable. +the @samp{INTO @var{dest_vars}} clause must also be given and +must not refer to a string variable. @samp{CONVERT} causes a number specified as a string to -be converted to a numeric value. +be converted to a numeric value. For example it will convert the string @samp{"3"} into the numeric value 3 (note that it will not convert @samp{three} into 3). If the string cannot be parsed as a number, then the system-missing value is assigned instead. In the following example, cases where the value of @var{x} (a string variable) is the empty string, are recoded to 999 and all others are converted to the -numeric equivalent of the input value. The results are placed into the +numeric equivalent of the input value. The results are placed into the numeric variable @var{y}: @example -recode @var{x} +recode @var{x} ("" = 999) (convert) into @var{y}. @@ -691,14 +777,14 @@ It is possible to specify multiple recodings on a single command. Introduce additional recodings with a slash (@samp{/}) to separate them from the previous recodings: @example -recode - @var{a} (2 = 22) (else = 99) +recode + @var{a} (2 = 22) (else = 99) /@var{b} (1 = 3) into @var{z} . @end example @noindent Here we have two recodings. The first affects the source variable @var{a} and recodes in-place the value 2 into 22 and all other values to 99. -The second recoding copies the values of @var{b} into the variable @var{z}, +The second recoding copies the values of @var{b} into the variable @var{z}, changing any instances of 1 into 3. @node SORT CASES @@ -714,7 +800,8 @@ variables. Specify @subcmd{BY} and a list of variables to sort by. By default, variables are sorted in ascending order. To override sort order, specify @subcmd{(D)} or -@subcmd{(DOWN)} after a list of variables to get descending order, or @subcmd{(A)} or @subcmd{(UP)} +@subcmd{(DOWN)} after a list of variables to get descending order, or @subcmd{(A)} +or @subcmd{(UP)} for ascending order. These apply to all the listed variables up until the preceding @subcmd{(A)}, @subcmd{(D)}, @subcmd{(UP)} or @subcmd{(DOWN)}. @@ -730,4 +817,7 @@ cases. If workspace is exhausted, it falls back to a merge sort algorithm that involves creates numerous temporary files. -@cmd{SORT CASES} may not be specified following @cmd{TEMPORARY}. +@cmd{SORT CASES} may not be specified following @cmd{TEMPORARY}. + +@subsection Sorting Example +