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".
11 @chapter Selecting data for analysis
13 This chapter documents @pspp{} commands that temporarily or permanently
14 select data records from the active dataset for analysis.
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.
31 FILTER BY @var{var_name}.
35 @cmd{FILTER} allows a boolean-valued variable to be used to select
36 cases from the data stream for processing.
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
47 @code{FILTER OFF} turns off case filtering.
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.
60 N [OF CASES] @var{num_of_cases} [ESTIMATED].
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
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.
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.
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
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.
94 SAMPLE @var{num1} [FROM @var{num2}].
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.
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
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:
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.
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.
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.}
125 @cmd{SAMPLE} and @cmd{SELECT IF} are performed in
126 the order specified by the syntax file.
128 @cmd{SAMPLE} is always performed before @code{N OF CASES}, regardless
129 of ordering in the syntax file (@pxref{N OF CASES}).
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.
143 SELECT IF @var{expression}.
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
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.
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.
160 When @cmd{SELECT IF} is specified following @cmd{TEMPORARY}
161 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
169 SPLIT FILE [@{LAYERED, SEPARATE@}] BY @var{var_list}.
173 @cmd{SPLIT FILE} allows multiple sets of data present in one data
174 file to be analyzed separately using single statistical procedure
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.
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
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}).
191 Specify @subcmd{OFF} to disable @cmd{SPLIT FILE} and resume analysis of the
192 entire active dataset as a single group of data.
194 When @cmd{SPLIT FILE} is specified after @cmd{TEMPORARY}, it affects only
195 the next procedure (@pxref{TEMPORARY}).
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.
210 The only specification on @cmd{TEMPORARY} is the command name.
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.
216 Scratch variables cannot be used following @cmd{TEMPORARY}.
218 An example may help to clarify:
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,
249 WEIGHT BY @var{var_name}.
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.
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}).
263 When @subcmd{OFF} is specified, subsequent statistical procedures will weight all
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.
274 When @cmd{WEIGHT} is specified after @cmd{TEMPORARY}, it affects only
275 the next procedure (@pxref{TEMPORARY}).
277 @cmd{WEIGHT} does not cause cases in the active dataset to be
278 replicated in memory.