variable-parser: Rewrite parse_DATA_LIST_vars().
[pspp] / 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.