doc/data-selection.texi

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