better tests
[pspp] / doc / combining.texi
1 @c PSPP - a program for statistical analysis.
2 @c Copyright (C) 2017, 2020 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 Combining Data Files
11 @chapter Combining Data Files
12
13 This chapter describes commands that allow data from system files,
14 portable files, and open datasets to be combined to
15 form a new active dataset.  These commands can combine data files in the
16 following ways:
17
18 @itemize
19 @item
20 @cmd{ADD FILES} interleaves or appends the cases from each input file.
21 It is used with input files that have variables in common, but
22 distinct sets of cases.
23
24 @item
25 @cmd{MATCH FILES} adds the data together in cases that match across
26 multiple input files.  It is used with input files that have cases in
27 common, but different information about each case.
28
29 @item
30 @cmd{UPDATE} updates a master data file from data in a set of
31 transaction files.  Each case in a transaction data file modifies a
32 matching case in the primary data file, or it adds a new case if no
33 matching case can be found.
34 @end itemize
35
36 These commands share the majority of their syntax, which is described
37 in the following section, followed by one section for each command
38 that describes its specific syntax and semantics.
39
40 @menu
41 * Combining Files Common Syntax::
42 * ADD FILES::                   Interleave cases from multiple files.
43 * MATCH FILES::                 Merge cases from multiple files.
44 * UPDATE::                      Update cases using transactional data.
45 @end menu
46
47 @node Combining Files Common Syntax
48 @section Common Syntax
49
50 @display
51 Per input file:
52         /FILE=@{*,'@var{file_name}'@}
53         [/RENAME=(@var{src_names}=@var{target_names})@dots{}]
54         [/IN=@var{var_name}]
55         [/SORT]
56
57 Once per command:
58         /BY @var{var_list}[(@{D|A@})] [@var{var_list}[(@{D|A@}]]@dots{}
59         [/DROP=@var{var_list}]
60         [/KEEP=@var{var_list}]
61         [/FIRST=@var{var_name}]
62         [/LAST=@var{var_name}]
63         [/MAP]
64 @end display
65
66 This section describes the syntactical features in common among the
67 @cmd{ADD FILES}, @cmd{MATCH FILES}, and @cmd{UPDATE} commands.  The
68 following sections describe details specific to each command.
69
70 Each of these commands reads two or more input files and combines them.
71 The command's output becomes the new active dataset.
72 None of the commands actually change the input files.
73 Therefore, if you want the changes to become permanent, you must explicitly
74 save them using an appropriate procedure or transformation (@pxref{System and Portable File IO}).
75
76 The syntax of each command begins with a specification of the files to
77 be read as input.  For each input file, specify FILE with a system
78 file or portable file's name as a string, a dataset (@pxref{Datasets})
79 or file handle name, (@pxref{File Handles}), or an asterisk (@samp{*})
80 to use the active dataset as input.  Use of portable files on @subcmd{FILE} is a
81 @pspp{} extension.
82
83 At least two @subcmd{FILE} subcommands must be specified.  If the active dataset
84 is used as an input source, then @cmd{TEMPORARY} must not be in
85 effect.
86
87 Each @subcmd{FILE} subcommand may be followed by any number of @subcmd{RENAME}
88 subcommands that specify a parenthesized group or groups of variable
89 names as they appear in the input file, followed by those variables'
90 new names, separated by an equals sign (@subcmd{=}),
91 @i{e.g.} @subcmd{/RENAME=(OLD1=NEW1)(OLD2=NEW2)}.  To rename a single
92 variable, the parentheses may be omitted: @subcmd{/RENAME=@var{old}=@var{new}}.
93 Within a parenthesized group, variables are renamed simultaneously, so
94 that @subcmd{/RENAME=(@var{A} @var{B}=@var{B} @var{A})} exchanges the
95 names of variables @var{A} and @var{B}.
96 Otherwise, renaming occurs in left-to-right order.
97
98 Each @subcmd{FILE} subcommand may optionally be followed by a single @subcmd{IN}
99 subcommand, which creates a numeric variable with the specified name
100 and format F1.0.  The IN variable takes value 1 in an output case if
101 the given input file contributed to that output case, and 0 otherwise.
102 The @subcmd{DROP}, @subcmd{KEEP}, and @subcmd{RENAME} subcommands have no effect on IN variables.
103
104 If @subcmd{BY} is used (see below), the @subcmd{SORT} keyword must be specified after a
105 @subcmd{FILE} if that input file is not already sorted on the @subcmd{BY} variables.
106 When @subcmd{SORT} is specified, @pspp{} sorts the input file's data on the @subcmd{BY}
107 variables before it applies it to the command.  When @subcmd{SORT} is used, @subcmd{BY}
108 is required.  @subcmd{SORT} is a @pspp{} extension.
109
110 @pspp{} merges the dictionaries of all of the input files to form the
111 dictionary of the new active dataset, like so:
112
113 @itemize @bullet
114 @item
115 The variables in the new active dataset are the union of all the input files'
116 variables, matched based on their name.  When a single input file
117 contains a variable with a given name, the output file will contain
118 exactly that variable.  When more than one input file contains a
119 variable with a given name, those variables must all have the same
120 type (numeric or string) and, for string variables, the same width.
121 Variables are matched after renaming with the @subcmd{RENAME} subcommand.
122 Thus, @subcmd{RENAME} can be used to resolve conflicts.
123
124 @item
125 The variable label for each output variable is taken from the first
126 specified input file that has a variable label for that variable, and
127 similarly for value labels and missing values.
128
129 @item
130 The file label of the new active dataset (@pxref{FILE LABEL}) is that of the
131 first specified @subcmd{FILE} that has a file label.
132
133 @item
134 The documents in the new active dataset (@pxref{DOCUMENT}) are the
135 concatenation of all the input files' documents, in the order in which
136 the @subcmd{FILE} subcommands are specified.
137
138 @item
139 If all of the input files are weighted on the same variable, then the
140 new active dataset is weighted on that variable.  Otherwise, the new
141 active dataset is not weighted.
142 @end itemize
143
144 The remaining subcommands apply to the output file as a whole, rather
145 than to individual input files.  They must be specified at the end of
146 the command specification, following all of the @subcmd{FILE} and related
147 subcommands.  The most important of these subcommands is @subcmd{BY}, which
148 specifies a set of one or more variables that may be used to find
149 corresponding cases in each of the input files.  The variables
150 specified on @subcmd{BY} must be present in all of the input files.
151 Furthermore, if any of the input files are not sorted on the @subcmd{BY}
152 variables, then @subcmd{SORT} must be specified for those input files.
153
154 The variables listed on @subcmd{BY} may include (A) or (D) annotations to
155 specify ascending or descending sort order.  @xref{SORT CASES}, for
156 more details on this notation.  Adding (A) or (D) to the @subcmd{BY} subcommand
157 specification is a @pspp{} extension.
158
159 The @subcmd{DROP} subcommand can be used to specify a list of variables to
160 exclude from the output.  By contrast, the @subcmd{KEEP} subcommand can be used
161 to specify variables to include in the output; all variables not
162 listed are dropped.  @subcmd{DROP} and @subcmd{KEEP} are executed in left-to-right order
163 and may be repeated any number of times.  @subcmd{DROP} and @subcmd{KEEP} do not affect
164 variables created by the @subcmd{IN}, @subcmd{FIRST}, and @subcmd{LAST} subcommands, which are
165 always included in the new active dataset, but they can be used to drop
166 @subcmd{BY} variables.
167
168 The @subcmd{FIRST} and @subcmd{LAST} subcommands are optional.  They may only be
169 specified on @cmd{MATCH FILES} and @cmd{ADD FILES}, and only when @subcmd{BY}
170 is used.  @subcmd{FIRST} and @subcmd{LIST} each adds a numeric variable to the new
171 active dataset, with the name given as the subcommand's argument and F1.0
172 print and write formats.  The value of the @subcmd{FIRST} variable is 1 in the
173 first output case with a given set of values for the @subcmd{BY} variables, and
174 0 in other cases.  Similarly, the @subcmd{LAST} variable is 1 in the last case
175 with a given of @subcmd{BY} values, and 0 in other cases.
176
177 When any of these commands creates an output case, variables that are
178 only in files that are not present for the current case are set to the
179 system-missing value for numeric variables or spaces for string
180 variables.
181
182 These commands may combine any number of files, limited only by the
183 machine's memory.
184
185 @node ADD FILES
186 @section ADD FILES
187 @vindex ADD FILES
188
189 @display
190 ADD FILES
191
192 Per input file:
193         /FILE=@{*,'@var{file_name}'@}
194         [/RENAME=(@var{src_names}=@var{target_names})@dots{}]
195         [/IN=@var{var_name}]
196         [/SORT]
197
198 Once per command:
199         [/BY @var{var_list}[(@{D|A@})] [@var{var_list}[(@{D|A@})]@dots{}]]
200         [/DROP=@var{var_list}]
201         [/KEEP=@var{var_list}]
202         [/FIRST=@var{var_name}]
203         [/LAST=@var{var_name}]
204         [/MAP]
205 @end display
206
207 @cmd{ADD FILES} adds cases from multiple input files.  The output,
208 which replaces the active dataset, consists all of the cases in all of
209 the input files.
210
211 @subcmd{ADD FILES} shares the bulk of its syntax with other @pspp{} commands for
212 combining multiple data files.  @xref{Combining Files Common Syntax},
213 above, for an explanation of this common syntax.
214
215 When @subcmd{BY} is not used, the output of @subcmd{ADD FILES} consists of all the cases
216 from the first input file specified, followed by all the cases from
217 the second file specified, and so on.  When @subcmd{BY} is used, the output is
218 additionally sorted on the @subcmd{BY} variables.
219
220 When @subcmd{ADD FILES} creates an output case, variables that are not part of
221 the input file from which the case was drawn are set to the
222 system-missing value for numeric variables or spaces for string
223 variables.
224
225 @node MATCH FILES
226 @section MATCH FILES
227 @vindex MATCH FILES
228
229 @display
230 MATCH FILES
231
232 Per input file:
233         /@{FILE,TABLE@}=@{*,'@var{file_name}'@}
234         [/RENAME=(@var{src_names}=@var{target_names})@dots{}]
235         [/IN=@var{var_name}]
236         [/SORT]
237
238 Once per command:
239         /BY @var{var_list}[(@{D|A@}] [@var{var_list}[(@{D|A@})]@dots{}]
240         [/DROP=@var{var_list}]
241         [/KEEP=@var{var_list}]
242         [/FIRST=@var{var_name}]
243         [/LAST=@var{var_name}]
244         [/MAP]
245 @end display
246
247 @cmd{MATCH FILES} merges sets of corresponding cases in multiple
248 input files into single cases in the output, combining their data.
249
250 @cmd{MATCH FILES} shares the bulk of its syntax with other @pspp{} commands for
251 combining multiple data files.  @xref{Combining Files Common Syntax},
252 above, for an explanation of this common syntax.
253
254 How @cmd{MATCH FILES} matches up cases from the input files depends on
255 whether @subcmd{BY} is specified:
256
257 @itemize @bullet
258 @item
259 If @subcmd{BY} is not used, @cmd{MATCH FILES} combines the first case from each input
260 file to produce the first output case, then the second case from each
261 input file for the second output case, and so on.  If some input files
262 have fewer cases than others, then the shorter files do not contribute
263 to cases output after their input has been exhausted.
264
265 @item
266 If @subcmd{BY} is used, @cmd{MATCH FILES} combines cases from each input file that
267 have identical values for the @subcmd{BY} variables.
268
269 When @subcmd{BY} is used, @subcmd{TABLE} subcommands may be used to introduce @dfn{table
270 lookup file}.  @subcmd{TABLE} has same syntax as @subcmd{FILE}, and the @subcmd{RENAME}, @subcmd{IN}, and
271 @subcmd{SORT} subcommands may follow a @subcmd{TABLE} in the same way as @subcmd{FILE}.
272 Regardless of the number of @subcmd{TABLE}s, at least one @subcmd{FILE} must specified.
273 Table lookup files are treated in the same way as other input files
274 for most purposes and, in particular, table lookup files must be
275 sorted on the @subcmd{BY} variables or the @subcmd{SORT} subcommand must be specified
276 for that @subcmd{TABLE}.
277
278 Cases in table lookup files are not consumed after they have been used
279 once.  This means that data in table lookup files can correspond to
280 any number of cases in @subcmd{FILE} input files.  Table lookup files are
281 analogous to lookup tables in traditional relational database systems.
282
283 If a table lookup file contains more than one case with a given set of
284 @subcmd{BY} variables, only the first case is used.
285 @end itemize
286
287 When @cmd{MATCH FILES} creates an output case, variables that are only in
288 files that are not present for the current case are set to the
289 system-missing value for numeric variables or spaces for string
290 variables.
291
292 @node UPDATE
293 @section UPDATE
294 @vindex UPDATE
295
296 @display
297 UPDATE
298
299 Per input file:
300         /FILE=@{*,'@var{file_name}'@}
301         [/RENAME=(@var{src_names}=@var{target_names})@dots{}]
302         [/IN=@var{var_name}]
303         [/SORT]
304
305 Once per command:
306         /BY @var{var_list}[(@{D|A@})] [@var{var_list}[(@{D|A@})]]@dots{}
307         [/DROP=@var{var_list}]
308         [/KEEP=@var{var_list}]
309         [/MAP]
310 @end display
311
312 @cmd{UPDATE} updates a @dfn{master file} by applying modifications
313 from one or more @dfn{transaction files}.
314
315 @cmd{UPDATE} shares the bulk of its syntax with other @pspp{} commands for
316 combining multiple data files.  @xref{Combining Files Common Syntax},
317 above, for an explanation of this common syntax.
318
319 At least two @subcmd{FILE} subcommands must be specified.  The first @subcmd{FILE}
320 subcommand names the master file, and the rest name transaction files.
321 Every input file must either be sorted on the variables named on the
322 @subcmd{BY} subcommand, or the @subcmd{SORT} subcommand must be used just after the @subcmd{FILE}
323 subcommand for that input file.
324
325 @cmd{UPDATE} uses the variables specified on the @subcmd{BY} subcommand, which is
326 required, to attempt to match each case in a transaction file with a
327 case in the master file:
328
329 @itemize @bullet
330 @item
331 When a match is found, then the values of the variables present in the
332 transaction file replace those variables' values in the new active
333 file.  If there are matching cases in more than more transaction file,
334 @pspp{} applies the replacements from the first transaction file, then
335 from the second transaction file, and so on.  Similarly, if a single
336 transaction file has cases with duplicate @subcmd{BY} values, then those are
337 applied in order to the master file.
338
339 When a variable in a transaction file has a missing value or when a string
340 variable's value is all blanks, that value is never used to update the
341 master file.
342
343 @item
344 If a case in the master file has no matching case in any transaction
345 file, then it is copied unchanged to the output.
346
347 @item
348 If a case in a transaction file has no matching case in the master
349 file, then it causes a new case to be added to the output, initialized
350 from the values in the transaction file.
351 @end itemize