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