doc/data-selection.texi

   1 @node Data Selection, Conditionals and Looping, Data Manipulation, Top
   2 @chapter Selecting data for analysis
   3
   4 This chapter documents PSPP commands that temporarily or permanently
   5 select data records from the active file for analysis.
   6
   7 @menu
   8 * FILTER::                      Exclude cases based on a variable.
   9 * N OF CASES::                  Limit the size of the active file.
  10 * PROCESS IF::                  Temporarily excluding cases.
  11 * SAMPLE::                      Select a specified proportion of cases.
  12 * SELECT IF::                   Permanently delete selected cases.
  13 * SPLIT FILE::                  Do multiple analyses with one command.
  14 * TEMPORARY::                   Make transformations' effects temporary.
  15 * WEIGHT::                      Weight cases by a variable.
  16 @end menu
  17
  18 @node FILTER, N OF CASES, Data Selection, Data Selection
  19 @section FILTER
  20 @vindex FILTER
  21
  22 @display
  23 FILTER BY var_name.
  24 FILTER OFF.
  25 @end display
  26
  27 @cmd{FILTER} allows a boolean-valued variable to be used to select
  28 cases from the data stream for processing.
  29
  30 To set up filtering, specify BY and a variable name.  Keyword
  31 BY is optional but recommended.  Cases which have a zero or system- or
  32 user-missing value are excluded from analysis, but not deleted from the
  33 data stream.  Cases with other values are analyzed.
  34 To filter based on a different condition, use
  35 transformations such as @cmd{COMPUTE} or @cmd{RECODE} to compute a
  36 filter variable of the required form, then specify that variable on
  37 @cmd{FILTER}.
  38
  39 @code{FILTER OFF} turns off case filtering.
  40
  41 Filtering takes place immediately before cases pass to a procedure for
  42 analysis.  Only one filter variable may be active at a time.  Normally,
  43 case filtering continues until it is explicitly turned off with @code{FILTER
  44 OFF}.  However, if @cmd{FILTER} is placed after TEMPORARY, it filters only
  45 the next procedure or procedure-like command.
  46
  47 @node N OF CASES, PROCESS IF, FILTER, Data Selection
  48 @section N OF CASES
  49 @vindex N OF CASES
  50
  51 @display
  52 N [OF CASES] num_of_cases [ESTIMATED].
  53 @end display
  54
  55 Sometimes you may want to disregard cases of your input.  @cmd{N} can
  56 do this.  @code{N 100} tells PSPP to disregard all cases after the
  57 first 100.
  58
  59 If the value specified for @cmd{N} is greater than the number of cases
  60 read in, the value is ignored.
  61
  62 @cmd{N} does not discard cases or prevent them from being read.  It
  63 just causes cases beyond the last one specified to be ignored by data
  64 analysis commands.
  65
  66 A later @cmd{N} command can increase or decrease the number of cases
  67 selected.  (To select all the cases without knowing how many there are,
  68 specify a very high number: 100000 or whatever you think is large enough.)
  69
  70 Transformation procedures performed after @cmd{N} is executed
  71 @emph{do} cause cases to be discarded.
  72
  73 @cmd{SAMPLE}, @cmd{PROCESS IF}, and @cmd{SELECT IF} have
  74 precedence over @cmd{N}---the same results are obtained by both of the
  75 following fragments, given the same random number seeds:
  76
  77 @example
  78 @i{@dots{}set up, read in data@dots{}}
  79 N 100.
  80 SAMPLE .5.
  81 @i{@dots{}analyze data@dots{}}
  82
  83 @i{@dots{}set up, read in data@dots{}}
  84 SAMPLE .5.
  85 N 100.
  86 @i{@dots{}analyze data@dots{}}
  87 @end example
  88
  89 Both fragments above first randomly sample approximately half of the
  90 cases, then select the first 100 of those sampled.
  91
  92 @cmd{N} with the @code{ESTIMATED} keyword gives an
  93 estimated number of cases before @cmd{DATA LIST} or another command to
  94 read in data.  @code{ESTIMATED} never limits the number of cases
  95 processed by procedures.  PSPP currently does not make use of
  96 case count estimates.
  97
  98 When @cmd{N} is specified after @cmd{TEMPORARY}, it affects only
  99 the next procedure (@pxref{TEMPORARY}).
 100
 101 @node PROCESS IF, SAMPLE, N OF CASES, Data Selection
 102 @section PROCESS IF
 103 @vindex PROCESS IF
 104
 105 @example
 106 PROCESS IF expression.
 107 @end example
 108
 109 @cmd{PROCESS IF} temporarily eliminates cases from the
 110 data stream.  Its effects are active only through the execution of the
 111 next procedure or procedure-like command.
 112
 113 Specify a boolean expression (@pxref{Expressions}).  If the value of the
 114 expression is true for a particular case, the case will be analyzed.  If
 115 the expression has a false or missing value, then the case will be
 116 deleted from the data stream for this procedure only.
 117
 118 Regardless of its placement relative to other commands, @cmd{PROCESS IF}
 119 always takes effect immediately before data passes to the procedure.
 120 Only one @cmd{PROCESS IF} command may be in effect at any given time.
 121
 122 The effects of @cmd{PROCESS IF} are similar, but not identical, to the
 123 effects of executing @cmd{TEMPORARY}, then @cmd{SELECT IF}
 124 (@pxref{SELECT IF}).
 125
 126 The filtering performed by @cmd{PROCESS IF} takes place immediately
 127 before cases pass to a procedure for analysis.  Because @cmd{PROCESS
 128 IF} affects only a single procedure, its placement relative to
 129 @cmd{TEMPORARY} is unimportant.
 130
 131 @cmd{PROCESS IF} is deprecated.  It is included for compatibility with
 132 old command files.  New syntax files should use @cmd{SELECT IF} or
 133 @cmd{FILTER} instead.
 134
 135 @node SAMPLE, SELECT IF, PROCESS IF, Data Selection
 136 @section SAMPLE
 137 @vindex SAMPLE
 138
 139 @display
 140 SAMPLE num1 [FROM num2].
 141 @end display
 142
 143 @cmd{SAMPLE} randomly samples a proportion of the cases in the active
 144 file.  Unless it follows @cmd{TEMPORARY}, it operates as a
 145 transformation, permanently removing cases from the active file.
 146
 147 The proportion to sample can be expressed as a single number between 0
 148 and 1.  If @code{k} is the number specified, and @code{N} is the number
 149 of currently-selected cases in the active file, then after
 150 @code{SAMPLE @var{k}.}, approximately @code{k*N} cases will be
 151 selected.
 152
 153 The proportion to sample can also be specified in the style @code{SAMPLE
 154 @var{m} FROM @var{N}}.  With this style, cases are selected as follows:
 155
 156 @enumerate
 157 @item
 158 If @var{N} is equal to the number of currently-selected cases in the
 159 active file, exactly @var{m} cases will be selected.
 160
 161 @item
 162 If @var{N} is greater than the number of currently-selected cases in the
 163 active file, an equivalent proportion of cases will be selected.
 164
 165 @item
 166 If @var{N} is less than the number of currently-selected cases in the
 167 active, exactly @var{m} cases will be selected @emph{from the first
 168 @var{N} cases in the active file.}
 169 @end enumerate
 170
 171 @cmd{SAMPLE} and @cmd{SELECT IF} are performed in
 172 the order specified by the syntax file.
 173
 174 @cmd{SAMPLE} is always performed before @code{N OF CASES}, regardless
 175 of ordering in the syntax file (@pxref{N OF CASES}).
 176
 177 The same values for @cmd{SAMPLE} may result in different samples.  To
 178 obtain the same sample, use the @code{SET} command to set the random
 179 number seed to the same value before each @cmd{SAMPLE}.  Different
 180 samples may still result when the file is processed on systems with
 181 differing endianness or floating-point formats.  By default, the
 182 random number seed is based on the system time.
 183
 184 @node SELECT IF, SPLIT FILE, SAMPLE, Data Selection
 185 @section SELECT IF
 186 @vindex SELECT IF
 187
 188 @display
 189 SELECT IF expression.
 190 @end display
 191
 192 @cmd{SELECT IF} selects cases for analysis based on the value of a
 193 boolean expression.  Cases not selected are permanently eliminated
 194 from the active file, unless @cmd{TEMPORARY} is in effect
 195 (@pxref{TEMPORARY}).
 196
 197 Specify a boolean expression (@pxref{Expressions}).  If the value of the
 198 expression is true for a particular case, the case will be analyzed.  If
 199 the expression has a false or missing value, then the case will be
 200 deleted from the data stream.
 201
 202 Place @cmd{SELECT IF} as early in the command file as
 203 possible.  Cases that are deleted early can be processed more
 204 efficiently in time and space.
 205
 206 When @cmd{SELECT IF} is specified following @cmd{TEMPORARY}
 207 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
 208 (@pxref{LAG}).
 209
 210 @node SPLIT FILE, TEMPORARY, SELECT IF, Data Selection
 211 @section SPLIT FILE
 212 @vindex SPLIT FILE
 213
 214 @display
 215 Two possible syntaxes:
 216         SPLIT FILE BY var_list.
 217         SPLIT FILE OFF.
 218 @end display
 219
 220 @cmd{SPLIT FILE} allows multiple sets of data present in one data
 221 file to be analyzed separately using single statistical procedure
 222 commands.
 223
 224 Specify a list of variable names to analyze multiple sets of
 225 data separately.  Groups of adjacent cases having the same values for these
 226 variables are analyzed by statistical procedure commands as one group.
 227 An independent analysis is carried out for each group of cases, and the
 228 variable values for the group are printed along with the analysis.
 229
 230 Groups are formed only by @emph{adjacent} cases.  To create a split
 231 using a variable where like values are not adjacent in the working file,
 232 you should first sort the data by that variable (@pxref{SORT CASES}).
 233
 234 Specify OFF to disable @cmd{SPLIT FILE} and resume analysis of the
 235 entire active file as a single group of data.
 236
 237 When @cmd{SPLIT FILE} is specified after @cmd{TEMPORARY}, it affects only
 238 the next procedure (@pxref{TEMPORARY}).
 239
 240 @node TEMPORARY, WEIGHT, SPLIT FILE, Data Selection
 241 @section TEMPORARY
 242 @vindex TEMPORARY
 243
 244 @display
 245 TEMPORARY.
 246 @end display
 247
 248 @cmd{TEMPORARY} is used to make the effects of transformations
 249 following its execution temporary.  These transformations will
 250 affect only the execution of the next procedure or procedure-like
 251 command.  Their effects will not be saved to the active file.
 252
 253 The only specification on @cmd{TEMPORARY} is the command name.
 254
 255 @cmd{TEMPORARY} may not appear within a @cmd{DO IF} or @cmd{LOOP}
 256 construct.  It may appear only once between procedures and
 257 procedure-like commands.
 258
 259 Scratch variables cannot be used following @cmd{TEMPORARY}.
 260
 261 An example may help to clarify:
 262
 263 @example
 264 DATA LIST /X 1-2.
 265 BEGIN DATA.
 266  2
 267  4
 268 10
 269 15
 270 20
 271 24
 272 END DATA.
 273 COMPUTE X=X/2.
 274 TEMPORARY.
 275 COMPUTE X=X+3.
 276 DESCRIPTIVES X.
 277 DESCRIPTIVES X.
 278 @end example
 279
 280 The data read by the first @cmd{DESCRIPTIVES} are 4, 5, 8,
 281 10.5, 13, 15.  The data read by the first @cmd{DESCRIPTIVES} are 1, 2,
 282 5, 7.5, 10, 12.
 283
 284 @node WEIGHT,  , TEMPORARY, Data Selection
 285 @section WEIGHT
 286 @vindex WEIGHT
 287
 288 @display
 289 WEIGHT BY var_name.
 290 WEIGHT OFF.
 291 @end display
 292
 293 @cmd{WEIGHT} assigns cases varying weights,
 294 changing the frequency distribution of the active file.  Execution of
 295 @cmd{WEIGHT} is delayed until data have been read.
 296
 297 If a variable name is specified, @cmd{WEIGHT} causes the values of that
 298 variable to be used as weighting factors for subsequent statistical
 299 procedures.  Use of keyword BY is optional but recommended.  Weighting
 300 variables must be numeric.  Scratch variables may not be used for
 301 weighting (@pxref{Scratch Variables}).
 302
 303 When OFF is specified, subsequent statistical procedures will weight all
 304 cases equally.
 305
 306 A positive integer weighting factor @var{w} on a case will yield the
 307 same statistical output as would replicating the case @var{w} times.
 308 A weighting factor of 0 is treated for statistical purposes as if the
 309 case did not exist in the input.  Weighting values need not be
 310 integers, but negative and system-missing values for the weighting
 311 variable are interpreted as weighting factors of 0.  User-missing
 312 values are not treated specially.
 313
 314 When @cmd{WEIGHT} is specified after @cmd{TEMPORARY}, it affects only
 315 the next procedure (@pxref{TEMPORARY}).
 316
 317 @cmd{WEIGHT} does not cause cases in the active file to be replicated in
 318 memory.
 319 @setfilename ignored