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 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 Specify OFF to disable @cmd{SPLIT FILE} and resume analysis of the
 231 entire active file as a single group of data.
 232
 233 When @cmd{SPLIT FILE} is specified after @cmd{TEMPORARY}, it affects only
 234 the next procedure (@pxref{TEMPORARY}).
 235
 236 @node TEMPORARY, WEIGHT, SPLIT FILE, Data Selection
 237 @section TEMPORARY
 238 @vindex TEMPORARY
 239
 240 @display
 241 TEMPORARY.
 242 @end display
 243
 244 @cmd{TEMPORARY} is used to make the effects of transformations
 245 following its execution temporary.  These transformations will
 246 affect only the execution of the next procedure or procedure-like
 247 command.  Their effects will not be saved to the active file.
 248
 249 The only specification on @cmd{TEMPORARY} is the command name.
 250
 251 @cmd{TEMPORARY} may not appear within a @cmd{DO IF} or @cmd{LOOP}
 252 construct.  It may appear only once between procedures and
 253 procedure-like commands.
 254
 255 Scratch variables cannot be used following @cmd{TEMPORARY}.
 256
 257 An example may help to clarify:
 258
 259 @example
 260 DATA LIST /X 1-2.
 261 BEGIN DATA.
 262  2
 263  4
 264 10
 265 15
 266 20
 267 24
 268 END DATA.
 269 COMPUTE X=X/2.
 270 TEMPORARY.
 271 COMPUTE X=X+3.
 272 DESCRIPTIVES X.
 273 DESCRIPTIVES X.
 274 @end example
 275
 276 The data read by the first @cmd{DESCRIPTIVES} are 4, 5, 8,
 277 10.5, 13, 15.  The data read by the first @cmd{DESCRIPTIVES} are 1, 2,
 278 5, 7.5, 10, 12.
 279
 280 @node WEIGHT,  , TEMPORARY, Data Selection
 281 @section WEIGHT
 282 @vindex WEIGHT
 283
 284 @display
 285 WEIGHT BY var_name.
 286 WEIGHT OFF.
 287 @end display
 288
 289 @cmd{WEIGHT} assigns cases varying weights,
 290 changing the frequency distribution of the active file.  Execution of
 291 @cmd{WEIGHT} is delayed until data have been read.
 292
 293 If a variable name is specified, @cmd{WEIGHT} causes the values of that
 294 variable to be used as weighting factors for subsequent statistical
 295 procedures.  Use of keyword BY is optional but recommended.  Weighting
 296 variables must be numeric.  Scratch variables may not be used for
 297 weighting (@pxref{Scratch Variables}).
 298
 299 When OFF is specified, subsequent statistical procedures will weight all
 300 cases equally.
 301
 302 A positive integer weighting factor @var{w} on a case will yield the
 303 same statistical output as would replicating the case @var{w} times.
 304 A weighting factor of 0 is treated for statistical purposes as if the
 305 case did not exist in the input.  Weighting values need not be
 306 integers, but negative and system-missing values for the weighting
 307 variable are interpreted as weighting factors of 0.  User-missing
 308 values are not treated specially.
 309
 310 When @cmd{WEIGHT} is specified after @cmd{TEMPORARY}, it affects only
 311 the next procedure (@pxref{TEMPORARY}).
 312
 313 @cmd{WEIGHT} does not cause cases in the active file to be replicated in
 314 memory.
 315 @setfilename ignored