pintos-os.org Git - pspp/blob - doc/data-selection.texi

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