Improve error messages for missing subcommands.
[pspp] / doc / statistics.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 Statistics
11 @chapter Statistics
12
13 This chapter documents the statistical procedures that @pspp{} supports so
14 far.
15
16 @menu
17 * DESCRIPTIVES::                Descriptive statistics.
18 * FREQUENCIES::                 Frequency tables.
19 * EXAMINE::                     Testing data for normality.
20 * GRAPH::                       Plot data.
21 * CORRELATIONS::                Correlation tables.
22 * CROSSTABS::                   Crosstabulation tables.
23 * CTABLES::                     Custom tables.
24 * FACTOR::                      Factor analysis and Principal Components analysis.
25 * GLM::                         Univariate Linear Models.
26 * LOGISTIC REGRESSION::         Bivariate Logistic Regression.
27 * MEANS::                       Average values and other statistics.
28 * NPAR TESTS::                  Nonparametric tests.
29 * T-TEST::                      Test hypotheses about means.
30 * ONEWAY::                      One way analysis of variance.
31 * QUICK CLUSTER::               K-Means clustering.
32 * RANK::                        Compute rank scores.
33 * REGRESSION::                  Linear regression.
34 * RELIABILITY::                 Reliability analysis.
35 * ROC::                         Receiver Operating Characteristic.
36 @end menu
37
38 @node DESCRIPTIVES
39 @section DESCRIPTIVES
40
41 @vindex DESCRIPTIVES
42 @display
43 DESCRIPTIVES
44         /VARIABLES=@var{var_list}
45         /MISSING=@{VARIABLE,LISTWISE@} @{INCLUDE,NOINCLUDE@}
46         /FORMAT=@{LABELS,NOLABELS@} @{NOINDEX,INDEX@} @{LINE,SERIAL@}
47         /SAVE
48         /STATISTICS=@{ALL,MEAN,SEMEAN,STDDEV,VARIANCE,KURTOSIS,
49                      SKEWNESS,RANGE,MINIMUM,MAXIMUM,SUM,DEFAULT,
50                      SESKEWNESS,SEKURTOSIS@}
51         /SORT=@{NONE,MEAN,SEMEAN,STDDEV,VARIANCE,KURTOSIS,SKEWNESS,
52                RANGE,MINIMUM,MAXIMUM,SUM,SESKEWNESS,SEKURTOSIS,NAME@}
53               @{A,D@}
54 @end display
55
56 The @cmd{DESCRIPTIVES} procedure reads the active dataset and outputs
57 linear descriptive statistics requested by the user.  In addition, it can optionally
58 compute Z-scores.
59
60 The @subcmd{VARIABLES} subcommand, which is required, specifies the list of
61 variables to be analyzed.  Keyword @subcmd{VARIABLES} is optional.
62
63 All other subcommands are optional:
64
65 The @subcmd{MISSING} subcommand determines the handling of missing variables.  If
66 @subcmd{INCLUDE} is set, then user-missing values are included in the
67 calculations.  If @subcmd{NOINCLUDE} is set, which is the default, user-missing
68 values are excluded.  If @subcmd{VARIABLE} is set, then missing values are
69 excluded on a variable by variable basis; if @subcmd{LISTWISE} is set, then
70 the entire case is excluded whenever any value in that case has a
71 system-missing or, if @subcmd{INCLUDE} is set, user-missing value.
72
73 The @subcmd{FORMAT} subcommand has no effect.  It is accepted for
74 backward compatibility.
75
76 The @subcmd{SAVE} subcommand causes @cmd{DESCRIPTIVES} to calculate Z scores for all
77 the specified variables.  The Z scores are saved to new variables.
78 Variable names are generated by trying first the original variable name
79 with Z prepended and truncated to a maximum of 8 characters, then the
80 names ZSC000 through ZSC999, STDZ00 through STDZ09, ZZZZ00 through
81 ZZZZ09, ZQZQ00 through ZQZQ09, in that sequence.  In addition, Z score
82 variable names can be specified explicitly on @subcmd{VARIABLES} in the variable
83 list by enclosing them in parentheses after each variable.
84 When Z scores are calculated, @pspp{} ignores @cmd{TEMPORARY},
85 treating temporary transformations as permanent.
86
87 The @subcmd{STATISTICS} subcommand specifies the statistics to be displayed:
88
89 @table @code
90 @item @subcmd{ALL}
91 All of the statistics below.
92 @item @subcmd{MEAN}
93 Arithmetic mean.
94 @item @subcmd{SEMEAN}
95 Standard error of the mean.
96 @item @subcmd{STDDEV}
97 Standard deviation.
98 @item @subcmd{VARIANCE}
99 Variance.
100 @item @subcmd{KURTOSIS}
101 Kurtosis and standard error of the kurtosis.
102 @item @subcmd{SKEWNESS}
103 Skewness and standard error of the skewness.
104 @item @subcmd{RANGE}
105 Range.
106 @item MINIMUM
107 Minimum value.
108 @item MAXIMUM
109 Maximum value.
110 @item SUM
111 Sum.
112 @item DEFAULT
113 Mean, standard deviation of the mean, minimum, maximum.
114 @item SEKURTOSIS
115 Standard error of the kurtosis.
116 @item SESKEWNESS
117 Standard error of the skewness.
118 @end table
119
120 The @subcmd{SORT} subcommand specifies how the statistics should be sorted.  Most
121 of the possible values should be self-explanatory.  @subcmd{NAME} causes the
122 statistics to be sorted by name.  By default, the statistics are listed
123 in the order that they are specified on the @subcmd{VARIABLES} subcommand.
124 The @subcmd{A} and @subcmd{D} settings request an ascending or descending
125 sort order, respectively.
126
127 @subsection Descriptives Example
128
129 The @file{physiology.sav} file contains various physiological data for a sample
130 of persons.   Running the @cmd{DESCRIPTIVES} command on the variables @exvar{height}
131 and @exvar{temperature} with the default options allows one to see simple linear
132 statistics for these two variables.  In @ref{descriptives:ex}, these variables
133 are specfied on the @subcmd{VARIABLES} subcommand and the @subcmd{SAVE} option
134 has been used, to request that Z scores be calculated.
135
136 After the command has completed, this example runs @cmd{DESCRIPTIVES} again, this
137 time on the @exvar{zheight} and @exvar{ztemperature} variables,
138 which are the two normalized (Z-score) variables generated by the
139 first @cmd{DESCRIPTIVES} command.
140
141 @float Example, descriptives:ex
142 @psppsyntax {descriptives.sps}
143 @caption {Running two @cmd{DESCRIPTIVES} commands, one with the @subcmd{SAVE} subcommand}
144 @end float
145
146 @float Screenshot, descriptives:scr
147 @psppimage {descriptives}
148 @caption {The Descriptives dialog box with two variables and Z-Scores option selected}
149 @end float
150
151 In @ref{descriptives:res}, we can see that there are 40 valid data for each of the variables
152 and no missing values.   The mean average of the height and temperature is 16677.12
153 and 37.02 respectively.  The descriptive statistics for temperature seem reasonable.
154 However there is a very high standard deviation for @exvar{height} and a suspiciously
155 low minimum.  This is due to a data entry error in the
156 data (@pxref{Identifying incorrect data}).
157
158 In the second Descriptive Statistics command, one can see that the mean and standard
159 deviation of both Z score variables is 0 and 1 respectively.  All Z score statistics
160 should have these properties since they are normalized versions of the original scores.
161
162 @float Result, descriptives:res
163 @psppoutput {descriptives}
164 @caption {Descriptives statistics including two normalized variables (Z-scores)}
165 @end float
166
167 @node FREQUENCIES
168 @section FREQUENCIES
169
170 @vindex FREQUENCIES
171 @display
172 FREQUENCIES
173         /VARIABLES=@var{var_list}
174         /FORMAT=@{TABLE,NOTABLE,LIMIT(@var{limit})@}
175                 @{AVALUE,DVALUE,AFREQ,DFREQ@}
176         /MISSING=@{EXCLUDE,INCLUDE@}
177         /STATISTICS=@{DEFAULT,MEAN,SEMEAN,MEDIAN,MODE,STDDEV,VARIANCE,
178                      KURTOSIS,SKEWNESS,RANGE,MINIMUM,MAXIMUM,SUM,
179                      SESKEWNESS,SEKURTOSIS,ALL,NONE@}
180         /NTILES=@var{ntiles}
181         /PERCENTILES=percent@dots{}
182         /HISTOGRAM=[MINIMUM(@var{x_min})] [MAXIMUM(@var{x_max})]
183                    [@{FREQ[(@var{y_max})],PERCENT[(@var{y_max})]@}] [@{NONORMAL,NORMAL@}]
184         /PIECHART=[MINIMUM(@var{x_min})] [MAXIMUM(@var{x_max})]
185                   [@{FREQ,PERCENT@}] [@{NOMISSING,MISSING@}]
186         /BARCHART=[MINIMUM(@var{x_min})] [MAXIMUM(@var{x_max})]
187                   [@{FREQ,PERCENT@}]
188         /ORDER=@{ANALYSIS,VARIABLE@}
189
190
191 (These options are not currently implemented.)
192         /HBAR=@dots{}
193         /GROUPED=@dots{}
194 @end display
195
196 The @cmd{FREQUENCIES} procedure outputs frequency tables for specified
197 variables.
198 @cmd{FREQUENCIES} can also calculate and display descriptive statistics
199 (including median and mode) and percentiles, and various graphical representations
200 of the frequency distribution.
201
202 The @subcmd{VARIABLES} subcommand is the only required subcommand.  Specify the
203 variables to be analyzed.
204
205 The @subcmd{FORMAT} subcommand controls the output format.  It has several
206 possible settings:
207
208 @itemize @subcmd{}
209 @item
210 @subcmd{TABLE}, the default, causes a frequency table to be output for every
211 variable specified.  @subcmd{NOTABLE} prevents them from being output.  @subcmd{LIMIT}
212 with a numeric argument causes them to be output except when there are
213 more than the specified number of values in the table.
214
215 @item
216 Normally frequency tables are sorted in ascending order by value.  This
217 is @subcmd{AVALUE}.  @subcmd{DVALUE} tables are sorted in descending order by value.
218 @subcmd{AFREQ} and @subcmd{DFREQ} tables are sorted in ascending and descending order,
219 respectively, by frequency count.
220 @end itemize
221
222 The @subcmd{MISSING} subcommand controls the handling of user-missing values.
223 When @subcmd{EXCLUDE}, the default, is set, user-missing values are not included
224 in frequency tables or statistics.  When @subcmd{INCLUDE} is set, user-missing
225 are included.  System-missing values are never included in statistics,
226 but are listed in frequency tables.
227
228 The available @subcmd{STATISTICS} are the same as available
229 in @cmd{DESCRIPTIVES} (@pxref{DESCRIPTIVES}), with the addition
230 of @subcmd{MEDIAN}, the data's median
231 value, and MODE, the mode.  (If there are multiple modes, the smallest
232 value is reported.)  By default, the mean, standard deviation of the
233 mean, minimum, and maximum are reported for each variable.
234
235 @cindex percentiles
236 @subcmd{PERCENTILES} causes the specified percentiles to be reported.
237 The percentiles should  be presented at a list of numbers between 0
238 and 100 inclusive.
239 The @subcmd{NTILES} subcommand causes the percentiles to be reported at the
240 boundaries of the data set divided into the specified number of ranges.
241 For instance, @subcmd{/NTILES=4} would cause quartiles to be reported.
242
243 @cindex histogram
244 The @subcmd{HISTOGRAM} subcommand causes the output to include a histogram for
245 each specified numeric variable.  The X axis by default ranges from
246 the minimum to the maximum value observed in the data, but the @subcmd{MINIMUM}
247 and @subcmd{MAXIMUM} keywords can set an explicit range.
248 @footnote{The number of
249 bins is chosen according to the Freedman-Diaconis rule:
250 @math{2 \times IQR(x)n^{-1/3}}, where @math{IQR(x)} is the interquartile range of @math{x}
251 and @math{n} is the number of samples.    Note that
252 @cmd{EXAMINE} uses a different algorithm to determine bin sizes.}
253 Histograms are not created for string variables.
254
255 Specify @subcmd{NORMAL} to superimpose a normal curve on the
256 histogram.
257
258 @cindex piechart
259 The @subcmd{PIECHART} subcommand adds a pie chart for each variable to the data.  Each
260 slice represents one value, with the size of the slice proportional to
261 the value's frequency.  By default, all non-missing values are given
262 slices.
263 The @subcmd{MINIMUM} and @subcmd{MAXIMUM} keywords can be used to limit the
264 displayed slices to a given range of values.
265 The keyword @subcmd{NOMISSING} causes missing values to be omitted from the
266 piechart.  This is the default.
267 If instead, @subcmd{MISSING} is specified, then the pie chart includes
268 a single slice representing all system missing and user-missing cases.
269
270 @cindex bar chart
271 The @subcmd{BARCHART} subcommand produces a bar chart for each variable.
272 The @subcmd{MINIMUM} and @subcmd{MAXIMUM} keywords can be used to omit
273 categories whose counts which lie outside the specified limits.
274 The @subcmd{FREQ} option (default) causes the ordinate to display the frequency
275 of each category, whereas the @subcmd{PERCENT} option displays relative
276 percentages.
277
278 The @subcmd{FREQ} and @subcmd{PERCENT} options on @subcmd{HISTOGRAM} and
279 @subcmd{PIECHART} are accepted but not currently honoured.
280
281 The @subcmd{ORDER} subcommand is accepted but ignored.
282
283 @subsection Frequencies Example
284
285 @ref{frequencies:ex} runs a frequency analysis on the @exvar{sex}
286 and @exvar{occupation} variables from the @file{personnel.sav} file.
287 This is useful to get an general idea of the way in which these nominal
288 variables are distributed.
289
290 @float Example, frequencies:ex
291 @psppsyntax {frequencies.sps}
292 @caption {Running frequencies on the @exvar{sex} and @exvar{occupation} variables}
293 @end float
294
295 If you are using the graphic user interface, the dialog box is set up such that
296 by default, several statistics are calculated.   Some are not particularly useful
297 for categorical variables, so you may want to disable those.
298
299 @float Screenshot, frequencies:scr
300 @psppimage {frequencies}
301 @caption {The frequencies dialog box with the @exvar{sex} and @exvar{occupation} variables selected}
302 @end float
303
304 From @ref{frequencies:res} it is evident that there are 33 males, 21 females and
305 2 persons for whom their sex has not been entered.
306
307 One can also see how many of each occupation there are in the data.
308 When dealing with string variables used as nominal values, running a frequency
309 analysis is useful to detect data input entries.  Notice that
310 one @exvar{occupation} value has been mistyped as ``Scrientist''.  This entry should
311 be corrected, or marked as missing before using the data.
312
313 @float Result, frequencies:res
314 @psppoutput {frequencies}
315 @caption {The relative frequencies of @exvar{sex} and @exvar{occupation}}
316 @end float
317
318 @node EXAMINE
319 @section EXAMINE
320
321 @vindex EXAMINE
322 @cindex Exploratory data analysis
323 @cindex normality, testing
324
325 @display
326 EXAMINE
327         VARIABLES= @var{var1} [@var{var2}] @dots{} [@var{varN}]
328            [BY @var{factor1} [BY @var{subfactor1}]
329              [ @var{factor2} [BY @var{subfactor2}]]
330              @dots{}
331              [ @var{factor3} [BY @var{subfactor3}]]
332             ]
333         /STATISTICS=@{DESCRIPTIVES, EXTREME[(@var{n})], ALL, NONE@}
334         /PLOT=@{BOXPLOT, NPPLOT, HISTOGRAM, SPREADLEVEL[(@var{t})], ALL, NONE@}
335         /CINTERVAL @var{p}
336         /COMPARE=@{GROUPS,VARIABLES@}
337         /ID=@var{identity_variable}
338         /@{TOTAL,NOTOTAL@}
339         /PERCENTILE=[@var{percentiles}]=@{HAVERAGE, WAVERAGE, ROUND, AEMPIRICAL, EMPIRICAL @}
340         /MISSING=@{LISTWISE, PAIRWISE@} [@{EXCLUDE, INCLUDE@}]
341                 [@{NOREPORT,REPORT@}]
342
343 @end display
344
345 The @cmd{EXAMINE} command is used to perform exploratory data analysis.
346 In particular, it is useful for testing how closely a distribution follows a
347 normal distribution, and for finding outliers and extreme values.
348
349 The @subcmd{VARIABLES} subcommand is mandatory.
350 It specifies the dependent variables and optionally variables to use as
351 factors for the analysis.
352 Variables listed before the first @subcmd{BY} keyword (if any) are the
353 dependent variables.
354 The dependent variables may optionally be followed by a list of
355 factors which tell @pspp{} how to break down the analysis for each
356 dependent variable.
357
358 Following the dependent variables, factors may be specified.
359 The factors (if desired) should be preceded by a single @subcmd{BY} keyword.
360 The format for each factor is
361 @display
362 @var{factorvar} [BY @var{subfactorvar}].
363 @end display
364 Each unique combination of the values of  @var{factorvar} and
365 @var{subfactorvar} divide the dataset into @dfn{cells}.
366 Statistics are calculated for each cell
367 and for the entire dataset (unless @subcmd{NOTOTAL} is given).
368
369 The @subcmd{STATISTICS} subcommand specifies which statistics to show.
370 @subcmd{DESCRIPTIVES} produces a table showing some parametric and
371 non-parametrics statistics.
372 @subcmd{EXTREME} produces a table showing the extremities of each cell.
373 A number in parentheses, @var{n} determines
374 how many upper and lower extremities to show.
375 The default number is 5.
376
377 The subcommands @subcmd{TOTAL} and @subcmd{NOTOTAL} are mutually exclusive.
378 If @subcmd{TOTAL} appears, then statistics for the entire dataset
379 as well as for each cell are produced.
380 If @subcmd{NOTOTAL} appears, then statistics are produced only for the cells
381 (unless no factor variables have been given).
382 These subcommands have no effect if there have  been no factor variables
383 specified.
384
385 @cindex boxplot
386 @cindex histogram
387 @cindex npplot
388 @cindex spreadlevel plot
389 The @subcmd{PLOT} subcommand specifies which plots are to be produced if any.
390 Available plots are @subcmd{HISTOGRAM}, @subcmd{NPPLOT},  @subcmd{BOXPLOT} and
391 @subcmd{SPREADLEVEL}.
392 The first three can be used to visualise how closely each cell conforms to a
393 normal distribution, whilst the spread vs.@: level plot can be useful to visualise
394 how the variance differs between factors.
395 Boxplots show you the outliers and extreme values.
396 @footnote{@subcmd{HISTOGRAM} uses Sturges' rule to determine the number of
397 bins, as approximately @math{1 + \log2(n)}, where @math{n} is the number of samples.
398 Note that @cmd{FREQUENCIES} uses a different algorithm to find the bin size.}
399
400 The @subcmd{SPREADLEVEL} plot displays the interquartile range versus the
401 median.  It takes an optional parameter @var{t}, which specifies how the data
402 should be transformed prior to plotting.
403 The given value @var{t} is a power to which the data are raised.  For example, if
404 @var{t} is given as 2, then the square of the data is used.
405 Zero, however is a special value.  If @var{t} is 0 or
406 is omitted, then data are transformed by taking its natural logarithm instead of
407 raising to the power of @var{t}.
408
409 @cindex Shapiro-Wilk
410 When one or more plots are requested, @subcmd{EXAMINE} also performs the
411 Shapiro-Wilk test for each category.
412 There are however a number of provisos:
413 @itemize
414 @item All weight values must be integer.
415 @item The cumulative weight value must be in the range [3, 5000]
416 @end itemize
417
418 The @subcmd{COMPARE} subcommand is only relevant if producing boxplots, and it is only
419 useful there is more than one dependent variable and at least one factor.
420 If
421 @subcmd{/COMPARE=GROUPS} is specified, then one plot per dependent variable is produced,
422 each of which contain boxplots for all the cells.
423 If @subcmd{/COMPARE=VARIABLES} is specified, then one plot per cell is produced,
424 each containing one boxplot per dependent variable.
425 If the @subcmd{/COMPARE} subcommand is omitted, then @pspp{} behaves as if
426 @subcmd{/COMPARE=GROUPS} were given.
427
428 The @subcmd{ID} subcommand is relevant only if @subcmd{/PLOT=BOXPLOT} or
429 @subcmd{/STATISTICS=EXTREME} has been given.
430 If given, it should provide the name of a variable which is to be used
431 to labels extreme values and outliers.
432 Numeric or string variables are permissible.
433 If the @subcmd{ID} subcommand is not given, then the case number is used for
434 labelling.
435
436 The @subcmd{CINTERVAL} subcommand specifies the confidence interval to use in
437 calculation of the descriptives command.  The default is 95%.
438
439 @cindex percentiles
440 The @subcmd{PERCENTILES} subcommand specifies which percentiles are to be calculated,
441 and which algorithm to use for calculating them.  The default is to
442 calculate the 5, 10, 25, 50, 75, 90, 95 percentiles using the
443 @subcmd{HAVERAGE} algorithm.
444
445 The @subcmd{TOTAL} and @subcmd{NOTOTAL} subcommands are mutually exclusive.  If @subcmd{NOTOTAL}
446 is given and factors have been specified in the @subcmd{VARIABLES} subcommand,
447 then statistics for the unfactored dependent variables are
448 produced in addition to the factored variables.  If there are no
449 factors specified then @subcmd{TOTAL} and @subcmd{NOTOTAL} have no effect.
450
451
452 The following example generates descriptive statistics and histograms for
453 two variables @var{score1} and @var{score2}.
454 Two factors are given, @i{viz}: @var{gender} and @var{gender} BY @var{culture}.
455 Therefore, the descriptives and histograms are generated for each
456 distinct  value
457 of @var{gender} @emph{and} for each distinct combination of the values
458 of @var{gender} and @var{race}.
459 Since the @subcmd{NOTOTAL} keyword is given, statistics and histograms for
460 @var{score1} and @var{score2} covering the  whole dataset are not produced.
461 @example
462 EXAMINE @var{score1} @var{score2} BY
463         @var{gender}
464         @var{gender} BY @var{culture}
465         /STATISTICS = DESCRIPTIVES
466         /PLOT = HISTOGRAM
467         /NOTOTAL.
468 @end example
469
470 Here is a second example showing how the @cmd{examine} command can be used to find extremities.
471 @example
472 EXAMINE @var{height} @var{weight} BY
473         @var{gender}
474         /STATISTICS = EXTREME (3)
475         /PLOT = BOXPLOT
476         /COMPARE = GROUPS
477         /ID = @var{name}.
478 @end example
479 In this example, we look at the height and weight of a sample of individuals and
480 how they differ between male and female.
481 A table showing the 3 largest and the 3 smallest values of @exvar{height} and
482 @exvar{weight} for each gender, and for the whole dataset as are shown.
483 In addition, the @subcmd{/PLOT} subcommand requests boxplots.
484 Because @subcmd{/COMPARE = GROUPS} was specified, boxplots for male and female are
485 shown in juxtaposed in the same graphic, allowing us to easily see the difference between
486 the genders.
487 Since the variable @var{name} was specified on the @subcmd{ID} subcommand,
488 values of the @var{name} variable are used to label the extreme values.
489
490 @strong{Warning!}
491 If you specify many dependent variables or factor variables
492 for which there are many distinct values, then @cmd{EXAMINE} will produce a very
493 large quantity of output.
494
495 @node GRAPH
496 @section GRAPH
497
498 @vindex GRAPH
499 @cindex Exploratory data analysis
500 @cindex normality, testing
501
502 @display
503 GRAPH
504         /HISTOGRAM [(NORMAL)]= @var{var}
505         /SCATTERPLOT [(BIVARIATE)] = @var{var1} WITH @var{var2} [BY @var{var3}]
506         /BAR = @{@var{summary-function}(@var{var1}) | @var{count-function}@} BY @var{var2} [BY @var{var3}]
507         [ /MISSING=@{LISTWISE, VARIABLE@} [@{EXCLUDE, INCLUDE@}] ]
508                 [@{NOREPORT,REPORT@}]
509
510 @end display
511
512 The @cmd{GRAPH} command produces graphical plots of data. Only one of the subcommands
513 @subcmd{HISTOGRAM}, @subcmd{BAR} or @subcmd{SCATTERPLOT} can be specified, @i{i.e.} only one plot
514 can be produced per call of @cmd{GRAPH}. The @subcmd{MISSING} is optional.
515
516 @menu
517 * SCATTERPLOT::             Cartesian Plots
518 * HISTOGRAM::               Histograms
519 * BAR CHART::               Bar Charts
520 @end menu
521
522 @node SCATTERPLOT
523 @subsection Scatterplot
524 @cindex scatterplot
525
526 The subcommand @subcmd{SCATTERPLOT} produces an xy plot of the
527 data.
528 @cmd{GRAPH} uses the third variable @var{var3}, if specified, to determine
529 the colours and/or markers for the plot.
530 The following is an example for producing a scatterplot.
531
532 @example
533 GRAPH
534         /SCATTERPLOT = @var{height} WITH @var{weight} BY @var{gender}.
535 @end example
536
537 This example produces a scatterplot where @var{height} is plotted versus @var{weight}. Depending
538 on the value of the @var{gender} variable, the colour of the datapoint is different. With
539 this plot it is possible to analyze gender differences for @var{height} versus @var{weight} relation.
540
541 @node HISTOGRAM
542 @subsection Histogram
543 @cindex histogram
544
545 The subcommand @subcmd{HISTOGRAM} produces a histogram. Only one variable is allowed for
546 the histogram plot.
547 The keyword @subcmd{NORMAL} may be specified in parentheses, to indicate that the ideal normal curve
548 should be superimposed over the histogram.
549 For an alternative method to produce histograms @pxref{EXAMINE}. The
550 following example produces a histogram plot for the variable @var{weight}.
551
552 @example
553 GRAPH
554         /HISTOGRAM = @var{weight}.
555 @end example
556
557 @node BAR CHART
558 @subsection Bar Chart
559 @cindex bar chart
560
561 The subcommand @subcmd{BAR} produces a bar chart.
562 This subcommand requires that a @var{count-function} be specified (with no arguments) or a @var{summary-function} with a variable @var{var1} in parentheses.
563 Following the summary or count function, the keyword @subcmd{BY} should be specified and then a catagorical variable, @var{var2}.
564 The values of the variable @var{var2} determine the labels of the bars to be plotted.
565 Optionally a second categorical variable @var{var3} may be specified in which case a clustered (grouped) bar chart is produced.
566
567 Valid count functions are
568 @table @subcmd
569 @item COUNT
570 The weighted counts of the cases in each category.
571 @item PCT
572 The weighted counts of the cases in each category expressed as a percentage of the total weights of the cases.
573 @item CUFREQ
574 The cumulative weighted counts of the cases in each category.
575 @item CUPCT
576 The cumulative weighted counts of the cases in each category expressed as a percentage of the total weights of the cases.
577 @end table
578
579 The summary function is applied to @var{var1} across all cases in each category.
580 The recognised summary functions are:
581 @table @subcmd
582 @item SUM
583 The sum.
584 @item MEAN
585 The arithmetic mean.
586 @item MAXIMUM
587 The maximum value.
588 @item MINIMUM
589 The minimum value.
590 @end table
591
592 The following examples assume a dataset which is the results of a survey.
593 Each respondent has indicated annual income, their sex and city of residence.
594 One could create a bar chart showing how the mean income varies between of residents of different cities, thus:
595 @example
596 GRAPH  /BAR  = MEAN(@var{income}) BY @var{city}.
597 @end example
598
599 This can be extended to also indicate how income in each city differs between the sexes.
600 @example
601 GRAPH  /BAR  = MEAN(@var{income}) BY @var{city} BY @var{sex}.
602 @end example
603
604 One might also want to see how many respondents there are from each city.  This can be achieved as follows:
605 @example
606 GRAPH  /BAR  = COUNT BY @var{city}.
607 @end example
608
609 Bar charts can also be produced using the @ref{FREQUENCIES} and @ref{CROSSTABS} commands.
610
611 @node CORRELATIONS
612 @section CORRELATIONS
613
614 @vindex CORRELATIONS
615 @display
616 CORRELATIONS
617      /VARIABLES = @var{var_list} [ WITH @var{var_list} ]
618      [
619       .
620       .
621       .
622       /VARIABLES = @var{var_list} [ WITH @var{var_list} ]
623       /VARIABLES = @var{var_list} [ WITH @var{var_list} ]
624      ]
625
626      [ /PRINT=@{TWOTAIL, ONETAIL@} @{SIG, NOSIG@} ]
627      [ /STATISTICS=DESCRIPTIVES XPROD ALL]
628      [ /MISSING=@{PAIRWISE, LISTWISE@} @{INCLUDE, EXCLUDE@} ]
629 @end display
630
631 @cindex correlation
632 The @cmd{CORRELATIONS} procedure produces tables of the Pearson correlation coefficient
633 for a set of variables.  The significance of the coefficients are also given.
634
635 At least one @subcmd{VARIABLES} subcommand is required. If you specify the @subcmd{WITH}
636 keyword, then a non-square correlation table is produced.
637 The variables preceding @subcmd{WITH}, are used as the rows of the table,
638 and the variables following @subcmd{WITH} are used as the columns of the table.
639 If no @subcmd{WITH} subcommand is specified, then @cmd{CORRELATIONS} produces a
640 square, symmetrical table using all variables.
641
642 The @cmd{MISSING} subcommand determines the handling of missing variables.
643 If @subcmd{INCLUDE} is set, then user-missing values are included in the
644 calculations, but system-missing values are not.
645 If @subcmd{EXCLUDE} is set, which is the default, user-missing
646 values are excluded as well as system-missing values.
647
648 If @subcmd{LISTWISE} is set, then the entire case is excluded from analysis
649 whenever any variable  specified in any @cmd{/VARIABLES} subcommand
650 contains a missing value.
651 If @subcmd{PAIRWISE} is set, then a case is considered missing only if either of the
652 values  for the particular coefficient are missing.
653 The default is @subcmd{PAIRWISE}.
654
655 The @subcmd{PRINT} subcommand is used to control how the reported significance values are printed.
656 If the @subcmd{TWOTAIL} option is used, then a two-tailed test of significance is
657 printed.  If the @subcmd{ONETAIL} option is given, then a one-tailed test is used.
658 The default is @subcmd{TWOTAIL}.
659
660 If the @subcmd{NOSIG} option is specified, then correlation coefficients with significance less than
661 0.05 are highlighted.
662 If @subcmd{SIG} is specified, then no highlighting is performed.  This is the default.
663
664 @cindex covariance
665 The @subcmd{STATISTICS} subcommand requests additional statistics to be displayed.  The keyword
666 @subcmd{DESCRIPTIVES} requests that the mean, number of non-missing cases, and the non-biased
667 estimator of the standard deviation are displayed.
668 These statistics are displayed in a separated table, for all the variables listed
669 in any @subcmd{/VARIABLES} subcommand.
670 The @subcmd{XPROD} keyword requests cross-product deviations and covariance estimators to
671 be displayed for each pair of variables.
672 The keyword @subcmd{ALL} is the union of @subcmd{DESCRIPTIVES} and @subcmd{XPROD}.
673
674 @node CROSSTABS
675 @section CROSSTABS
676
677 @vindex CROSSTABS
678 @display
679 CROSSTABS
680         /TABLES=@var{var_list} BY @var{var_list} [BY @var{var_list}]@dots{}
681         /MISSING=@{TABLE,INCLUDE,REPORT@}
682         /FORMAT=@{TABLES,NOTABLES@}
683                 @{AVALUE,DVALUE@}
684         /CELLS=@{COUNT,ROW,COLUMN,TOTAL,EXPECTED,RESIDUAL,SRESIDUAL,
685                 ASRESIDUAL,ALL,NONE@}
686         /COUNT=@{ASIS,CASE,CELL@}
687                @{ROUND,TRUNCATE@}
688         /STATISTICS=@{CHISQ,PHI,CC,LAMBDA,UC,BTAU,CTAU,RISK,GAMMA,D,
689                      KAPPA,ETA,CORR,ALL,NONE@}
690         /BARCHART
691
692 (Integer mode.)
693         /VARIABLES=@var{var_list} (@var{low},@var{high})@dots{}
694 @end display
695
696 The @cmd{CROSSTABS} procedure displays crosstabulation
697 tables requested by the user.  It can calculate several statistics for
698 each cell in the crosstabulation tables.  In addition, a number of
699 statistics can be calculated for each table itself.
700
701 The @subcmd{TABLES} subcommand is used to specify the tables to be reported.  Any
702 number of dimensions is permitted, and any number of variables per
703 dimension is allowed.  The @subcmd{TABLES} subcommand may be repeated as many
704 times as needed.  This is the only required subcommand in @dfn{general
705 mode}.
706
707 Occasionally, one may want to invoke a special mode called @dfn{integer
708 mode}.  Normally, in general mode, @pspp{} automatically determines
709 what values occur in the data.  In integer mode, the user specifies the
710 range of values that the data assumes.  To invoke this mode, specify the
711 @subcmd{VARIABLES} subcommand, giving a range of data values in parentheses for
712 each variable to be used on the @subcmd{TABLES} subcommand.  Data values inside
713 the range are truncated to the nearest integer, then assigned to that
714 value.  If values occur outside this range, they are discarded.  When it
715 is present, the @subcmd{VARIABLES} subcommand must precede the @subcmd{TABLES}
716 subcommand.
717
718 In general mode, numeric and string variables may be specified on
719 TABLES.  In integer mode, only numeric variables are allowed.
720
721 The @subcmd{MISSING} subcommand determines the handling of user-missing values.
722 When set to @subcmd{TABLE}, the default, missing values are dropped on a table by
723 table basis.  When set to @subcmd{INCLUDE}, user-missing values are included in
724 tables and statistics.  When set to @subcmd{REPORT}, which is allowed only in
725 integer mode, user-missing values are included in tables but marked with
726 a footnote and excluded from statistical calculations.
727
728 The @subcmd{FORMAT} subcommand controls the characteristics of the
729 crosstabulation tables to be displayed.  It has a number of possible
730 settings:
731
732 @itemize @w{}
733 @item
734 @subcmd{TABLES}, the default, causes crosstabulation tables to be output.
735 @subcmd{NOTABLES}, which is equivalent to @code{CELLS=NONE}, suppresses them.
736
737 @item
738 @subcmd{AVALUE}, the default, causes values to be sorted in ascending order.
739 @subcmd{DVALUE} asserts a descending sort order.
740 @end itemize
741
742 The @subcmd{CELLS} subcommand controls the contents of each cell in the displayed
743 crosstabulation table.  The possible settings are:
744
745 @table @asis
746 @item COUNT
747 Frequency count.
748 @item ROW
749 Row percent.
750 @item COLUMN
751 Column percent.
752 @item TOTAL
753 Table percent.
754 @item EXPECTED
755 Expected value.
756 @item RESIDUAL
757 Residual.
758 @item SRESIDUAL
759 Standardized residual.
760 @item ASRESIDUAL
761 Adjusted standardized residual.
762 @item ALL
763 All of the above.
764 @item NONE
765 Suppress cells entirely.
766 @end table
767
768 @samp{/CELLS} without any settings specified requests @subcmd{COUNT}, @subcmd{ROW},
769 @subcmd{COLUMN}, and @subcmd{TOTAL}.
770 If @subcmd{CELLS} is not specified at all then only @subcmd{COUNT}
771 is selected.
772
773 By default, crosstabulation and statistics use raw case weights,
774 without rounding.  Use the @subcmd{/COUNT} subcommand to perform
775 rounding: CASE rounds the weights of individual weights as cases are
776 read, CELL rounds the weights of cells within each crosstabulation
777 table after it has been constructed, and ASIS explicitly specifies the
778 default non-rounding behavior.  When rounding is requested, ROUND, the
779 default, rounds to the nearest integer and TRUNCATE rounds toward
780 zero.
781
782 The @subcmd{STATISTICS} subcommand selects statistics for computation:
783
784 @table @asis
785 @item CHISQ
786 @cindex chi-square
787
788 Pearson chi-square, likelihood ratio, Fisher's exact test, continuity
789 correction, linear-by-linear association.
790 @item PHI
791 Phi.
792 @item CC
793 Contingency coefficient.
794 @item LAMBDA
795 Lambda.
796 @item UC
797 Uncertainty coefficient.
798 @item BTAU
799 Tau-b.
800 @item CTAU
801 Tau-c.
802 @item RISK
803 Risk estimate.
804 @item GAMMA
805 Gamma.
806 @item D
807 Somers' D.
808 @item KAPPA
809 Cohen's Kappa.
810 @item ETA
811 Eta.
812 @item CORR
813 Spearman correlation, Pearson's r.
814 @item ALL
815 All of the above.
816 @item NONE
817 No statistics.
818 @end table
819
820 Selected statistics are only calculated when appropriate for the
821 statistic.  Certain statistics require tables of a particular size, and
822 some statistics are calculated only in integer mode.
823
824 @samp{/STATISTICS} without any settings selects CHISQ.  If the
825 @subcmd{STATISTICS} subcommand is not given, no statistics are calculated.
826
827 @cindex bar chart
828 The @samp{/BARCHART} subcommand produces a clustered bar chart for the first two
829 variables on each table.
830 If a table has more than two variables, the counts for the third and subsequent levels
831 are aggregated and the chart is produced as if there were only two variables.
832
833
834 @strong{Please note:} Currently the implementation of @cmd{CROSSTABS} has the
835 following limitations:
836
837 @itemize @bullet
838 @item
839 Significance of some symmetric and directional measures is not calculated.
840 @item
841 Asymptotic standard error is not calculated for
842 Goodman and Kruskal's tau or symmetric Somers' d.
843 @item
844 Approximate T is not calculated for symmetric uncertainty coefficient.
845 @end itemize
846
847 Fixes for any of these deficiencies would be welcomed.
848
849 @subsection Crosstabs Example
850
851 @cindex chi-square test of independence
852
853 A researcher wishes to know if, in an industry, a person's sex is related to
854 the person's occupation.  To investigate this, she has determined that the
855 @file{personnel.sav} is a representative, randomly selected sample of persons.
856 The researcher's null hypothesis is that a person's sex has no relation to a
857 person's occupation. She uses a chi-squared test of independence to investigate
858 the hypothesis.
859
860 @float Example, crosstabs:ex
861 @psppsyntax {crosstabs.sps}
862 @caption {Running crosstabs on the @exvar{sex} and @exvar{occupation} variables}
863 @end float
864
865 The syntax in @ref{crosstabs:ex} conducts a chi-squared test of independence.
866 The line @code{/tables = occupation by sex} indicates that @exvar{occupation}
867 and @exvar{sex} are the variables to be tabulated.  To do this using the @gui{}
868 you must place these variable names respectively in the @samp{Row} and
869 @samp{Column} fields as shown in @ref{crosstabs:scr}.
870
871 @float Screenshot, crosstabs:scr
872 @psppimage {crosstabs}
873 @caption {The Crosstabs dialog box with the @exvar{sex} and @exvar{occupation} variables selected}
874 @end float
875
876 Similarly, the @samp{Cells} button shows a dialog box to select the @code{count}
877 and @code{expected} options.  All other cell options can be deselected for this
878 test.
879
880 You would use the @samp{Format} and @samp{Statistics}  buttons to select options
881 for the @subcmd{FORMAT} and @subcmd{STATISTICS} subcommands.  In this example,
882 the @samp{Statistics} requires only the @samp{Chisq} option to be checked.  All
883 other options should be unchecked.  No special settings are required from the
884 @samp{Format} dialog.
885
886 As shown in @ref{crosstabs:res} @cmd{CROSSTABS} generates a contingency table
887 containing the observed count and the expected count of each sex and each
888 occupation.  The expected count is the count which would be observed if the
889 null hypothesis were true.
890
891 The significance of the Pearson Chi-Square value is very much larger than the
892 normally accepted value of 0.05 and so one cannot reject the null hypothesis.
893 Thus the researcher must conclude that a person's sex has no relation to the
894 person's occupation.
895
896 @float Results, crosstabs:res
897 @psppoutput {crosstabs}
898 @caption {The results of a test of independence between @exvar{sex} and @exvar{occupation}}
899 @end float
900
901 @node CTABLES
902 @section CTABLES
903
904 @vindex CTABLES
905 @cindex custom tables
906 @cindex tables, custom
907
908 @code{CTABLES} has the following overall syntax.  At least one
909 @code{TABLE} subcommand is required:
910
911 @display
912 @t{CTABLES}
913   @dots{}@i{global subcommands}@dots{}
914   [@t{/TABLE} @i{axis} [@t{BY} @i{axis} [@t{BY} @i{axis}]]
915    @dots{}@i{per-table subcommands}@dots{}]@dots{}
916 @end display
917
918 @noindent
919 where each @i{axis} may be empty or take one of the following forms:
920
921 @display
922 @i{variable}
923 @i{variable} @t{[}@{@t{C} @math{|} @t{S}@}@t{]}
924 @i{axis} + @i{axis}
925 @i{axis} > @i{axis}
926 (@i{axis})
927 @i{axis} @t{[}@i{summary} [@i{string}] [@i{format}]@t{]}
928 @end display
929
930 The following subcommands precede the first @code{TABLE} subcommand
931 and apply to all of the output tables.  All of these subcommands are
932 optional:
933
934 @display
935 @t{/FORMAT}
936     [@t{MINCOLWIDTH=}@{@t{DEFAULT} @math{|} @i{width}@}]
937     [@t{MAXCOLWIDTH=}@{@t{DEFAULT} @math{|} @i{width}@}]
938     [@t{UNITS=}@{@t{POINTS} @math{|} @t{INCHES} @math{|} @t{CM}@}]
939     [@t{EMPTY=}@{@t{ZERO} @math{|} @t{BLANK} @math{|} @i{string}@}]
940     [@t{MISSING=}@i{string}]
941 @t{/VLABELS}
942     @t{VARIABLES=}@i{variables}
943     @t{DISPLAY}=@{@t{DEFAULT} @math{|} @t{NAME} @math{|} @t{LABEL} @math{|} @t{BOTH} @math{|} @t{NONE}@}
944 @ignore @c not yet implemented
945 @t{/MRSETS COUNTDUPLICATES=}@{@t{YES} @math{|} @t{NO}@}
946 @end ignore
947 @t{/SMISSING} @{@t{VARIABLE} @math{|} @t{LISTWISE}@}
948 @t{/PCOMPUTE} @t{&}@i{postcompute}@t{=EXPR(}@i{expression}@t{)}
949 @t{/PPROPERTIES} @t{&}@i{postcompute}@dots{}
950     [@t{LABEL=}@i{string}]
951     [@t{FORMAT=}[@i{summary} @i{format}]@dots{}]
952     [@t{HIDESOURCECATS=}@{@t{NO} @math{|} @t{YES}@}
953 @t{/WEIGHT VARIABLE=}@i{variable}
954 @t{/HIDESMALLCOUNTS COUNT=@i{count}}
955 @end display
956
957 The following subcommands follow @code{TABLE} and apply only to the
958 previous @code{TABLE}.  All of these subcommands are optional:
959
960 @display
961 @t{/SLABELS}
962     [@t{POSITION=}@{@t{COLUMN} @math{|} @t{ROW} @math{|} @t{LAYER}@}]
963     [@t{VISIBLE=}@{@t{YES} @math{|} @t{NO}@}]
964 @t{/CLABELS} @{@t{AUTO} @math{|} @{@t{ROWLABELS}@math{|}@t{COLLABELS}@}@t{=}@{@t{OPPOSITE}@math{|}@t{LAYER}@}@}
965 @t{/CATEGORIES} @t{VARIABLES=}@i{variables}
966     @{@t{[}@i{value}@t{,} @i{value}@dots{}@t{]}
967    @math{|} [@t{ORDER=}@{@t{A} @math{|} @t{D}@}]
968      [@t{KEY=}@{@t{VALUE} @math{|} @t{LABEL} @math{|} @i{summary}@t{(}@i{variable}@t{)}@}]
969      [@t{MISSING=}@{@t{EXCLUDE} @math{|} @t{INCLUDE}@}]@}
970     [@t{TOTAL=}@{@t{NO} @math{|} @t{YES}@} [@t{LABEL=}@i{string}] [@t{POSITION=}@{@t{AFTER} @math{|} @t{BEFORE}@}]]
971     [@t{EMPTY=}@{@t{INCLUDE} @math{|} @t{EXCLUDE}@}]
972 @t{/TITLES}
973     [@t{TITLE=}@i{string}@dots{}]
974     [@t{CAPTION=}@i{string}@dots{}]
975     [@t{CORNER=}@i{string}@dots{}]
976 @ignore  @c not yet implemented
977 @t{/CRITERIA CILEVEL=}@i{percentage}
978 @t{/SIGTEST TYPE=CHISQUARE}
979     [@t{ALPHA=}@i{siglevel}]
980     [@t{INCLUDEMRSETS=}@{@t{YES} @math{|} @t{NO}@}]
981     [@t{CATEGORIES=}@{@t{ALLVISIBLE} @math{|} @t{SUBTOTALS}@}]
982 @t{/COMPARETEST TYPE=}@{@t{PROP} @math{|} @t{MEAN}@}
983     [@t{ALPHA=}@i{value}[@t{,} @i{value}]]
984     [@t{ADJUST=}@{@t{BONFERRONI} @math{|} @t{BH} @math{|} @t{NONE}@}]
985     [@t{INCLUDEMRSETS=}@{@t{YES} @math{|} @t{NO}@}]
986     [@t{MEANSVARIANCE=}@{@t{ALLCATS} @math{|} @t{TESTEDCATS}@}]
987     [@t{CATEGORIES=}@{@t{ALLVISIBLE} @math{|} @t{SUBTOTALS}@}]
988     [@t{MERGE=}@{@t{NO} @math{|} @t{YES}@}]
989     [@t{STYLE=}@{@t{APA} @math{|} @t{SIMPLE}@}]
990     [@t{SHOWSIG=}@{@t{NO} @math{|} @t{YES}@}]
991 @end ignore
992 @end display
993
994 The @code{CTABLES} (aka ``custom tables'') command produces
995 multi-dimensional tables from categorical and scale data.  It offers
996 many options for data summarization and formatting.
997
998 This section's examples use data from the 2008 (USA) National Survey
999 of Drinking and Driving Attitudes and Behaviors, a public domain data
1000 set from the (USA) National Highway Traffic Administration and
1001 available at @url{https://data.transportation.gov}.  @pspp{} includes
1002 this data set, with a slightly modified dictionary, as
1003 @file{examples/nhtsa.sav}.
1004
1005 @node CTABLES Basics
1006 @subsection Basics
1007
1008 The only required subcommand is @code{TABLE}, which specifies the
1009 variables to include along each axis:
1010 @display
1011 @t{/TABLE} @i{rows} [@t{BY} @i{columns} [@t{BY} @i{layers}]]
1012 @end display
1013 @noindent
1014 In @code{TABLE}, each of @var{rows}, @var{columns}, and @var{layers}
1015 is either empty or an axis expression that specifies one or more
1016 variables.  At least one must specify an axis expression.
1017
1018 @node CTABLES Categorical Variable Basics
1019 @subsubsection Categorical Variables
1020
1021 An axis expression that names a categorical variable divides the data
1022 into cells according to the values of that variable.  When all the
1023 variables named on @code{TABLE} are categorical, by default each cell
1024 displays the number of cases that it contains, so specifying a single
1025 variable yields a frequency table, much like the output of the
1026 @code{FREQUENCIES} command (@pxref{FREQUENCIES}):
1027
1028 @example
1029 CTABLES /TABLE=AgeGroup.
1030 @end example
1031 @psppoutput {ctables1}
1032
1033 @noindent
1034 Specifying a row and a column categorical variable yields a
1035 crosstabulation, much like the output of the @code{CROSSTABS} command
1036 (@pxref{CROSSTABS}):
1037
1038 @example
1039 CTABLES /TABLE=AgeGroup BY qns3a.
1040 @end example
1041 @psppoutput {ctables2}
1042
1043 @noindent
1044 The @samp{>} ``nesting'' operator nests multiple variables on a single
1045 axis, e.g.:
1046
1047 @example
1048 CTABLES /TABLE qn105ba BY AgeGroup > qns3a.
1049 @end example
1050 @psppoutput {ctables3}
1051
1052 @noindent
1053 The @samp{+} ``stacking'' operator allows a single output table to
1054 include multiple data analyses.  With @samp{+}, @code{CTABLES} divides
1055 the output table into multiple @dfn{sections}, each of which includes
1056 an analysis of the full data set.  For example, the following command
1057 separately tabulates age group and driving frequency by gender:
1058
1059 @example
1060 CTABLES /TABLE AgeGroup + qn1 BY qns3a.
1061 @end example
1062 @psppoutput {ctables4}
1063
1064 @noindent
1065 When @samp{+} and @samp{>} are used together, @samp{>} binds more
1066 tightly.  Use parentheses to override operator precedence.  Thus:
1067
1068 @example
1069 CTABLES /TABLE qn26 + qn27 > qns3a.
1070 CTABLES /TABLE (qn26 + qn27) > qns3a.
1071 @end example
1072 @psppoutput {ctables5}
1073
1074 @node CTABLES Scalar Variable Basics
1075 @subsubsection Scalar Variables
1076
1077 For a categorical variable, @code{CTABLES} divides the table into a
1078 cell per category.  For a scalar variable, @code{CTABLES} instead
1079 calculates a summary measure, by default the mean, of the values that
1080 fall into a cell.  For example, if the only variable specified is a
1081 scalar variable, then the output is a single cell that holds the mean
1082 of all of the data:
1083
1084 @example
1085 CTABLES /TABLE qnd1.
1086 @end example
1087 @psppoutput {ctables6}
1088
1089 A scalar variable may nest with categorical variables.  The following
1090 example shows the mean age of survey respondents across gender and
1091 language groups:
1092
1093 @example
1094 CTABLES /TABLE qns3a > qnd1 BY region.
1095 @end example
1096 @psppoutput {ctables7}
1097
1098 The order of nesting of scalar and categorical variables affects table
1099 labeling, but it does not affect the data displayed in the table.  The
1100 following example shows how the output changes when the nesting order
1101 of the scalar and categorical variable are interchanged:
1102
1103 @example
1104 CTABLES /TABLE qnd1 > qns3a BY region.
1105 @end example
1106 @psppoutput {ctables8}
1107
1108 Only a single scalar variable may appear in each section; that is, a
1109 scalar variable may not nest inside a scalar variable directly or
1110 indirectly.  Scalar variables may only appear on one axis within
1111 @code{TABLE}.
1112
1113 @node CTABLES Overriding Measurement Level
1114 @subsubsection Overriding Measurement Level
1115
1116 By default, @code{CTABLES} uses a variable's measurement level to
1117 decide whether to treat it as categorical or scalar.  Variables
1118 assigned the nominal or ordinal measurement level are treated as
1119 categorical, and scalar variables are treated as scalar.
1120
1121 When @pspp{} reads data from a file in an external format, such as a
1122 text file, variables' measurement levels are often unknown.  If
1123 @code{CTABLES} runs when a variable has an unknown measurement level,
1124 it makes an initial pass through the data to guess measurement levels
1125 using the rules described in an earlier section (@pxref{Measurement
1126 Level}).  Use the @code{VARIABLE LEVEL} command to set or change a
1127 variable's measurement level (@pxref{VARIABLE LEVEL}).
1128
1129 To treat a variable as categorical or scalar only for one use on
1130 @code{CTABLES}, add @samp{[C]} or @samp{[S]}, respectively, after the
1131 variable name.  The following example shows the output when variable
1132 @code{qn20} is analyzed as scalar (the default for its measurement
1133 level) and as categorical:
1134
1135 @example
1136 CTABLES
1137     /TABLE qn20 BY qns3a
1138     /TABLE qn20 [C] BY qns3a.
1139 @end example
1140 @psppoutput {ctables9}
1141
1142 @ignore
1143 @node CTABLES Multiple Response Sets
1144 @subsubheading Multiple Response Sets
1145
1146 The @code{CTABLES} command does not yet support multiple response
1147 sets.
1148 @end ignore
1149
1150 @node CTABLES Data Summarization
1151 @subsection Data Summarization
1152
1153 The @code{CTABLES} command allows the user to control how the data are
1154 summarized with @dfn{summary specifications}, syntax that lists one or
1155 more summary function names, optionally separated by commas, and which
1156 are enclosed in square brackets following a variable name on the
1157 @code{TABLE} subcommand.  When all the variables are categorical,
1158 summary specifications can be given for the innermost nested variables
1159 on any one axis.  When a scalar variable is present, only the scalar
1160 variable may have summary specifications.
1161
1162 The following example includes a summary specification for column and
1163 row percentages for categorical variables, and mean and median for a
1164 scalar variable:
1165
1166 @example
1167 CTABLES
1168     /TABLE=qnd1 [MEAN, MEDIAN] BY qns3a
1169     /TABLE=AgeGroup [COLPCT, ROWPCT] BY qns3a.
1170 @end example
1171 @psppoutput {ctables10}
1172
1173 A summary specification may override the default label and format by
1174 appending a string or format specification or both (in that order) to
1175 the summary function name.  For example:
1176
1177 @example
1178 CTABLES /TABLE=AgeGroup [COLPCT 'Gender %' PCT5.0,
1179                          ROWPCT 'Age Group %' PCT5.0]
1180                BY qns3a.
1181 @end example
1182 @psppoutput {ctables11}
1183
1184 In addition to the standard formats, @code{CTABLES} allows the user to
1185 specify the following special formats:
1186
1187 @multitable {@code{NEGPAREN@i{w}.@i{d}}} {Encloses all numbers in parentheses.} {@t{(42.96%)}} {@t{(-42.96%)}}
1188 @item @code{NEGPAREN@i{w}.@i{d}}
1189 @tab Encloses negative numbers in parentheses.
1190 @tab @t{@w{    }42.96}
1191 @tab @t{@w{  }(42.96)}
1192
1193 @item @code{NEQUAL@i{w}.@i{d}}
1194 @tab Adds a @code{N=} prefix.
1195 @tab @t{@w{  }N=42.96}
1196 @tab @t{@w{ }N=-42.96}
1197
1198 @item @code{@code{PAREN@i{w}.@i{d}}}
1199 @tab Encloses all numbers in parentheses.
1200 @tab @t{@w{  }(42.96)}
1201 @tab @t{@w{ }(-42.96)}
1202
1203 @item @code{PCTPAREN@i{w}.@i{d}}
1204 @tab Encloses all numbers in parentheses with a @samp{%} suffix.
1205 @tab @t{@w{ }(42.96%)}
1206 @tab @t{(-42.96%)}
1207 @end multitable
1208
1209 Parentheses provide a shorthand to apply summary specifications to
1210 multiple variables.  For example, both of these commands:
1211
1212 @example
1213 CTABLES /TABLE=AgeGroup[COLPCT] + qns1[COLPCT] BY qns3a.
1214 CTABLES /TABLE=(AgeGroup + qns1)[COLPCT] BY qns3a.
1215 @end example
1216
1217 @noindent
1218 produce the same output shown below:
1219
1220 @psppoutput {ctables12}
1221
1222 The following sections list the available summary functions.  After
1223 each function's name is given its default label and format.  If no
1224 format is listed, then the default format is the print format for the
1225 variable being summarized.
1226
1227 @node CTABLES Summary Functions for Individual Cells
1228 @subsubsection Summary Functions for Individual Cells
1229
1230 This section lists the summary functions that consider only an
1231 individual cell in @code{CTABLES}.  Only one such summary function,
1232 @code{COUNT}, may be applied to both categorical and scale variables:
1233
1234 @table @asis
1235 @item @code{COUNT} (``Count'', F40.0)
1236 The sum of weights in a cell.
1237
1238 If @code{CATEGORIES} for one or more of the variables in a table
1239 include missing values (@pxref{CTABLES Per-Variable Category
1240 Options}), then some or all of the categories for a cell might be
1241 missing values.  @code{COUNT} counts data included in a cell
1242 regardless of whether its categories are missing.
1243 @end table
1244
1245 The following summary functions apply only to scale variables or
1246 totals and subtotals for categorical variables.  Be cautious about
1247 interpreting the summary value in the latter case, because it is not
1248 necessarily meaningful; however, the mean of a Likert scale, etc.@:
1249 may have a straightforward interpreation.
1250
1251 @table @asis
1252 @item @code{MAXIMUM} (``Maximum'')
1253 The largest value.
1254
1255 @item @code{MEAN} (``Mean'')
1256 The mean.
1257
1258 @item @code{MEDIAN} (``Median'')
1259 The median value.
1260
1261 @item @code{MINIMUM} (``Minimum'')
1262 The smallest value.
1263
1264 @item @code{MISSING} (``Missing'')
1265 Sum of weights of user- and system-missing values.
1266
1267 @item @code{MODE} (``Mode'')
1268 The highest-frequency value.  Ties are broken by taking the smallest mode.
1269
1270 @item @code{PTILE} @i{n} (``Percentile @i{n}'')
1271 The @var{n}th percentile, where @math{0 @leq{} @var{n} @leq{} 100}.
1272
1273 @item @code{RANGE} (``Range'')
1274 The maximum minus the minimum.
1275
1276 @item @code{SEMEAN} (``Std Error of Mean'')
1277 The standard error of the mean.
1278
1279 @item @code{STDDEV} (``Std Deviation'')
1280 The standard deviation.
1281
1282 @item @code{SUM} (``Sum'')
1283 The sum.
1284
1285 @item @code{TOTALN} (``Total N'', F40.0)
1286 The sum of weights in a cell.
1287
1288 For scale data, @code{COUNT} and @code{TOTALN} are the same.
1289
1290 For categorical data, @code{TOTALN} counts missing values in excluded
1291 categories, that is, user-missing values not in an explicit category
1292 list on @code{CATEGORIES} (@pxref{CTABLES Per-Variable Category
1293 Options}), or user-missing values excluded because
1294 @code{MISSING=EXCLUDE} is in effect on @code{CATEGORIES}, or
1295 system-missing values.  @code{COUNT} does not count these.
1296
1297 @xref{CTABLES Missing Values for Summary Variables}, for details of
1298 how @code{CTABLES} summarizes missing values.
1299
1300 @item @code{VALIDN} (``Valid N'', F40.0)
1301 The sum of valid count weights in included categories.
1302
1303 For categorical variables, @code{VALIDN} does not count missing values
1304 regardless of whether they are in included categories via
1305 @code{CATEGORIES}.  @code{VALIDN} does not count valid values that are
1306 in excluded categories.  @xref{CTABLES Missing Values for Summary
1307 Variables}, for details.
1308
1309 @item @code{VARIANCE} (``Variance'')
1310 The variance.
1311 @end table
1312
1313 @node CTABLES Summary Functions for Groups of Cells
1314 @subsubsection Summary Functions for Groups of Cells
1315
1316 These summary functions summarize over multiple cells within an area
1317 of the output chosen by the user and specified as part of the function
1318 name.  The following basic @var{area}s are supported, in decreasing
1319 order of size:
1320
1321 @table @code
1322 @item TABLE
1323 A @dfn{section}.  Stacked variables divide sections of the output from
1324 each other.  sections may span multiple layers.
1325
1326 @item LAYER
1327 A section within a single layer.
1328
1329 @item SUBTABLE
1330 A @dfn{subtable}, whose contents are the cells that pair an innermost
1331 row variable and an innermost column variable within a single layer.
1332 @end table
1333
1334 The following shows how the output for the table expression @code{qn61
1335 > qn57 BY qnd7a > qn86 + qn64b BY qns3a}@footnote{This is not
1336 necessarily a meaningful table, so for clarity variable labels are
1337 omitted.} is divided up into @code{TABLE}, @code{LAYER}, and
1338 @code{SUBTABLE} areas.  Each unique value for Table ID is one section,
1339 and similarly for Layer ID and Subtable ID.  Thus, this output has two
1340 @code{TABLE} areas (one for @code{qnd7a} and one for @code{qn64b}),
1341 four @code{LAYER} areas (for those two variables, per layer), and 12
1342 @code{SUBTABLE} areas.
1343 @psppoutput {ctables22}
1344
1345 @code{CTABLES} also supports the following @var{area}s that further
1346 divide a subtable or a layer within a section:
1347
1348 @table @code
1349 @item LAYERROW
1350 @itemx LAYERCOL
1351 A row or column, respectively, in one layer of a section.
1352
1353 @item ROW
1354 @itemx COL
1355 A row or column, respectively, in a subtable.
1356 @end table
1357
1358 The following summary functions for groups of cells are available for
1359 each @var{area} described above, for both categorical and scale
1360 variables:
1361
1362 @table @asis
1363 @item @code{@i{area}PCT} or @code{@i{area}PCT.COUNT} (``@i{Area} %'', PCT40.1)
1364 A percentage of total counts within @var{area}.
1365
1366 @item @code{@i{area}PCT.VALIDN} (``@i{Area} Valid N %'', PCT40.1)
1367 A percentage of total counts for valid values within @var{area}.
1368
1369 @item @code{@i{area}PCT.TOTALN} (``@i{Area} Total N %'', PCT40.1)
1370 A percentage of total counts for all values within @var{area}.
1371 @end table
1372
1373 Scale variables and totals and subtotals for categorical variables may
1374 use the following additional group cell summary function:
1375
1376 @table @asis
1377 @item @code{@i{area}PCT.SUM} (``@i{Area} Sum %'', PCT40.1)
1378 Percentage of the sum of the values within @var{area}.
1379 @end table
1380
1381 @node CTABLES Summary Functions for Adjusted Weights
1382 @subsubsection Summary Functions for Adjusted Weights
1383
1384 If the @code{WEIGHT} subcommand specified an effective weight variable
1385 (@pxref{CTABLES Effective Weight}), then the following summary functions
1386 use its value instead of the dictionary weight variable.  Otherwise,
1387 they are equivalent to the summary function without the
1388 @samp{E}-prefix:
1389
1390 @itemize @bullet
1391 @item
1392 @code{ECOUNT} (``Adjusted Count'', F40.0)
1393
1394 @item
1395 @code{ETOTALN} (``Adjusted Total N'', F40.0)
1396
1397 @item
1398 @code{EVALIDN} (``Adjusted Valid N'', F40.0)
1399 @end itemize
1400
1401 @node CTABLES Unweighted Summary Functions
1402 @subsubsection Unweighted Summary Functions
1403
1404 The following summary functions with a @samp{U}-prefix are equivalent
1405 to the same ones without the prefix, except that they use unweighted
1406 counts:
1407
1408 @itemize @bullet
1409 @item
1410 @code{UCOUNT} (``Unweighted Count'', F40.0)
1411
1412 @item
1413 @code{U@i{area}PCT} or @code{U@i{area}PCT.COUNT} (``Unweighted @i{Area} %'', PCT40.1)
1414
1415 @item
1416 @code{U@i{area}PCT.VALIDN} (``Unweighted @i{Area} Valid N %'', PCT40.1)
1417
1418 @item
1419 @code{U@i{area}PCT.TOTALN} (``Unweighted @i{Area} Total N %'', PCT40.1)
1420
1421 @item
1422 @code{UMEAN} (``Unweighted Mean'')
1423
1424 @item
1425 @code{UMEDIAN} (``Unweighted Median'')
1426
1427 @item
1428 @code{UMISSING} (``Unweighted Missing'')
1429
1430 @item
1431 @code{UMODE} (``Unweighted Mode'')
1432
1433 @item
1434 @code{U@i{area}PCT.SUM} (``Unweighted @i{Area} Sum %'', PCT40.1)
1435
1436 @item
1437 @code{UPTILE} @i{n} (``Unweighted Percentile @i{n}'') 
1438
1439 @item
1440 @code{USEMEAN} (``Unweighted Std Error of Mean'')
1441
1442 @item
1443 @code{USTDDEV} (``Unweighted Std Deviation'')
1444
1445 @item
1446 @code{USUM} (``Unweighted Sum'')
1447
1448 @item
1449 @code{UTOTALN} (``Unweighted Total N'', F40.0)
1450
1451 @item
1452 @code{UVALIDN} (``Unweighted Valid N'', F40.0)
1453
1454 @item
1455 @code{UVARIANCE} (``Unweighted Variance'', F40.0)
1456 @end itemize
1457
1458 @node CTABLES Statistics Positions and Labels
1459 @subsection Statistics Positions and Labels
1460
1461 @display
1462 @t{/SLABELS}
1463     [@t{POSITION=}@{@t{COLUMN} @math{|} @t{ROW} @math{|} @t{LAYER}@}]
1464     [@t{VISIBLE=}@{@t{YES} @math{|} @t{NO}@}]
1465 @end display
1466
1467 The @code{SLABELS} subcommand controls the position and visibility of
1468 summary statistics for the @code{TABLE} subcommand that it follows.
1469
1470 @code{POSITION} sets the axis on which summary statistics appear.
1471 With @t{POSITION=COLUMN}, which is the default, each summary statistic
1472 appears in a column.  For example:
1473
1474 @example
1475 CTABLES /TABLE=qnd1 [MEAN, MEDIAN] BY qns3a.
1476 @end example
1477 @psppoutput {ctables13}
1478
1479 @noindent
1480 With @t{POSITION=ROW}, each summary statistic appears in a row, as
1481 shown below:
1482
1483 @example
1484 CTABLES /TABLE=qnd1 [MEAN, MEDIAN] BY qns3a /SLABELS POSITION=ROW.
1485 @end example
1486 @psppoutput {ctables14}
1487
1488 @noindent
1489 @t{POSITION=LAYER} is also available to place each summary statistic in
1490 a separate layer.
1491
1492 Labels for summary statistics are shown by default.  Use
1493 @t{VISIBLE=NO} to suppress them.  Because unlabeled data can cause
1494 confusion, it should only be considered if the meaning of the data is
1495 evident, as in a simple case like this:
1496
1497 @example
1498 CTABLES /TABLE=AgeGroup [TABLEPCT] /SLABELS VISIBLE=NO.
1499 @end example
1500 @psppoutput {ctables15}
1501
1502 @node CTABLES Category Label Positions
1503 @subsection Category Label Positions
1504
1505 @display
1506 @t{/CLABELS} @{@t{AUTO} @math{|} @{@t{ROWLABELS}@math{|}@t{COLLABELS}@}@t{=}@{@t{OPPOSITE}@math{|}@t{LAYER}@}@}
1507 @end display
1508
1509 The @code{CLABELS} subcommand controls the position of category labels
1510 for the @code{TABLE} subcommand that it follows.  By default, or if
1511 @t{AUTO} is specified, category labels for a given variable nest
1512 inside the variable's label on the same axis.  For example, the
1513 command below results in age categories nesting within the age group
1514 variable on the rows axis and gender categories within the gender
1515 variable on the columns axis:
1516
1517 @example
1518 CTABLES /TABLE AgeGroup BY qns3a.
1519 @end example
1520 @psppoutput {ctables16}
1521
1522 @t{ROWLABELS=OPPOSITE} or @t{COLLABELS=OPPOSITE} move row or column
1523 variable category labels, respectively, to the opposite axis.  The
1524 setting affects only the innermost variable or variables, which must
1525 be categorical, on the given axis.  For example:
1526
1527 @example
1528 CTABLES /TABLE AgeGroup BY qns3a /CLABELS ROWLABELS=OPPOSITE.
1529 CTABLES /TABLE AgeGroup BY qns3a /CLABELS COLLABELS=OPPOSITE.
1530 @end example
1531 @psppoutput {ctables17}
1532
1533 @t{ROWLABELS=LAYER} or @t{COLLABELS=LAYER} move the innermost row or
1534 column variable category labels, respectively, to the layer axis.
1535
1536 Only one axis's labels may be moved, whether to the opposite axis or
1537 to the layer axis.
1538
1539 @subsubheading Effect on Summary Statistics
1540
1541 @code{CLABELS} primarily affects the appearance of tables, not the
1542 data displayed in them.  However, @code{CTABLES} can affect the values
1543 displayed for statistics that summarize areas of a table, since it can
1544 change the definitions of these areas.
1545
1546 For example, consider the following syntax and output:
1547
1548 @example
1549 CTABLES /TABLE AgeGroup BY qns3a [ROWPCT, COLPCT].
1550 @end example
1551 @psppoutput {ctables23}
1552
1553 @noindent
1554 Using @code{COLLABELS=OPPOSITE} changes the definitions of rows and
1555 columns, so that column percentages display what were previously row
1556 percentages and the new row percentages become meaningless (because
1557 there is only one cell per row):
1558
1559 @example
1560 CTABLES
1561     /TABLE AgeGroup BY qns3a [ROWPCT, COLPCT]
1562     /CLABELS COLLABELS=OPPOSITE.
1563 @end example
1564 @psppoutput {ctables24}
1565
1566 @subsubheading Moving Categories for Stacked Variables
1567
1568 If @code{CLABELS} moves category labels from an axis with stacked
1569 variables, the variables that are moved must have the same category
1570 specifications (@pxref{CTABLES Per-Variable Category Options}) and the
1571 same value labels.
1572
1573 The following shows both moving stacked category variables and
1574 adapting to the changing definitions of rows and columns:
1575
1576 @example
1577 CTABLES /TABLE (qn105ba + qn105bb) [COLPCT].
1578 CTABLES /TABLE (qn105ba + qn105bb) [ROWPCT]
1579   /CLABELS ROW=OPPOSITE.
1580 @end example
1581 @psppoutput {ctables25}
1582
1583 @node CTABLES Per-Variable Category Options
1584 @subsection Per-Variable Category Options
1585
1586 @display
1587 @t{/CATEGORIES} @t{VARIABLES=}@i{variables}
1588     @{@t{[}@i{value}@t{,} @i{value}@dots{}@t{]}
1589    @math{|} [@t{ORDER=}@{@t{A} @math{|} @t{D}@}]
1590      [@t{KEY=}@{@t{VALUE} @math{|} @t{LABEL} @math{|} @i{summary}@t{(}@i{variable}@t{)}@}]
1591      [@t{MISSING=}@{@t{EXCLUDE} @math{|} @t{INCLUDE}@}]@}
1592     [@t{TOTAL=}@{@t{NO} @math{|} @t{YES}@} [@t{LABEL=}@i{string}] [@t{POSITION=}@{@t{AFTER} @math{|} @t{BEFORE}@}]]
1593     [@t{EMPTY=}@{@t{INCLUDE} @math{|} @t{EXCLUDE}@}]
1594 @end display
1595
1596 The @code{CATEGORIES} subcommand specifies, for one or more
1597 categorical variables, the categories to include and exclude, the sort
1598 order for included categories, and treatment of missing values.  It
1599 also controls the totals and subtotals to display.  It may be
1600 specified any number of times, each time for a different set of
1601 variables.  @code{CATEGORIES} applies to the table produced by the
1602 @code{TABLE} subcommand that it follows.
1603
1604 @code{CATEGORIES} does not apply to scalar variables.
1605
1606 @t{VARIABLES} is required and must list the variables for the subcommand
1607 to affect.
1608
1609 The syntax may specify the categories to include and their sort order
1610 either explicitly or implicitly.  The following sections give the
1611 details of each form of syntax, followed by information on totals and
1612 subtotals and the @code{EMPTY} setting.
1613
1614 @node CTABLES Explicit Categories
1615 @subsubsection Explicit Categories
1616
1617 @anchor{CTABLES Explicit Category List}
1618
1619 To use @code{CTABLES} to explicitly specify categories to include,
1620 list the categories within square brackets in the desired sort order.
1621 Use spaces or commas to separate values.  Categories not covered by
1622 the list are excluded from analysis.
1623
1624 Each element of the list takes one of the following forms:
1625
1626 @table @t
1627 @item @i{number}
1628 @itemx '@i{string}'
1629 A numeric or string category value, for variables that have the
1630 corresponding type.
1631
1632 @item '@i{date}'
1633 @itemx '@i{time}'
1634 A date or time category value, for variables that have a date or time
1635 print format.
1636
1637 @item @i{min} THRU @i{max}
1638 @itemx LO THRU @i{max}
1639 @itemx @i{min} THRU HI
1640 A range of category values, where @var{min} and @var{max} each takes
1641 one of the forms above, in increasing order.
1642
1643 @item MISSING
1644 All user-missing values.  (To match individual user-missing values,
1645 specify their category values.)
1646
1647 @item OTHERNM
1648 Any non-missing value not covered by any other element of the list
1649 (regardless of where @t{OTHERNM} is placed in the list).
1650
1651 @item &@i{postcompute}
1652 A computed category name (@pxref{CTABLES Computed Categories}).
1653
1654 @item SUBTOTAL
1655 @itemx HSUBTOTAL
1656 A subtotal (@pxref{CTABLES Totals and Subtotals}).
1657 @end table
1658
1659 If multiple elements of the list cover a given category, the last one
1660 in the list takes precedence.
1661
1662 The following example syntax and output show how an explicit category
1663 can limit the displayed categories:
1664
1665 @example
1666 CTABLES /TABLE qn1.
1667 CTABLES /TABLE qn1 /CATEGORIES VARIABLES=qn1 [1, 2, 3].
1668 @end example
1669 @psppoutput {ctables27}
1670
1671 @node CTABLES Implicit Categories
1672 @subsubsection Implicit Categories
1673
1674 In the absence of an explicit list of categories, @code{CATEGORIES}
1675 allows @code{KEY}, @code{ORDER}, and @code{MISSING} to specify how to
1676 select and sort categories.
1677
1678 The @code{KEY} setting specifies the sort key.  By default, or with
1679 @code{KEY=VALUE}, categories are sorted by default.  Categories may
1680 also be sorted by value label, with @code{KEY=LABEL}, or by the value
1681 of a summary function, e.g.@: @code{KEY=COUNT}.
1682 @ignore  @c Not yet implemented
1683 For summary functions, a variable name may be specified in
1684 parentheses, e.g.@: @code{KEY=MAXIUM(qnd1)}, and this is required for
1685 functions that apply only to scalar variables.  The @code{PTILE}
1686 function also requires a percentage argument, e.g.@:
1687 @code{KEY=PTILE(qnd1, 90)}.  Only summary functions used in the table
1688 may be used, except that @code{COUNT} is always allowed.
1689 @end ignore
1690
1691 By default, or with @code{ORDER=A}, categories are sorted in ascending
1692 order.  Specify @code{ORDER=D} to sort in descending order.
1693
1694 User-missing values are excluded by default, or with
1695 @code{MISSING=EXCLUDE}.  Specify @code{MISSING=INCLUDE} to include
1696 user-missing values.  The system-missing value is always excluded.
1697
1698 The following example syntax and output show how
1699 @code{MISSING=INCLUDE} causes missing values to be included in a
1700 category list.
1701
1702 @example
1703 CTABLES /TABLE qn1.
1704 CTABLES /TABLE qn1 /CATEGORIES VARIABLES=qn1 MISSING=INCLUDE.
1705 @end example
1706 @psppoutput {ctables28}
1707
1708 @node CTABLES Totals and Subtotals
1709 @subsubsection Totals and Subtotals
1710
1711 @code{CATEGORIES} also controls display of totals and subtotals.  By
1712 default, or with @code{TOTAL=NO}, totals are not displayed.  Use
1713 @code{TOTAL=YES} to display a total.  By default, the total is labeled
1714 ``Total''; use @code{LABEL="@i{label}"} to override it.
1715
1716 Subtotals are also not displayed by default.  To add one or more
1717 subtotals, use an explicit category list and insert @code{SUBTOTAL} or
1718 @code{HSUBTOTAL} in the position or positions where the subtotal
1719 should appear.  The subtotal becomes an extra row or column or layer.
1720 @code{HSUBTOTAL} additionally hides the categories that make up the
1721 subtotal.  Either way, the default label is ``Subtotal'', use
1722 @code{SUBTOTAL="@i{label}"} or @code{HSUBTOTAL="@i{label}"} to specify
1723 a custom label.
1724
1725 The following example syntax and output show how to use
1726 @code{TOTAL=YES} and @code{SUBTOTAL}:
1727
1728 @example
1729 CTABLES
1730     /TABLE qn1
1731     /CATEGORIES VARIABLES=qn1 [OTHERNM, SUBTOTAL='Valid Total',
1732                                MISSING, SUBTOTAL='Missing Total']
1733                               TOTAL=YES LABEL='Overall Total'.
1734 @end example
1735 @psppoutput {ctables29}
1736
1737 By default, or with @code{POSITION=AFTER}, totals are displayed in the
1738 output after the last category and subtotals apply to categories that
1739 precede them.  With @code{POSITION=BEFORE}, totals come before the
1740 first category and subtotals apply to categories that follow them.
1741
1742 Only categorical variables may have totals and subtotals.  Scalar
1743 variables may be ``totaled'' indirectly by enabling totals and
1744 subtotals on a categorical variable within which the scalar variable
1745 is summarized.  For example, the following syntax produces a mean,
1746 count, and valid count across all data by adding a total on the
1747 categorical @code{region} variable, as shown:
1748
1749 @example
1750 CTABLES /TABLE=region > qn20 [MEAN, VALIDN]
1751     /CATEGORIES VARIABLES=region TOTAL=YES LABEL='All regions'.
1752 @end example
1753 @psppoutput {ctables30}
1754
1755 By default, @pspp{} uses the same summary functions for totals and
1756 subtotals as other categories.  To summarize totals and subtotals
1757 differently, specify the summary functions for totals and subtotals
1758 after the ordinary summary functions inside a nested set of @code{[]}
1759 following @code{TOTALS}.  For example, the following syntax displays
1760 @code{COUNT} for individual categories and totals and @code{VALIDN}
1761 for totals, as shown:
1762
1763 @example
1764 CTABLES
1765     /TABLE qnd7a [COUNT, TOTALS[COUNT, VALIDN]]
1766     /CATEGORIES VARIABLES=qnd7a TOTAL=YES MISSING=INCLUDE.
1767 @end example
1768 @psppoutput {ctables26}
1769
1770 @node CTABLES Categories Without Values
1771 @subsubsection Categories Without Values
1772
1773 Some categories might not be included in the data set being analyzed.
1774 For example, our example data set has no cases in the ``15 or
1775 younger'' age group.  By default, or with @code{EMPTY=INCLUDE},
1776 @pspp{} includes these empty categories in output tables.  To exclude
1777 them, specify @code{EMPTY=EXCLUDE}.
1778
1779 For implicit categories, empty categories potentially include all the
1780 values with value labels for a given variable; for explicit
1781 categories, they include all the values listed individually and all
1782 values with value labels that are covered by ranges or @code{MISSING}
1783 or @code{OTHERNM}.
1784
1785 The following example syntax and output show the effect of
1786 @code{EMPTY=EXCLUDE} for the @code{qns1} variable, in which 0 is labeled
1787 ``None'' but no cases exist with that value:
1788
1789 @example
1790 CTABLES /TABLE=qns1.
1791 CTABLES /TABLE=qns1 /CATEGORIES VARIABLES=qns1 EMPTY=EXCLUDE.
1792 @end example
1793 @psppoutput {ctables31}
1794
1795 @node CTABLES Titles
1796 @subsection Titles
1797
1798 @display
1799 @t{/TITLES}
1800     [@t{TITLE=}@i{string}@dots{}]
1801     [@t{CAPTION=}@i{string}@dots{}]
1802     [@t{CORNER=}@i{string}@dots{}]
1803 @end display
1804
1805 The @code{TITLES} subcommand sets the title, caption, and corner text
1806 for the table output for the previous @code{TABLE} subcommand.  Any
1807 number of strings may be specified for each kind of text, with each
1808 string appearing on a separate line in the output.  The title appears
1809 above the table, the caption below the table, and the corner text
1810 appears in the table's upper left corner.  By default, the title is
1811 ``Custom Tables'' and the caption and corner text are empty.  With
1812 some table output styles, the corner text is not displayed.
1813
1814 The strings provided in this subcommand may contain the following
1815 macro-like keywords that @pspp{} substitutes at the time that it runs
1816 the command:
1817
1818 @table @code @c (
1819 @item )DATE
1820 The current date, e.g.@: MM/DD/YY.  The format is locale-dependent.
1821
1822 @c (
1823 @item )TIME
1824 The current time, e.g.@: HH:MM:SS.  The format is locale-dependent.
1825
1826 @c (
1827 @item )TABLE
1828 The expression specified on the @code{TABLE} command.  Summary
1829 and measurement level specifications are omitted, and variable labels are used in place of variable names.
1830 @end table
1831
1832 @node CTABLES Table Formatting
1833 @subsection Table Formatting
1834
1835 @display
1836 @t{/FORMAT}
1837     [@t{MINCOLWIDTH=}@{@t{DEFAULT} @math{|} @i{width}@}]
1838     [@t{MAXCOLWIDTH=}@{@t{DEFAULT} @math{|} @i{width}@}]
1839     [@t{UNITS=}@{@t{POINTS} @math{|} @t{INCHES} @math{|} @t{CM}@}]
1840     [@t{EMPTY=}@{@t{ZERO} @math{|} @t{BLANK} @math{|} @i{string}@}]
1841     [@t{MISSING=}@i{string}]
1842 @end display
1843
1844 The @code{FORMAT} subcommand, which must precede the first
1845 @code{TABLE} subcommand, controls formatting for all the output
1846 tables.  @code{FORMAT} and all of its settings are optional.
1847
1848 Use @code{MINCOLWIDTH} and @code{MAXCOLWIDTH} to control the minimum
1849 or maximum width of columns in output tables.  By default, with
1850 @code{DEFAULT}, column width varies based on content.  Otherwise,
1851 specify a number for either or both of these settings.  If both are
1852 specified, @code{MAXCOLWIDTH} must be greater than or equal to
1853 @code{MINCOLWIDTH}.  The default unit, or with @code{UNITS=POINTS}, is
1854 points (1/72 inch), or specify @code{UNITS=INCHES} to use inches or
1855 @code{UNITS=CM} for centimeters.  @pspp{} does not currently honor any
1856 of these settings.
1857
1858 By default, or with @code{EMPTY=ZERO}, zero values are displayed in
1859 their usual format.  Use @code{EMPTY=BLANK} to use an empty cell
1860 instead, or @code{EMPTY="@i{string}"} to use the specified string.
1861
1862 By default, missing values are displayed as @samp{.}, the same as in
1863 other tables.  Specify @code{MISSING="@i{string}"} to instead use a
1864 custom string.
1865
1866 @node CTABLES Display of Variable Labels
1867 @subsection Display of Variable Labels
1868
1869 @display
1870 @t{/VLABELS}
1871     @t{VARIABLES=}@i{variables}
1872     @t{DISPLAY}=@{@t{DEFAULT} @math{|} @t{NAME} @math{|} @t{LABEL} @math{|} @t{BOTH} @math{|} @t{NONE}@}
1873 @end display
1874
1875 The @code{VLABELS} subcommand, which must precede the first
1876 @code{TABLE} subcommand, controls display of variable labels in all
1877 the output tables.  @code{VLABELS} is optional.  It may appear
1878 multiple times to adjust settings for different variables.
1879
1880 @code{VARIABLES} and @code{DISPLAY} are required.  The value of
1881 @code{DISPLAY} controls how variable labels are displayed for the
1882 variables listed on @code{VARIABLES}.  The supported values are:
1883
1884 @table @code
1885 @item DEFAULT
1886 Use the setting from @code{SET TVARS} (@pxref{SET TVARS}).
1887
1888 @item NAME
1889 Show only a variable name.
1890
1891 @item LABEL
1892 Show only a variable label.
1893
1894 @item BOTH
1895 Show variable name and label.
1896
1897 @item NONE
1898 Show nothing.
1899 @end table
1900
1901 @node CTABLES Missing Value Treatment
1902 @subsection Missing Value Treatment
1903
1904 The @code{TABLE} subcommand on @code{CTABLES} specifies two different
1905 kinds of variables: variables that divide tables into cells (which are
1906 always categorical) and variables being summarized (which may be
1907 categorical or scale).  @pspp{} treats missing values differently in
1908 each kind of variable, as described in the sections below.
1909
1910 @node CTABLES Missing Values for Cell-Defining Variables
1911 @subsubsection Missing Values for Cell-Defining Variables
1912
1913 For variables that divide tables into cells, per-variable category
1914 options, as described in @ref{CTABLES Per-Variable Category Options},
1915 determine which data is analyzed.  If any of the categories for such a
1916 variable would exclude a case, then that case is not included.
1917
1918 As an example, consider the following entirely artificial dataset, in
1919 which @samp{x} and @samp{y} are categorical variables with missing
1920 value 9, and @samp{z} is scale:
1921
1922 @psppoutput{ctables32}
1923
1924 Using @samp{x} and @samp{y} to define cells, and summarizing @samp{z},
1925 by default @pspp{} omits all the cases that have @samp{x} or @samp{y} (or both)
1926 missing:
1927
1928 @example
1929 CTABLES /TABLE x > y > z [SUM].
1930 @end example
1931 @psppoutput{ctables33}
1932
1933 If, however, we add @code{CATEGORIES} specifications to include
1934 missing values for @samp{y} or for @samp{x} and @samp{y}, the output
1935 table includes them, like so:
1936
1937 @example
1938 CTABLES /TABLE x > y > z [SUM] /CATEGORIES VARIABLES=y MISSING=INCLUDE.
1939 CTABLES /TABLE x > y > z [SUM] /CATEGORIES VARIABLES=x y MISSING=INCLUDE.
1940 @end example
1941 @psppoutput{ctables34}
1942
1943 @node CTABLES Missing Values for Summary Variables
1944 @subsubsection Missing Values for Summary Variables
1945
1946 For summary variables, values that are valid and in included
1947 categories are analyzed, and values that are missing or in excluded
1948 categories are not analyzed, with the following exceptions:
1949
1950 @itemize @bullet
1951 @item
1952 The ``@t{VALIDN}'' summary functions (@code{VALIDN}, @code{EVALIDN},
1953 @code{UVALIDN}, @code{@i{area}PCT.VALIDN}, and
1954 @code{U@i{area}PCT.VALIDN}) only count valid values in included
1955 categories (not missing values in included categories).
1956
1957 @item
1958 The ``@t{TOTALN}'' summary functions (@code{TOTALN}, @code{ETOTALN},
1959 @code{UTOTALN}, @code{@i{area}PCT.TOTALN}), and
1960 @code{U@i{area}PCT.TOTALN} count all values (valid and missing) in
1961 included categories and missing (but not valid) values in excluded
1962 categories.
1963 @end itemize
1964
1965 @noindent
1966 For categorical variables, system-missing values are never in included
1967 categories.  For scale variables, there is no notion of included and
1968 excluded categories, so all values are effectively included.
1969
1970 The following table provides another view of the above rules:
1971
1972 @multitable {@w{ }@w{ }@w{ }@w{ }Missing values in excluded categories} {@t{VALIDN}} {other} {@t{TOTALN}}
1973 @headitem @tab @t{VALIDN} @tab other @tab @t{TOTALN}
1974 @item @headitemfont{Categorical variables:}
1975 @item @w{ }@w{ }@w{ }@w{ }Valid values in included categories   @tab yes @tab yes @tab yes
1976 @item @w{ }@w{ }@w{ }@w{ }Missing values in included categories @tab --- @tab yes @tab yes
1977 @item @w{ }@w{ }@w{ }@w{ }Missing values in excluded categories @tab --- @tab --- @tab yes
1978 @item @w{ }@w{ }@w{ }@w{ }Valid values in excluded categories   @tab --- @tab --- @tab ---
1979 @item @headitemfont{Scale variables:}
1980 @item @w{ }@w{ }@w{ }@w{ }Valid values                          @tab yes @tab yes @tab yes
1981 @item @w{ }@w{ }@w{ }@w{ }User- or system-missing values        @tab --- @tab yes @tab yes
1982 @end multitable
1983
1984 @node CTABLES Scale Missing Values
1985 @subsubsection Scale Missing Values
1986
1987 @display
1988 @t{/SMISSING} @{@t{VARIABLE} @math{|} @t{LISTWISE}@}
1989 @end display
1990
1991 The @code{SMISSING} subcommand, which must precede the first
1992 @code{TABLE} subcommand, controls treatment of missing values for
1993 scalar variables in producing all the output tables.  @code{SMISSING}
1994 is optional.
1995
1996 With @code{SMISSING=VARIABLE}, which is the default, missing values
1997 are excluded on a variable-by-variable basis.  With
1998 @code{SMISSING=LISTWISE}, when stacked scalar variables are nested
1999 together with a categorical variable, a missing value for any of the
2000 scalar variables causes the case to be excluded for all of them.
2001
2002 As an example, consider the following dataset, in which @samp{x} is a
2003 categorical variable and @samp{y} and @samp{z} are scale:
2004
2005 @psppoutput{ctables18}
2006
2007 @noindent
2008 With the default missing-value treatment, @samp{x}'s mean is 20, based
2009 on the values 10, 20, and 30, and @samp{y}'s mean is 50, based on 40,
2010 50, and 60:
2011
2012 @example
2013 CTABLES /TABLE (y + z) > x.
2014 @end example
2015 @psppoutput{ctables19}
2016
2017 @noindent
2018 By adding @code{SMISSING=LISTWISE}, only cases where @samp{y} and
2019 @samp{z} are both non-missing are considered, so @samp{x}'s mean
2020 becomes 15, as the average of 10 and 20, and @samp{y}'s mean becomes
2021 55, the average of 50 and 60:
2022
2023 @example
2024 CTABLES /SMISSING LISTWISE /TABLE (y + z) > x.
2025 @end example
2026 @psppoutput{ctables20}
2027
2028 @noindent
2029 Even with @code{SMISSING=LISTWISE}, if @samp{y} and @samp{z} are
2030 separately nested with @samp{x}, instead of using a single @samp{>}
2031 operator, missing values revert to being considered on a
2032 variable-by-variable basis:
2033
2034 @example
2035 CTABLES /SMISSING LISTWISE /TABLE (y > x) + (z > x).
2036 @end example
2037 @psppoutput{ctables21}
2038
2039 @node CTABLES Computed Categories
2040 @subsection Computed Categories
2041
2042 @display
2043 @t{/PCOMPUTE} @t{&}@i{postcompute}@t{=EXPR(}@i{expression}@t{)}
2044 @t{/PPROPERTIES} @t{&}@i{postcompute}@dots{}
2045     [@t{LABEL=}@i{string}]
2046     [@t{FORMAT=}[@i{summary} @i{format}]@dots{}]
2047     [@t{HIDESOURCECATS=}@{@t{NO} @math{|} @t{YES}@}
2048 @end display
2049
2050 @dfn{Computed categories}, also called @dfn{postcomputes}, are
2051 categories created using arithmetic on categories obtained from the
2052 data.  The @code{PCOMPUTE} subcommand creates a postcompute, which may
2053 then be used on @code{CATEGORIES} within an explicit category list
2054 (@pxref{CTABLES Explicit Category List}).  Optionally,
2055 @code{PPROPERTIES} refines how a postcompute is displayed.  The
2056 following sections provide the details.
2057
2058 @node CTABLES PCOMPUTE
2059 @subsubsection PCOMPUTE
2060
2061 @display
2062 @t{/PCOMPUTE} @t{&}@i{postcompute}@t{=EXPR(}@i{expression}@t{)}
2063 @end display
2064
2065 The @code{PCOMPUTE} subcommand, which must precede the first
2066 @code{TABLE} command, defines computed categories.  It is optional and
2067 may be used any number of times to define multiple postcomputes.
2068
2069 Each @code{PCOMPUTE} defines one postcompute.  Its syntax consists of
2070 a name to identify the postcompute as a @pspp{} identifier prefixed by
2071 @samp{&}, followed by @samp{=} and a postcompute expression enclosed
2072 in @code{EXPR(@dots{})}.  A postcompute expression consists of:
2073
2074 @table @t
2075 @item [@i{category}]
2076 This form evaluates to the summary statistic for @i{category}, e.g.@:
2077 @code{[1]} evaluates to the value of the summary statistic associated
2078 with category 1.  The @i{category} may be a number, a quoted string,
2079 or a quoted time or date value.  All of the categories for a given
2080 postcompute must have the same form.  The category must appear in all
2081 the @code{CATEGORIES} list in which the postcompute is used.
2082
2083 @item [@i{min} THRU @i{max}]
2084 @itemx [LO THRU @i{max}]
2085 @itemx [@i{min} THRU HI]
2086 @itemx MISSING
2087 @itemx OTHERNM
2088 These forms evaluate to the summary statistics for a category
2089 specified with the same syntax, as described in previous section
2090 (@pxref{CTABLES Explicit Category List}).  The category must appear in
2091 all the @code{CATEGORIES} list in which the postcompute is used.
2092
2093 @item SUBTOTAL
2094 The summary statistic for the subtotal category.  This form is allowed
2095 only if the @code{CATEGORIES} lists that include this postcompute have
2096 exactly one subtotal.
2097
2098 @item SUBTOTAL[@i{index}]
2099 The summary statistic for subtotal category @i{index}, where 1 is the
2100 first subtotal, 2 is the second, and so on.  This form may be used for
2101 @code{CATEGORIES} lists with any number of subtotals.
2102
2103 @item TOTAL
2104 The summary statistic for the total.  The @code{CATEGORIES} lsits that
2105 include this postcompute must have a total enabled.
2106
2107 @item @i{a} + @i{b}
2108 @itemx @i{a} - @i{b}
2109 @itemx @i{a} * @i{b}
2110 @itemx @i{a} / @i{b}
2111 @itemx @i{a} ** @i{b}
2112 These forms perform arithmetic on the values of postcompute
2113 expressions @i{a} and @i{b}.  The usual operator precedence rules
2114 apply.
2115
2116 @item @i{number}
2117 Numeric constants may be used in postcompute expressions.
2118
2119 @item (@i{a})
2120 Parentheses override operator precedence.
2121 @end table
2122
2123 A postcompute is not associated with any particular variable.
2124 Instead, it may be referenced within @code{CATEGORIES} for any
2125 suitable variable (e.g.@: only a string variable is suitable for a
2126 postcompute expression that refers to a string category, only a
2127 variable with subtotals for an expression that refers to subtotals,
2128 @dots{}).
2129
2130 Normally a named postcompute is defined only once, but if a later
2131 @code{PCOMPUTE} redefines a postcompute with the same name as an
2132 earlier one, the later one take precedence.
2133
2134 The following syntax and output shows how @code{PCOMPUTE} can compute
2135 a total over subtotals, summing the ``Frequent Drivers'' and
2136 ``Infrequent Drivers'' subtotals to form an ``All Drivers''
2137 postcompute.  It also shows how to calculate and display a percentage,
2138 in this case the percentage of valid responses that report never
2139 driving.  It uses @code{PPROPERTIES} (@pxref{CTABLES PPROPERTIES}) to
2140 display the latter in @code{PCT} format.
2141
2142 @example
2143 CTABLES
2144     /PCOMPUTE &all_drivers=EXPR([1 THRU 2] + [3 THRU 4])
2145     /PPROPERTIES &all_drivers LABEL='All Drivers'
2146     /PCOMPUTE &pct_never=EXPR([5] / ([1 THRU 2] + [3 THRU 4] + [5]) * 100)
2147     /PPROPERTIES &pct_never LABEL='% Not Drivers' FORMAT=COUNT PCT40.1
2148     /TABLE=qn1 BY qns3a
2149     /CATEGORIES VARIABLES=qn1 [1 THRU 2, SUBTOTAL='Frequent Drivers',
2150                                3 THRU 4, SUBTOTAL='Infrequent Drivers',
2151                                &all_drivers, 5, &pct_never,
2152                                MISSING, SUBTOTAL='Not Drivers or Missing'].
2153 @end example
2154 @psppoutput{ctables35}
2155
2156 @node CTABLES PPROPERTIES
2157 @subsubsection PPROPERTIES
2158
2159 @display
2160 @t{/PPROPERTIES} @t{&}@i{postcompute}@dots{}
2161     [@t{LABEL=}@i{string}]
2162     [@t{FORMAT=}[@i{summary} @i{format}]@dots{}]
2163     [@t{HIDESOURCECATS=}@{@t{NO} @math{|} @t{YES}@}
2164 @end display
2165
2166 The @code{PPROPERTIES} subcommand, which must appear before
2167 @code{TABLE}, sets properties for one or more postcomputes defined on
2168 prior @code{PCOMPUTE} subcommands.  The subcommand syntax begins with
2169 the list of postcomputes, each prefixed with @samp{&} as specified on
2170 @code{PCOMPUTE}.
2171
2172 All of the settings on @code{PPROPERTIES} are optional.  Use
2173 @code{LABEL} to set the label shown for the postcomputes in table
2174 output.  The default label for a postcompute is the expression used to
2175 define it.
2176
2177 A postcompute always uses same summary functions as the variable whose
2178 categories contain it, but @code{FORMAT} allows control over the
2179 format used to display their values.  It takes a list of summary
2180 function names and format specifiers.
2181
2182 By default, or with @code{HIDESOURCECATS=NO}, categories referred to
2183 by computed categories are displayed like other categories.  Use
2184 @code{HIDESOURCECATS=YES} to hide them.
2185
2186 The previous section provides an example for @code{PPROPERTIES}.
2187
2188 @node CTABLES Effective Weight
2189 @subsection Effective Weight
2190
2191 @display
2192 @t{/WEIGHT VARIABLE=}@i{variable}
2193 @end display
2194
2195 The @code{WEIGHT} subcommand is optional and must appear before
2196 @code{TABLE}.  If it appears, it must name a numeric variable, known
2197 as the @dfn{effective weight} or @dfn{adjustment weight}.  The
2198 effective weight variable stands in for the dictionary's weight
2199 variable (@pxref{WEIGHT}), if any, in most calculations in
2200 @code{CTABLES}.  The only exceptions are the @code{COUNT},
2201 @code{TOTALN}, and @code{VALIDN} summary functions, which use the
2202 dictionary weight instead.
2203
2204 Weights obtained from the @pspp{} dictionary are rounded to the
2205 nearest integer at the case level.  Effective weights are not rounded.
2206 Regardless of the weighting source, @pspp{} does not analyze cases
2207 with zero, missing, or negative effective weights.
2208
2209 @node CTABLES Hiding Small Counts
2210 @subsection Hiding Small Counts
2211
2212 @display
2213 @t{/HIDESMALLCOUNTS COUNT=@i{count}}
2214 @end display
2215
2216 The @code{HIDESMALLCOUNTS} subcommand is optional.  If it specified,
2217 then @code{COUNT}, @code{ECOUNT}, and @code{UCOUNT} values in output
2218 tables less than the value of @i{count} are shown as @code{<@i{count}}
2219 instead of their true values.  The value of @i{count} must be an
2220 integer and must be at least 2.
2221
2222 The following syntax and example shows how to use
2223 @code{HIDESMALLCOUNTS}:
2224
2225 @example
2226 CTABLES /HIDESMALLCOUNTS COUNT=10 /TABLE qn37.
2227 @end example
2228 @psppoutput{ctables36}
2229
2230 @node FACTOR
2231 @section FACTOR
2232
2233 @vindex FACTOR
2234 @cindex factor analysis
2235 @cindex principal components analysis
2236 @cindex principal axis factoring
2237 @cindex data reduction
2238
2239 @display
2240 FACTOR  @{
2241          VARIABLES=@var{var_list},
2242          MATRIX IN (@{CORR,COV@}=@{*,@var{file_spec}@})
2243         @}
2244
2245         [ /METHOD = @{CORRELATION, COVARIANCE@} ]
2246
2247         [ /ANALYSIS=@var{var_list} ]
2248
2249         [ /EXTRACTION=@{PC, PAF@}]
2250
2251         [ /ROTATION=@{VARIMAX, EQUAMAX, QUARTIMAX, PROMAX[(@var{k})], NOROTATE@}]
2252
2253         [ /PRINT=[INITIAL] [EXTRACTION] [ROTATION] [UNIVARIATE] [CORRELATION] [COVARIANCE] [DET] [KMO] [AIC] [SIG] [ALL] [DEFAULT] ]
2254
2255         [ /PLOT=[EIGEN] ]
2256
2257         [ /FORMAT=[SORT] [BLANK(@var{n})] [DEFAULT] ]
2258
2259         [ /CRITERIA=[FACTORS(@var{n})] [MINEIGEN(@var{l})] [ITERATE(@var{m})] [ECONVERGE (@var{delta})] [DEFAULT] ]
2260
2261         [ /MISSING=[@{LISTWISE, PAIRWISE@}] [@{INCLUDE, EXCLUDE@}] ]
2262 @end display
2263
2264 The @cmd{FACTOR} command performs Factor Analysis or Principal Axis Factoring on a dataset.  It may be used to find
2265 common factors in the data or for data reduction purposes.
2266
2267 The @subcmd{VARIABLES} subcommand is required (unless the @subcmd{MATRIX IN}
2268 subcommand is used).
2269 It lists the variables which are to partake in the analysis.  (The @subcmd{ANALYSIS}
2270 subcommand may optionally further limit the variables that
2271 participate; it is useful primarily in conjunction with @subcmd{MATRIX IN}.)
2272
2273 If @subcmd{MATRIX IN} instead of @subcmd{VARIABLES} is specified, then the analysis
2274 is performed on a pre-prepared correlation or covariance matrix file instead of on
2275 individual data cases.  Typically the matrix file will have been generated by
2276 @cmd{MATRIX DATA} (@pxref{MATRIX DATA}) or provided by a third party.
2277 If specified, @subcmd{MATRIX IN} must be followed by @samp{COV} or @samp{CORR},
2278 then by @samp{=} and @var{file_spec} all in parentheses.
2279 @var{file_spec} may either be an asterisk, which indicates the currently loaded
2280 dataset, or it may be a file name to be loaded. @xref{MATRIX DATA}, for the expected
2281 format of the file.
2282
2283 The @subcmd{/EXTRACTION} subcommand is used to specify the way in which factors
2284 (components) are extracted from the data.
2285 If @subcmd{PC} is specified, then Principal Components Analysis is used.
2286 If @subcmd{PAF} is specified, then Principal Axis Factoring is
2287 used. By default Principal Components Analysis is used.
2288
2289 The @subcmd{/ROTATION} subcommand is used to specify the method by which the
2290 extracted solution is rotated.  Three orthogonal rotation methods are available:
2291 @subcmd{VARIMAX} (which is the default), @subcmd{EQUAMAX}, and @subcmd{QUARTIMAX}.
2292 There is one oblique rotation method, @i{viz}: @subcmd{PROMAX}.
2293 Optionally you may enter the power of the promax rotation @var{k}, which must be enclosed in parentheses.
2294 The default value of @var{k} is 5.
2295 If you don't want any rotation to be performed, the word @subcmd{NOROTATE}
2296 prevents the command from performing any rotation on the data.
2297
2298 The @subcmd{/METHOD} subcommand should be used to determine whether the
2299 covariance matrix or the correlation matrix of the data is
2300 to be analysed.  By default, the correlation matrix is analysed.
2301
2302 The @subcmd{/PRINT} subcommand may be used to select which features of the analysis are reported:
2303
2304 @itemize
2305 @item @subcmd{UNIVARIATE}
2306       A table of mean values, standard deviations and total weights are printed.
2307 @item @subcmd{INITIAL}
2308       Initial communalities and eigenvalues are printed.
2309 @item @subcmd{EXTRACTION}
2310       Extracted communalities and eigenvalues are printed.
2311 @item @subcmd{ROTATION}
2312       Rotated communalities and eigenvalues are printed.
2313 @item @subcmd{CORRELATION}
2314       The correlation matrix is printed.
2315 @item @subcmd{COVARIANCE}
2316       The covariance matrix is printed.
2317 @item @subcmd{DET}
2318       The determinant of the correlation or covariance matrix is printed.
2319 @item @subcmd{AIC}
2320       The anti-image covariance and anti-image correlation matrices are printed.
2321 @item @subcmd{KMO}
2322       The Kaiser-Meyer-Olkin measure of sampling adequacy and the Bartlett test of sphericity is printed.
2323 @item @subcmd{SIG}
2324       The significance of the elements of correlation matrix is printed.
2325 @item @subcmd{ALL}
2326       All of the above are printed.
2327 @item @subcmd{DEFAULT}
2328       Identical to @subcmd{INITIAL} and @subcmd{EXTRACTION}.
2329 @end itemize
2330
2331 If @subcmd{/PLOT=EIGEN} is given, then a ``Scree'' plot of the eigenvalues is
2332 printed.  This can be useful for visualizing the factors and deciding
2333 which factors (components) should be retained.
2334
2335 The @subcmd{/FORMAT} subcommand determined how data are to be
2336 displayed in loading matrices.  If @subcmd{SORT} is specified, then
2337 the variables are sorted in descending order of significance.  If
2338 @subcmd{BLANK(@var{n})} is specified, then coefficients whose absolute
2339 value is less than @var{n} are not printed.  If the keyword
2340 @subcmd{DEFAULT} is specified, or if no @subcmd{/FORMAT} subcommand is
2341 specified, then no sorting is performed, and all coefficients are printed.
2342
2343 You can use the @subcmd{/CRITERIA} subcommand to specify how the number of
2344 extracted factors (components) are chosen.  If @subcmd{FACTORS(@var{n})} is
2345 specified, where @var{n} is an integer, then @var{n} factors are
2346 extracted.  Otherwise, the @subcmd{MINEIGEN} setting is used.
2347 @subcmd{MINEIGEN(@var{l})} requests that all factors whose eigenvalues
2348 are greater than or equal to @var{l} are extracted. The default value
2349 of @var{l} is 1. The @subcmd{ECONVERGE} setting has effect only when
2350 using iterative algorithms for factor extraction (such as Principal Axis
2351 Factoring).  @subcmd{ECONVERGE(@var{delta})} specifies that
2352 iteration should cease when the maximum absolute value of the
2353 communality estimate between one iteration and the previous is less
2354 than @var{delta}. The default value of @var{delta} is 0.001.
2355
2356 The @subcmd{ITERATE(@var{m})} may appear any number of times and is
2357 used for two different purposes. It is used to set the maximum number
2358 of iterations (@var{m}) for convergence and also to set the maximum
2359 number of iterations for rotation.
2360 Whether it affects convergence or rotation depends upon which
2361 subcommand follows the @subcmd{ITERATE} subcommand.
2362 If @subcmd{EXTRACTION} follows, it affects convergence.
2363 If @subcmd{ROTATION} follows, it affects rotation.
2364 If neither @subcmd{ROTATION} nor @subcmd{EXTRACTION} follow a
2365 @subcmd{ITERATE} subcommand, then the entire subcommand is ignored.
2366 The default value of @var{m} is 25.
2367
2368 The @cmd{MISSING} subcommand determines the handling of missing
2369 variables.  If @subcmd{INCLUDE} is set, then user-missing values are
2370 included in the calculations, but system-missing values are not.
2371 If @subcmd{EXCLUDE} is set, which is the default, user-missing
2372 values are excluded as well as system-missing values.  This is the
2373 default. If @subcmd{LISTWISE} is set, then the entire case is excluded
2374 from analysis whenever any variable  specified in the @cmd{VARIABLES}
2375 subcommand contains a missing value.
2376
2377 If @subcmd{PAIRWISE} is set, then a case is considered missing only if
2378 either of the values  for the particular coefficient are missing.
2379 The default is @subcmd{LISTWISE}.
2380
2381 @node GLM
2382 @section GLM
2383
2384 @vindex GLM
2385 @cindex univariate analysis of variance
2386 @cindex fixed effects
2387 @cindex factorial anova
2388 @cindex analysis of variance
2389 @cindex ANOVA
2390
2391
2392 @display
2393 GLM @var{dependent_vars} BY @var{fixed_factors}
2394      [/METHOD = SSTYPE(@var{type})]
2395      [/DESIGN = @var{interaction_0} [@var{interaction_1} [... @var{interaction_n}]]]
2396      [/INTERCEPT = @{INCLUDE|EXCLUDE@}]
2397      [/MISSING = @{INCLUDE|EXCLUDE@}]
2398 @end display
2399
2400 The @cmd{GLM} procedure can be used for fixed effects factorial Anova.
2401
2402 The @var{dependent_vars} are the variables to be analysed.
2403 You may analyse several variables in the same command in which case they should all
2404 appear before the @code{BY} keyword.
2405
2406 The @var{fixed_factors} list must be one or more categorical variables.  Normally it
2407 does not make sense to enter a scalar variable in the @var{fixed_factors} and doing
2408 so may cause @pspp{} to do a lot of unnecessary processing.
2409
2410 The @subcmd{METHOD} subcommand is used to change the method for producing the sums of
2411 squares.  Available values of @var{type} are 1, 2 and 3.  The default is type 3.
2412
2413 You may specify a custom design using the @subcmd{DESIGN} subcommand.
2414 The design comprises a list of interactions where each interaction is a
2415 list of variables separated by a @samp{*}.  For example the command
2416 @display
2417 GLM subject BY sex age_group race
2418     /DESIGN = age_group sex group age_group*sex age_group*race
2419 @end display
2420 @noindent specifies the model @math{subject = age_group + sex + race + age_group*sex + age_group*race}.
2421 If no @subcmd{DESIGN} subcommand is specified, then the default is all possible combinations
2422 of the fixed factors.  That is to say
2423 @display
2424 GLM subject BY sex age_group race
2425 @end display
2426 implies the model
2427 @math{subject = age_group + sex + race + age_group*sex + age_group*race + sex*race + age_group*sex*race}.
2428
2429
2430 The @subcmd{MISSING} subcommand determines the handling of missing
2431 variables.
2432 If @subcmd{INCLUDE} is set then, for the purposes of GLM analysis,
2433 only system-missing values are considered
2434 to be missing; user-missing values are not regarded as missing.
2435 If @subcmd{EXCLUDE} is set, which is the default, then user-missing
2436 values are considered to be missing as well as system-missing values.
2437 A case for which any dependent variable or any factor
2438 variable has a missing value is excluded from the analysis.
2439
2440 @node LOGISTIC REGRESSION
2441 @section LOGISTIC REGRESSION
2442
2443 @vindex LOGISTIC REGRESSION
2444 @cindex logistic regression
2445 @cindex bivariate logistic regression
2446
2447 @display
2448 LOGISTIC REGRESSION [VARIABLES =] @var{dependent_var} WITH @var{predictors}
2449
2450      [/CATEGORICAL = @var{categorical_predictors}]
2451
2452      [@{/NOCONST | /ORIGIN | /NOORIGIN @}]
2453
2454      [/PRINT = [SUMMARY] [DEFAULT] [CI(@var{confidence})] [ALL]]
2455
2456      [/CRITERIA = [BCON(@var{min_delta})] [ITERATE(@var{max_interations})]
2457                   [LCON(@var{min_likelihood_delta})] [EPS(@var{min_epsilon})]
2458                   [CUT(@var{cut_point})]]
2459
2460      [/MISSING = @{INCLUDE|EXCLUDE@}]
2461 @end display
2462
2463 Bivariate Logistic Regression is used when you want to explain a dichotomous dependent
2464 variable in terms of one or more predictor variables.
2465
2466 The minimum command is
2467 @example
2468 LOGISTIC REGRESSION @var{y} WITH @var{x1} @var{x2} @dots{} @var{xn}.
2469 @end example
2470 Here, @var{y} is the dependent variable, which must be dichotomous and @var{x1} @dots{} @var{xn}
2471 are the predictor variables whose coefficients the procedure estimates.
2472
2473 By default, a constant term is included in the model.
2474 Hence, the full model is
2475 @math{
2476 {\bf y}
2477 = b_0 + b_1 {\bf x_1}
2478 + b_2 {\bf x_2}
2479 + \dots
2480 + b_n {\bf x_n}
2481 }
2482
2483 Predictor variables which are categorical in nature should be listed on the @subcmd{/CATEGORICAL} subcommand.
2484 Simple variables as well as interactions between variables may be listed here.
2485
2486 If you want a model without the constant term @math{b_0}, use the keyword @subcmd{/ORIGIN}.
2487 @subcmd{/NOCONST} is a synonym for @subcmd{/ORIGIN}.
2488
2489 An iterative Newton-Raphson procedure is used to fit the model.
2490 The @subcmd{/CRITERIA} subcommand is used to specify the stopping criteria of the procedure,
2491 and other parameters.
2492 The value of @var{cut_point} is used in the classification table.  It is the
2493 threshold above which predicted values are considered to be 1.  Values
2494 of @var{cut_point} must lie in the range [0,1].
2495 During iterations, if any one of the stopping criteria are satisfied, the procedure is
2496 considered complete.
2497 The stopping criteria are:
2498 @itemize
2499 @item The number of iterations exceeds @var{max_iterations}.
2500       The default value of @var{max_iterations} is 20.
2501 @item The change in the all coefficient estimates are less than @var{min_delta}.
2502 The default value of @var{min_delta} is 0.001.
2503 @item The magnitude of change in the likelihood estimate is less than @var{min_likelihood_delta}.
2504 The default value of @var{min_delta} is zero.
2505 This means that this criterion is disabled.
2506 @item The differential of the estimated probability for all cases is less than @var{min_epsilon}.
2507 In other words, the probabilities are close to zero or one.
2508 The default value of @var{min_epsilon} is 0.00000001.
2509 @end itemize
2510
2511
2512 The @subcmd{PRINT} subcommand controls the display of optional statistics.
2513 Currently there is one such option, @subcmd{CI}, which indicates that the
2514 confidence interval of the odds ratio should be displayed as well as its value.
2515 @subcmd{CI} should be followed by an integer in parentheses, to indicate the
2516 confidence level of the desired confidence interval.
2517
2518 The @subcmd{MISSING} subcommand determines the handling of missing
2519 variables.
2520 If @subcmd{INCLUDE} is set, then user-missing values are included in the
2521 calculations, but system-missing values are not.
2522 If @subcmd{EXCLUDE} is set, which is the default, user-missing
2523 values are excluded as well as system-missing values.
2524 This is the default.
2525
2526 @node MEANS
2527 @section MEANS
2528
2529 @vindex MEANS
2530 @cindex means
2531
2532 @display
2533 MEANS [TABLES =]
2534       @{@var{var_list}@}
2535         [ BY @{@var{var_list}@} [BY @{@var{var_list}@} [BY @{@var{var_list}@} @dots{} ]]]
2536
2537       [ /@{@var{var_list}@}
2538          [ BY @{@var{var_list}@} [BY @{@var{var_list}@} [BY @{@var{var_list}@} @dots{} ]]] ]
2539
2540       [/CELLS = [MEAN] [COUNT] [STDDEV] [SEMEAN] [SUM] [MIN] [MAX] [RANGE]
2541         [VARIANCE] [KURT] [SEKURT]
2542         [SKEW] [SESKEW] [FIRST] [LAST]
2543         [HARMONIC] [GEOMETRIC]
2544         [DEFAULT]
2545         [ALL]
2546         [NONE] ]
2547
2548       [/MISSING = [INCLUDE] [DEPENDENT]]
2549 @end display
2550
2551 You can use the @cmd{MEANS} command to calculate the arithmetic mean and similar
2552 statistics, either for the dataset as a whole or for categories of data.
2553
2554 The simplest form of the command is
2555 @example
2556 MEANS @var{v}.
2557 @end example
2558 @noindent which calculates the mean, count and standard deviation for @var{v}.
2559 If you specify a grouping variable, for example
2560 @example
2561 MEANS @var{v} BY @var{g}.
2562 @end example
2563 @noindent then the means, counts and standard deviations for @var{v} after having
2564 been grouped by @var{g} are calculated.
2565 Instead of the mean, count and standard deviation, you could specify the statistics
2566 in which you are interested:
2567 @example
2568 MEANS @var{x} @var{y} BY @var{g}
2569       /CELLS = HARMONIC SUM MIN.
2570 @end example
2571 This example calculates the harmonic mean, the sum and the minimum values of @var{x} and @var{y}
2572 grouped by @var{g}.
2573
2574 The @subcmd{CELLS} subcommand specifies which statistics to calculate.  The available statistics
2575 are:
2576 @itemize
2577 @item @subcmd{MEAN}
2578 @cindex arithmetic mean
2579       The arithmetic mean.
2580 @item @subcmd{COUNT}
2581       The count of the values.
2582 @item @subcmd{STDDEV}
2583       The standard deviation.
2584 @item @subcmd{SEMEAN}
2585       The standard error of the mean.
2586 @item @subcmd{SUM}
2587       The sum of the values.
2588 @item @subcmd{MIN}
2589       The minimum value.
2590 @item @subcmd{MAX}
2591       The maximum value.
2592 @item @subcmd{RANGE}
2593       The difference between the maximum and minimum values.
2594 @item @subcmd{VARIANCE}
2595       The variance.
2596 @item @subcmd{FIRST}
2597       The first value in the category.
2598 @item @subcmd{LAST}
2599       The last value in the category.
2600 @item @subcmd{SKEW}
2601       The skewness.
2602 @item @subcmd{SESKEW}
2603       The standard error of the skewness.
2604 @item @subcmd{KURT}
2605       The kurtosis
2606 @item @subcmd{SEKURT}
2607       The standard error of the kurtosis.
2608 @item @subcmd{HARMONIC}
2609 @cindex harmonic mean
2610       The harmonic mean.
2611 @item @subcmd{GEOMETRIC}
2612 @cindex geometric mean
2613       The geometric mean.
2614 @end itemize
2615
2616 In addition, three special keywords are recognized:
2617 @itemize
2618 @item @subcmd{DEFAULT}
2619       This is the same as @subcmd{MEAN} @subcmd{COUNT} @subcmd{STDDEV}.
2620 @item @subcmd{ALL}
2621       All of the above statistics are calculated.
2622 @item @subcmd{NONE}
2623       No statistics are calculated (only a summary is shown).
2624 @end itemize
2625
2626
2627 More than one @dfn{table} can be specified in a single command.
2628 Each table is separated by a @samp{/}. For
2629 example
2630 @example
2631 MEANS TABLES =
2632       @var{c} @var{d} @var{e} BY @var{x}
2633       /@var{a} @var{b} BY @var{x} @var{y}
2634       /@var{f} BY @var{y} BY @var{z}.
2635 @end example
2636 has three tables (the @samp{TABLE =} is optional).
2637 The first table has three dependent variables @var{c}, @var{d} and @var{e}
2638 and a single categorical variable @var{x}.
2639 The second table has two dependent variables @var{a} and @var{b},
2640 and two categorical variables @var{x} and @var{y}.
2641 The third table has a single dependent variables @var{f}
2642 and a categorical variable formed by the combination of @var{y} and @var{z}.
2643
2644
2645 By default values are omitted from the analysis only if missing values
2646 (either system missing or user missing)
2647 for any of the variables directly involved in their calculation are
2648 encountered.
2649 This behaviour can be modified with the  @subcmd{/MISSING} subcommand.
2650 Three options are possible: @subcmd{TABLE}, @subcmd{INCLUDE} and @subcmd{DEPENDENT}.
2651
2652 @subcmd{/MISSING = INCLUDE} says that user missing values, either in the dependent
2653 variables or in the categorical variables should be taken at their face
2654 value, and not excluded.
2655
2656 @subcmd{/MISSING = DEPENDENT} says that user missing values, in the dependent
2657 variables should be taken at their face value, however cases which
2658 have user missing values for the categorical variables should be omitted
2659 from the calculation.
2660
2661 @subsection Example Means
2662
2663 The dataset in @file{repairs.sav} contains the mean time between failures (@exvar{mtbf})
2664 for a sample of artifacts produced by different factories and trialed under
2665 different operating conditions.
2666 Since there are four combinations of categorical variables, by simply looking
2667 at the list of data, it would be hard to how the scores vary for each category.
2668 @ref{means:ex} shows one way of tabulating the @exvar{mtbf} in a way which is
2669 easier to understand.
2670
2671 @float Example, means:ex
2672 @psppsyntax {means.sps}
2673 @caption {Running @cmd{MEANS} on the @exvar{mtbf} score with categories @exvar{factory} and @exvar{environment}}
2674 @end float
2675
2676 The results are shown in @ref{means:res}.   The figures shown indicate the mean,
2677 standard deviation and number of samples in each category.
2678 These figures however do not indicate whether the results are statistically
2679 significant.  For that, you would need to use the procedures @cmd{ONEWAY}, @cmd{GLM} or
2680 @cmd{T-TEST} depending on the hypothesis being tested.
2681
2682 @float Result, means:res
2683 @psppoutput {means}
2684 @caption {The @exvar{mtbf} categorised by @exvar{factory} and @exvar{environment}}
2685 @end float
2686
2687 Note that there is no limit to the number of variables for which you can calculate
2688 statistics, nor to the number of categorical variables per layer, nor the number
2689 of layers.
2690 However, running @cmd{MEANS} on a large numbers of variables, or with categorical variables
2691 containing a large number of distinct values may result in an extremely large output, which
2692 will not be easy to interpret.
2693 So you should consider carefully which variables to select for participation in the analysis.
2694
2695 @node NPAR TESTS
2696 @section NPAR TESTS
2697
2698 @vindex NPAR TESTS
2699 @cindex nonparametric tests
2700
2701 @display
2702 NPAR TESTS
2703
2704      nonparametric test subcommands
2705      .
2706      .
2707      .
2708
2709      [ /STATISTICS=@{DESCRIPTIVES@} ]
2710
2711      [ /MISSING=@{ANALYSIS, LISTWISE@} @{INCLUDE, EXCLUDE@} ]
2712
2713      [ /METHOD=EXACT [ TIMER [(@var{n})] ] ]
2714 @end display
2715
2716 @cmd{NPAR TESTS} performs nonparametric tests.
2717 Non parametric tests make very few assumptions about the distribution of the
2718 data.
2719 One or more tests may be specified by using the corresponding subcommand.
2720 If the @subcmd{/STATISTICS} subcommand is also specified, then summary statistics are
2721 produces for each variable that is the subject of any test.
2722
2723 Certain tests may take a long time to execute, if an exact figure is required.
2724 Therefore, by default asymptotic approximations are used unless the
2725 subcommand @subcmd{/METHOD=EXACT} is specified.
2726 Exact tests give more accurate results, but may take an unacceptably long
2727 time to perform.  If the @subcmd{TIMER} keyword is used, it sets a maximum time,
2728 after which the test is abandoned, and a warning message printed.
2729 The time, in minutes, should be specified in parentheses after the @subcmd{TIMER} keyword.
2730 If the @subcmd{TIMER} keyword is given without this figure, then a default value of 5 minutes
2731 is used.
2732
2733
2734 @menu
2735 * BINOMIAL::                Binomial Test
2736 * CHISQUARE::               Chi-square Test
2737 * COCHRAN::                 Cochran Q Test
2738 * FRIEDMAN::                Friedman Test
2739 * KENDALL::                 Kendall's W Test
2740 * KOLMOGOROV-SMIRNOV::      Kolmogorov Smirnov Test
2741 * KRUSKAL-WALLIS::          Kruskal-Wallis Test
2742 * MANN-WHITNEY::            Mann Whitney U Test
2743 * MCNEMAR::                 McNemar Test
2744 * MEDIAN::                  Median Test
2745 * RUNS::                    Runs Test
2746 * SIGN::                    The Sign Test
2747 * WILCOXON::                Wilcoxon Signed Ranks Test
2748 @end menu
2749
2750
2751 @node    BINOMIAL
2752 @subsection Binomial test
2753 @vindex BINOMIAL
2754 @cindex binomial test
2755
2756 @display
2757      [ /BINOMIAL[(@var{p})]=@var{var_list}[(@var{value1}[, @var{value2})] ] ]
2758 @end display
2759
2760 The @subcmd{/BINOMIAL} subcommand compares the observed distribution of a dichotomous
2761 variable with that of a binomial distribution.
2762 The variable @var{p} specifies the test proportion of the binomial
2763 distribution.
2764 The default value of 0.5 is assumed if @var{p} is omitted.
2765
2766 If a single value appears after the variable list, then that value is
2767 used as the threshold to partition the observed values. Values less
2768 than or equal to the threshold value form the first category.  Values
2769 greater than the threshold form the second category.
2770
2771 If two values appear after the variable list, then they are used
2772 as the values which a variable must take to be in the respective
2773 category.
2774 Cases for which a variable takes a value equal to neither of the specified
2775 values, take no part in the test for that variable.
2776
2777 If no values appear, then the variable must assume dichotomous
2778 values.
2779 If more than two distinct, non-missing values for a variable
2780 under test are encountered then an error occurs.
2781
2782 If the test proportion is equal to 0.5, then a two tailed test is
2783 reported.   For any other test proportion, a one tailed test is
2784 reported.
2785 For one tailed tests, if the test proportion is less than
2786 or equal to the observed proportion, then the significance of
2787 observing the observed proportion or more is reported.
2788 If the test proportion is more than the observed proportion, then the
2789 significance of observing the observed proportion or less is reported.
2790 That is to say, the test is always performed in the observed
2791 direction.
2792
2793 @pspp{} uses a very precise approximation to the gamma function to
2794 compute the binomial significance.  Thus, exact results are reported
2795 even for very large sample sizes.
2796
2797
2798 @node    CHISQUARE
2799 @subsection Chi-square Test
2800 @vindex CHISQUARE
2801 @cindex chi-square test
2802
2803
2804 @display
2805      [ /CHISQUARE=@var{var_list}[(@var{lo},@var{hi})] [/EXPECTED=@{EQUAL|@var{f1}, @var{f2} @dots{} @var{fn}@}] ]
2806 @end display
2807
2808
2809 The @subcmd{/CHISQUARE} subcommand produces a chi-square statistic for the differences
2810 between the expected and observed frequencies of the categories of a variable.
2811 Optionally, a range of values may appear after the variable list.
2812 If a range is given, then non integer values are truncated, and values
2813 outside the  specified range are excluded from the analysis.
2814
2815 The @subcmd{/EXPECTED} subcommand specifies the expected values of each
2816 category.
2817 There must be exactly one non-zero expected value, for each observed
2818 category, or the @subcmd{EQUAL} keyword must be specified.
2819 You may use the notation @subcmd{@var{n}*@var{f}} to specify @var{n}
2820 consecutive expected categories all taking a frequency of @var{f}.
2821 The frequencies given are proportions, not absolute frequencies.  The
2822 sum of the frequencies need not be 1.
2823 If no @subcmd{/EXPECTED} subcommand is given, then equal frequencies
2824 are expected.
2825
2826 @subsubsection Chi-square Example
2827
2828 A researcher wishes to investigate whether there are an equal number of
2829 persons of each sex in a population.   The sample chosen for invesigation
2830 is that from the @file {physiology.sav} dataset.   The null hypothesis for
2831 the test is that the population comprises an equal number of males and females.
2832 The analysis is performed as shown in @ref{chisquare:ex}.
2833
2834 @float Example, chisquare:ex
2835 @psppsyntax {chisquare.sps}
2836 @caption {Performing a chi-square test to check for equal distribution of sexes}
2837 @end float
2838
2839 There is only one test variable, @i{viz:} @exvar{sex}.  The other variables in the dataset
2840 are ignored.
2841
2842 @float Screenshot, chisquare:scr
2843 @psppimage {chisquare}
2844 @caption {Performing a chi-square test using the graphic user interface}
2845 @end float
2846
2847 In @ref{chisquare:res} the summary box shows that in the sample, there are more males
2848 than females.  However the significance of chi-square result is greater than 0.05
2849 --- the most commonly accepted p-value --- and therefore
2850 there is not enough evidence to reject the null hypothesis and one must conclude
2851 that the evidence does not indicate that there is an imbalance of the sexes
2852 in the population.
2853
2854 @float Result, chisquare:res
2855 @psppoutput {chisquare}
2856 @caption {The results of running a chi-square test on @exvar{sex}}
2857 @end float
2858
2859
2860 @node COCHRAN
2861 @subsection Cochran Q Test
2862 @vindex Cochran
2863 @cindex Cochran Q test
2864 @cindex Q, Cochran Q
2865
2866 @display
2867      [ /COCHRAN = @var{var_list} ]
2868 @end display
2869
2870 The Cochran Q test is used to test for differences between three or more groups.
2871 The data for @var{var_list} in all cases must assume exactly two
2872 distinct values (other than missing values).
2873
2874 The value of Q is displayed along with its Asymptotic significance
2875 based on a chi-square distribution.
2876
2877 @node FRIEDMAN
2878 @subsection Friedman Test
2879 @vindex FRIEDMAN
2880 @cindex Friedman test
2881
2882 @display
2883      [ /FRIEDMAN = @var{var_list} ]
2884 @end display
2885
2886 The Friedman test is used to test for differences between repeated measures when
2887 there is no indication that the distributions are normally distributed.
2888
2889 A list of variables which contain the measured data must be given.  The procedure
2890 prints the sum of ranks for each variable, the test statistic and its significance.
2891
2892 @node KENDALL
2893 @subsection Kendall's W Test
2894 @vindex KENDALL
2895 @cindex Kendall's W test
2896 @cindex coefficient of concordance
2897
2898 @display
2899      [ /KENDALL = @var{var_list} ]
2900 @end display
2901
2902 The Kendall test investigates whether an arbitrary number of related samples come from the
2903 same population.
2904 It is identical to the Friedman test except that the additional statistic W, Kendall's Coefficient of Concordance is printed.
2905 It has the range [0,1] --- a value of zero indicates no agreement between the samples whereas a value of
2906 unity indicates complete agreement.
2907
2908
2909 @node KOLMOGOROV-SMIRNOV
2910 @subsection Kolmogorov-Smirnov Test
2911 @vindex KOLMOGOROV-SMIRNOV
2912 @vindex K-S
2913 @cindex Kolmogorov-Smirnov test
2914
2915 @display
2916      [ /KOLMOGOROV-SMIRNOV (@{NORMAL [@var{mu}, @var{sigma}], UNIFORM [@var{min}, @var{max}], POISSON [@var{lambda}], EXPONENTIAL [@var{scale}] @}) = @var{var_list} ]
2917 @end display
2918
2919 The one sample Kolmogorov-Smirnov subcommand is used to test whether or not a dataset is
2920 drawn from a particular distribution.  Four distributions are supported, @i{viz:}
2921 Normal, Uniform, Poisson and Exponential.
2922
2923 Ideally you should provide the parameters of the distribution against
2924 which you wish to test the data. For example, with the normal
2925 distribution  the mean (@var{mu})and standard deviation (@var{sigma})
2926 should be given; with the uniform distribution, the minimum
2927 (@var{min})and maximum (@var{max}) value should be provided.
2928 However, if the parameters are omitted they are imputed from the
2929 data.  Imputing the parameters reduces the power of the test so should
2930 be avoided if possible.
2931
2932 In the following example, two variables @var{score} and @var{age} are
2933 tested to see if they follow a normal distribution with a mean of 3.5
2934 and a standard deviation of 2.0.
2935 @example
2936   NPAR TESTS
2937         /KOLMOGOROV-SMIRNOV (normal 3.5 2.0) = @var{score} @var{age}.
2938 @end example
2939 If the variables need to be tested against different distributions, then a separate
2940 subcommand must be used.  For example the following syntax tests @var{score} against
2941 a normal distribution with mean of 3.5 and standard deviation of 2.0 whilst @var{age}
2942 is tested against a normal distribution of mean 40 and standard deviation 1.5.
2943 @example
2944   NPAR TESTS
2945         /KOLMOGOROV-SMIRNOV (normal 3.5 2.0) = @var{score}
2946         /KOLMOGOROV-SMIRNOV (normal 40 1.5) =  @var{age}.
2947 @end example
2948
2949 The abbreviated subcommand  @subcmd{K-S} may be used in place of @subcmd{KOLMOGOROV-SMIRNOV}.
2950
2951 @node KRUSKAL-WALLIS
2952 @subsection Kruskal-Wallis Test
2953 @vindex KRUSKAL-WALLIS
2954 @vindex K-W
2955 @cindex Kruskal-Wallis test
2956
2957 @display
2958      [ /KRUSKAL-WALLIS = @var{var_list} BY var (@var{lower}, @var{upper}) ]
2959 @end display
2960
2961 The Kruskal-Wallis test is used to compare data from an
2962 arbitrary number of populations.  It does not assume normality.
2963 The data to be compared are specified by @var{var_list}.
2964 The categorical variable determining the groups to which the
2965 data belongs is given by @var{var}. The limits @var{lower} and
2966 @var{upper} specify the valid range of @var{var}.
2967 If @var{upper} is smaller than @var{lower}, the PSPP will assume their values
2968 to be reversed. Any cases for which @var{var} falls outside
2969 [@var{lower}, @var{upper}] are ignored.
2970
2971 The mean rank of each group as well as the chi-squared value and
2972 significance of the test are printed.
2973 The abbreviated subcommand  @subcmd{K-W} may be used in place of
2974 @subcmd{KRUSKAL-WALLIS}.
2975
2976
2977 @node MANN-WHITNEY
2978 @subsection Mann-Whitney U Test
2979 @vindex MANN-WHITNEY
2980 @vindex M-W
2981 @cindex Mann-Whitney U test
2982 @cindex U, Mann-Whitney U
2983
2984 @display
2985      [ /MANN-WHITNEY = @var{var_list} BY var (@var{group1}, @var{group2}) ]
2986 @end display
2987
2988 The Mann-Whitney subcommand is used to test whether two groups of data
2989 come from different populations. The variables to be tested should be
2990 specified in @var{var_list} and the grouping variable, that determines
2991 to which group the test variables belong, in @var{var}.
2992 @var{Var} may be either a string or an alpha variable.
2993 @var{Group1} and @var{group2} specify the
2994 two values of @var{var} which determine the groups of the test data.
2995 Cases for which the @var{var} value is neither @var{group1} or
2996 @var{group2} are ignored.
2997
2998 The value of the Mann-Whitney U statistic, the Wilcoxon W, and the
2999 significance are printed.
3000 You may abbreviated the subcommand @subcmd{MANN-WHITNEY} to
3001 @subcmd{M-W}.
3002
3003
3004 @node MCNEMAR
3005 @subsection McNemar Test
3006 @vindex MCNEMAR
3007 @cindex McNemar test
3008
3009 @display
3010      [ /MCNEMAR @var{var_list} [ WITH @var{var_list} [ (PAIRED) ]]]
3011 @end display
3012
3013 Use McNemar's test to analyse the significance of the difference between
3014 pairs of correlated proportions.
3015
3016 If the @code{WITH} keyword is omitted, then tests for all
3017 combinations of the listed variables are performed.
3018 If the @code{WITH} keyword is given, and the @code{(PAIRED)} keyword
3019 is also given, then the number of variables preceding @code{WITH}
3020 must be the same as the number following it.
3021 In this case, tests for each respective pair of variables are
3022 performed.
3023 If the @code{WITH} keyword is given, but the
3024 @code{(PAIRED)} keyword is omitted, then tests for each combination
3025 of variable preceding @code{WITH} against variable following
3026 @code{WITH} are performed.
3027
3028 The data in each variable must be dichotomous.  If there are more
3029 than two distinct variables an error will occur and the test will
3030 not be run.
3031
3032 @node MEDIAN
3033 @subsection Median Test
3034 @vindex MEDIAN
3035 @cindex Median test
3036
3037 @display
3038      [ /MEDIAN [(@var{value})] = @var{var_list} BY @var{variable} (@var{value1}, @var{value2}) ]
3039 @end display
3040
3041 The median test is used to test whether independent samples come from
3042 populations with a common median.
3043 The median of the populations against which the samples are to be tested
3044 may be given in parentheses immediately after the
3045 @subcmd{/MEDIAN} subcommand.  If it is not given, the median is imputed from the
3046 union of all the samples.
3047
3048 The variables of the samples to be tested should immediately follow the @samp{=} sign. The
3049 keyword @code{BY} must come next, and then the grouping variable.  Two values
3050 in parentheses should follow.  If the first value is greater than the second,
3051 then a 2 sample test is performed using these two values to determine the groups.
3052 If however, the first variable is less than the second, then a @i{k} sample test is
3053 conducted and the group values used are all values encountered which lie in the
3054 range [@var{value1},@var{value2}].
3055
3056
3057 @node RUNS
3058 @subsection Runs Test
3059 @vindex RUNS
3060 @cindex runs test
3061
3062 @display
3063      [ /RUNS (@{MEAN, MEDIAN, MODE, @var{value}@})  = @var{var_list} ]
3064 @end display
3065
3066 The @subcmd{/RUNS} subcommand tests whether a data sequence is randomly ordered.
3067
3068 It works by examining the number of times a variable's value crosses a given threshold.
3069 The desired threshold must be specified within parentheses.
3070 It may either be specified as a number or as one of @subcmd{MEAN}, @subcmd{MEDIAN} or @subcmd{MODE}.
3071 Following the threshold specification comes the list of variables whose values are to be
3072 tested.
3073
3074 The subcommand shows the number of runs, the asymptotic significance based on the
3075 length of the data.
3076
3077 @node SIGN
3078 @subsection Sign Test
3079 @vindex SIGN
3080 @cindex sign test
3081
3082 @display
3083      [ /SIGN @var{var_list} [ WITH @var{var_list} [ (PAIRED) ]]]
3084 @end display
3085
3086 The @subcmd{/SIGN} subcommand tests for differences between medians of the
3087 variables listed.
3088 The test does not make any assumptions about the
3089 distribution of the data.
3090
3091 If the @code{WITH} keyword is omitted, then tests for all
3092 combinations of the listed variables are performed.
3093 If the @code{WITH} keyword is given, and the @code{(PAIRED)} keyword
3094 is also given, then the number of variables preceding @code{WITH}
3095 must be the same as the number following it.
3096 In this case, tests for each respective pair of variables are
3097 performed.
3098 If the @code{WITH} keyword is given, but the
3099 @code{(PAIRED)} keyword is omitted, then tests for each combination
3100 of variable preceding @code{WITH} against variable following
3101 @code{WITH} are performed.
3102
3103 @node WILCOXON
3104 @subsection Wilcoxon Matched Pairs Signed Ranks Test
3105 @vindex WILCOXON
3106 @cindex wilcoxon matched pairs signed ranks test
3107
3108 @display
3109      [ /WILCOXON @var{var_list} [ WITH @var{var_list} [ (PAIRED) ]]]
3110 @end display
3111
3112 The @subcmd{/WILCOXON} subcommand tests for differences between medians of the
3113 variables listed.
3114 The test does not make any assumptions about the variances of the samples.
3115 It does however assume that the distribution is symmetrical.
3116
3117 If the @subcmd{WITH} keyword is omitted, then tests for all
3118 combinations of the listed variables are performed.
3119 If the @subcmd{WITH} keyword is given, and the @subcmd{(PAIRED)} keyword
3120 is also given, then the number of variables preceding @subcmd{WITH}
3121 must be the same as the number following it.
3122 In this case, tests for each respective pair of variables are
3123 performed.
3124 If the @subcmd{WITH} keyword is given, but the
3125 @subcmd{(PAIRED)} keyword is omitted, then tests for each combination
3126 of variable preceding @subcmd{WITH} against variable following
3127 @subcmd{WITH} are performed.
3128
3129 @node T-TEST
3130 @section T-TEST
3131
3132 @vindex T-TEST
3133
3134 @display
3135 T-TEST
3136         /MISSING=@{ANALYSIS,LISTWISE@} @{EXCLUDE,INCLUDE@}
3137         /CRITERIA=CI(@var{confidence})
3138
3139
3140 (One Sample mode.)
3141         TESTVAL=@var{test_value}
3142         /VARIABLES=@var{var_list}
3143
3144
3145 (Independent Samples mode.)
3146         GROUPS=var(@var{value1} [, @var{value2}])
3147         /VARIABLES=@var{var_list}
3148
3149
3150 (Paired Samples mode.)
3151         PAIRS=@var{var_list} [WITH @var{var_list} [(PAIRED)] ]
3152
3153 @end display
3154
3155
3156 The @cmd{T-TEST} procedure outputs tables used in testing hypotheses about
3157 means.
3158 It operates in one of three modes:
3159 @itemize
3160 @item One Sample mode.
3161 @item Independent Groups mode.
3162 @item Paired mode.
3163 @end itemize
3164
3165 @noindent
3166 Each of these modes are described in more detail below.
3167 There are two optional subcommands which are common to all modes.
3168
3169 The @cmd{/CRITERIA} subcommand tells @pspp{} the confidence interval used
3170 in the tests.  The default value is 0.95.
3171
3172
3173 The @cmd{MISSING} subcommand determines the handling of missing
3174 variables.
3175 If @subcmd{INCLUDE} is set, then user-missing values are included in the
3176 calculations, but system-missing values are not.
3177 If @subcmd{EXCLUDE} is set, which is the default, user-missing
3178 values are excluded as well as system-missing values.
3179 This is the default.
3180
3181 If @subcmd{LISTWISE} is set, then the entire case is excluded from analysis
3182 whenever any variable  specified in the @subcmd{/VARIABLES}, @subcmd{/PAIRS} or
3183 @subcmd{/GROUPS} subcommands contains a missing value.
3184 If @subcmd{ANALYSIS} is set, then missing values are excluded only in the analysis for
3185 which they would be needed. This is the default.
3186
3187
3188 @menu
3189 * One Sample Mode::             Testing against a hypothesized mean
3190 * Independent Samples Mode::    Testing two independent groups for equal mean
3191 * Paired Samples Mode::         Testing two interdependent groups for equal mean
3192 @end menu
3193
3194 @node One Sample Mode
3195 @subsection One Sample Mode
3196
3197 The @subcmd{TESTVAL} subcommand invokes the One Sample mode.
3198 This mode is used to test a population mean against a hypothesized
3199 mean.
3200 The value given to the @subcmd{TESTVAL} subcommand is the value against
3201 which you wish to test.
3202 In this mode, you must also use the @subcmd{/VARIABLES} subcommand to
3203 tell @pspp{} which variables you wish to test.
3204
3205 @subsubsection Example - One Sample T-test
3206
3207 A researcher wishes to know whether the weight of persons in a population
3208 is different from the national average.
3209 The samples are drawn from the population under investigation and recorded
3210 in the file @file{physiology.sav}.
3211 From the Department of Health, she
3212 knows that the national average weight of healthy adults is 76.8kg.
3213 Accordingly the @subcmd{TESTVAL} is set to 76.8.
3214 The null hypothesis therefore is that the mean average weight of the
3215 population from which the sample was drawn is 76.8kg.
3216
3217 As previously noted (@pxref{Identifying incorrect data}), one
3218 sample in the dataset contains a weight value
3219 which is clearly incorrect.  So this is excluded from the analysis
3220 using the @cmd{SELECT} command.
3221
3222 @float Example, one-sample-t:ex
3223 @psppsyntax {one-sample-t.sps}
3224 @caption {Running a one sample T-Test after excluding all non-positive values}
3225 @end float
3226
3227 @float Screenshot, one-sample-t:scr
3228 @psppimage {one-sample-t}
3229 @caption {Using the One Sample T-Test dialog box to test @exvar{weight} for a mean of 76.8kg}
3230 @end float
3231
3232
3233 @ref{one-sample-t:res} shows that the mean of our sample differs from the test value
3234 by -1.40kg.  However the significance is very high (0.610).  So one cannot
3235 reject the null hypothesis, and must conclude there is not enough evidence
3236 to suggest that the mean weight of the persons in our population is different
3237 from 76.8kg.
3238
3239 @float Results, one-sample-t:res
3240 @psppoutput {one-sample-t}
3241 @caption {The results of a one sample T-test of @exvar{weight} using a test value of 76.8kg}
3242 @end float
3243
3244 @node Independent Samples Mode
3245 @subsection Independent Samples Mode
3246
3247 The @subcmd{GROUPS} subcommand invokes Independent Samples mode or
3248 `Groups' mode.
3249 This mode is used to test whether two groups of values have the
3250 same population mean.
3251 In this mode, you must also use the @subcmd{/VARIABLES} subcommand to
3252 tell @pspp{} the dependent variables you wish to test.
3253
3254 The variable given in the @subcmd{GROUPS} subcommand is the independent
3255 variable which determines to which group the samples belong.
3256 The values in parentheses are the specific values of the independent
3257 variable for each group.
3258 If the parentheses are omitted and no values are given, the default values
3259 of 1.0 and 2.0 are assumed.
3260
3261 If the independent variable is numeric,
3262 it is acceptable to specify only one value inside the parentheses.
3263 If you do this, cases where the independent variable is
3264 greater than or equal to this value belong to the first group, and cases
3265 less than this value belong to the second group.
3266 When using this form of the @subcmd{GROUPS} subcommand, missing values in
3267 the independent variable are excluded on a listwise basis, regardless
3268 of whether @subcmd{/MISSING=LISTWISE} was specified.
3269
3270 @subsubsection Example - Independent Samples T-test
3271
3272 A researcher wishes to know whether within a population, adult males
3273 are taller than adult females.
3274 The samples are drawn from the population under investigation and recorded
3275 in the file @file{physiology.sav}.
3276
3277 As previously noted (@pxref{Identifying incorrect data}), one
3278 sample in the dataset contains a height value
3279 which is clearly incorrect.  So this is excluded from the analysis
3280 using the @cmd{SELECT} command.
3281
3282
3283 @float Example, indepdendent-samples-t:ex
3284 @psppsyntax {independent-samples-t.sps}
3285 @caption {Running a independent samples T-Test after excluding all observations less than 200kg}
3286 @end float
3287
3288
3289 The null hypothesis is that both males and females are on average
3290 of equal height.
3291
3292 @float Screenshot, independent-samples-t:scr
3293 @psppimage {independent-samples-t}
3294 @caption {Using the Independent Sample T-test dialog, to test for differences of @exvar{height} between values of @exvar{sex}}
3295 @end float
3296
3297
3298 In this case, the grouping variable is @exvar{sex}, so this is entered
3299 as the variable for the @subcmd{GROUP} subcommand.  The group values are  0 (male) and
3300 1 (female).
3301
3302 If you are running the proceedure using syntax, then you need to enter
3303 the values corresponding to each group within parentheses.
3304 If you are using the graphic user interface, then you have to open
3305 the ``Define Groups'' dialog box and enter the values corresponding
3306 to each group as shown in @ref{define-groups-t:scr}.  If, as in this case, the dataset has defined value
3307 labels for the group variable, then you can enter them by label
3308 or by value.
3309
3310 @float Screenshot, define-groups-t:scr
3311 @psppimage {define-groups-t}
3312 @caption {Setting the values of the grouping variable for an Independent Samples T-test}
3313 @end float
3314
3315 From @ref{independent-samples-t:res}, one can clearly see that the @emph{sample} mean height
3316 is greater for males than for females.  However in order to see if this
3317 is a significant result, one must consult the T-Test table.
3318
3319 The T-Test table contains two rows; one for use if the variance of the samples
3320 in each group may be safely assumed to be equal, and the second row
3321 if the variances in each group may not be safely assumed to be equal.
3322
3323 In this case however, both rows show a 2-tailed significance less than 0.001 and
3324 one must therefore reject the null hypothesis and conclude that within
3325 the population the mean height of males and of females are unequal.
3326
3327 @float Result, independent-samples-t:res
3328 @psppoutput {independent-samples-t}
3329 @caption {The results of an independent samples T-test of @exvar{height} by @exvar{sex}}
3330 @end float
3331
3332 @node Paired Samples Mode
3333 @subsection Paired Samples Mode
3334
3335 The @cmd{PAIRS} subcommand introduces Paired Samples mode.
3336 Use this mode when repeated measures have been taken from the same
3337 samples.
3338 If the @subcmd{WITH} keyword is omitted, then tables for all
3339 combinations of variables given in the @cmd{PAIRS} subcommand are
3340 generated.
3341 If the @subcmd{WITH} keyword is given, and the @subcmd{(PAIRED)} keyword
3342 is also given, then the number of variables preceding @subcmd{WITH}
3343 must be the same as the number following it.
3344 In this case, tables for each respective pair of variables are
3345 generated.
3346 In the event that the @subcmd{WITH} keyword is given, but the
3347 @subcmd{(PAIRED)} keyword is omitted, then tables for each combination
3348 of variable preceding @subcmd{WITH} against variable following
3349 @subcmd{WITH} are generated.
3350
3351
3352 @node ONEWAY
3353 @section ONEWAY
3354
3355 @vindex ONEWAY
3356 @cindex analysis of variance
3357 @cindex ANOVA
3358
3359 @display
3360 ONEWAY
3361         [/VARIABLES = ] @var{var_list} BY @var{var}
3362         /MISSING=@{ANALYSIS,LISTWISE@} @{EXCLUDE,INCLUDE@}
3363         /CONTRAST= @var{value1} [, @var{value2}] ... [,@var{valueN}]
3364         /STATISTICS=@{DESCRIPTIVES,HOMOGENEITY@}
3365         /POSTHOC=@{BONFERRONI, GH, LSD, SCHEFFE, SIDAK, TUKEY, ALPHA ([@var{value}])@}
3366 @end display
3367
3368 The @cmd{ONEWAY} procedure performs a one-way analysis of variance of
3369 variables factored by a single independent variable.
3370 It is used to compare the means of a population
3371 divided into more than two groups.
3372
3373 The dependent variables to be analysed should be given in the @subcmd{VARIABLES}
3374 subcommand.
3375 The list of variables must be followed by the @subcmd{BY} keyword and
3376 the name of the independent (or factor) variable.
3377
3378 You can use the @subcmd{STATISTICS} subcommand to tell @pspp{} to display
3379 ancillary information.  The options accepted are:
3380 @itemize
3381 @item DESCRIPTIVES
3382 Displays descriptive statistics about the groups factored by the independent
3383 variable.
3384 @item HOMOGENEITY
3385 Displays the Levene test of Homogeneity of Variance for the
3386 variables and their groups.
3387 @end itemize
3388
3389 The @subcmd{CONTRAST} subcommand is used when you anticipate certain
3390 differences between the groups.
3391 The subcommand must be followed by a list of numerals which are the
3392 coefficients of the groups to be tested.
3393 The number of coefficients must correspond to the number of distinct
3394 groups (or values of the independent variable).
3395 If the total sum of the coefficients are not zero, then @pspp{} will
3396 display a warning, but will proceed with the analysis.
3397 The @subcmd{CONTRAST} subcommand may be given up to 10 times in order
3398 to specify different contrast tests.
3399 The @subcmd{MISSING} subcommand defines how missing values are handled.
3400 If @subcmd{LISTWISE} is specified then cases which have missing values for
3401 the independent variable or any dependent variable are ignored.
3402 If @subcmd{ANALYSIS} is specified, then cases are ignored if the independent
3403 variable is missing or if the dependent variable currently being
3404 analysed is missing.  The default is @subcmd{ANALYSIS}.
3405 A setting of @subcmd{EXCLUDE} means that variables whose values are
3406 user-missing are to be excluded from the analysis. A setting of
3407 @subcmd{INCLUDE} means they are to be included.  The default is @subcmd{EXCLUDE}.
3408
3409 Using the @code{POSTHOC} subcommand you can perform multiple
3410 pairwise comparisons on the data. The following comparison methods
3411 are available:
3412 @itemize
3413 @item @subcmd{LSD}
3414 Least Significant Difference.
3415 @item @subcmd{TUKEY}
3416 Tukey Honestly Significant Difference.
3417 @item @subcmd{BONFERRONI}
3418 Bonferroni test.
3419 @item @subcmd{SCHEFFE}
3420 Scheff@'e's test.
3421 @item @subcmd{SIDAK}
3422 Sidak test.
3423 @item @subcmd{GH}
3424 The Games-Howell test.
3425 @end itemize
3426
3427 @noindent
3428 Use the optional syntax @code{ALPHA(@var{value})} to indicate that
3429 @cmd{ONEWAY} should perform the posthoc tests at a confidence level of
3430 @var{value}.  If @code{ALPHA(@var{value})} is not specified, then the
3431 confidence level used is 0.05.
3432
3433 @node QUICK CLUSTER
3434 @section QUICK CLUSTER
3435 @vindex QUICK CLUSTER
3436
3437 @cindex K-means clustering
3438 @cindex clustering
3439
3440 @display
3441 QUICK CLUSTER @var{var_list}
3442       [/CRITERIA=CLUSTERS(@var{k}) [MXITER(@var{max_iter})] CONVERGE(@var{epsilon}) [NOINITIAL]]
3443       [/MISSING=@{EXCLUDE,INCLUDE@} @{LISTWISE, PAIRWISE@}]
3444       [/PRINT=@{INITIAL@} @{CLUSTER@}]
3445       [/SAVE[=[CLUSTER[(@var{membership_var})]] [DISTANCE[(@var{distance_var})]]]
3446 @end display
3447
3448 The @cmd{QUICK CLUSTER} command performs k-means clustering on the
3449 dataset.  This is useful when you wish to allocate cases into clusters
3450 of similar values and you already know the number of clusters.
3451
3452 The minimum specification is @samp{QUICK CLUSTER} followed by the names
3453 of the variables which contain the cluster data.  Normally you will also
3454 want to specify @subcmd{/CRITERIA=CLUSTERS(@var{k})} where @var{k} is the
3455 number of clusters.  If this is not specified, then @var{k} defaults to 2.
3456
3457 If you use @subcmd{/CRITERIA=NOINITIAL} then a naive algorithm to select
3458 the initial clusters is used.   This will provide for faster execution but
3459 less well separated initial clusters and hence possibly an inferior final
3460 result.
3461
3462
3463 @cmd{QUICK CLUSTER} uses an iterative algorithm to select the clusters centers.
3464 The subcommand  @subcmd{/CRITERIA=MXITER(@var{max_iter})} sets the maximum number of iterations.
3465 During classification, @pspp{} will continue iterating until until @var{max_iter}
3466 iterations have been done or the convergence criterion (see below) is fulfilled.
3467 The default value of @var{max_iter} is 2.
3468
3469 If however, you specify @subcmd{/CRITERIA=NOUPDATE} then after selecting the initial centers,
3470 no further update to the cluster centers is done.  In this case, @var{max_iter}, if specified.
3471 is ignored.
3472
3473 The subcommand  @subcmd{/CRITERIA=CONVERGE(@var{epsilon})} is used
3474 to set the convergence criterion.  The value of convergence criterion is  @var{epsilon}
3475 times the minimum distance between the @emph{initial} cluster centers.  Iteration stops when
3476 the  mean cluster distance between  one iteration and the next
3477 is less than the convergence criterion.  The default value of @var{epsilon} is zero.
3478
3479 The @subcmd{MISSING} subcommand determines the handling of missing variables.
3480 If @subcmd{INCLUDE} is set, then user-missing values are considered at their face
3481 value and not as missing values.
3482 If @subcmd{EXCLUDE} is set, which is the default, user-missing
3483 values are excluded as well as system-missing values.
3484
3485 If @subcmd{LISTWISE} is set, then the entire case is excluded from the analysis
3486 whenever any of the clustering variables contains a missing value.
3487 If @subcmd{PAIRWISE} is set, then a case is considered missing only if all the
3488 clustering variables contain missing values.  Otherwise it is clustered
3489 on the basis of the non-missing values.
3490 The default is @subcmd{LISTWISE}.
3491
3492 The @subcmd{PRINT} subcommand requests additional output to be printed.
3493 If @subcmd{INITIAL} is set, then the initial cluster memberships will
3494 be printed.
3495 If @subcmd{CLUSTER} is set, the cluster memberships of the individual
3496 cases are displayed (potentially generating lengthy output).
3497
3498 You can specify the subcommand @subcmd{SAVE} to ask that each case's cluster membership
3499 and the euclidean distance between the case and its cluster center be saved to
3500 a new variable in the active dataset.   To save the cluster membership use the
3501 @subcmd{CLUSTER} keyword and to save the distance use the @subcmd{DISTANCE} keyword.
3502 Each keyword may optionally be followed by a variable name in parentheses to specify
3503 the new variable which is to contain the saved parameter.  If no variable name is specified,
3504 then PSPP will create one.
3505
3506 @node RANK
3507 @section RANK
3508
3509 @vindex RANK
3510 @display
3511 RANK
3512         [VARIABLES=] @var{var_list} [@{A,D@}] [BY @var{var_list}]
3513         /TIES=@{MEAN,LOW,HIGH,CONDENSE@}
3514         /FRACTION=@{BLOM,TUKEY,VW,RANKIT@}
3515         /PRINT[=@{YES,NO@}
3516         /MISSING=@{EXCLUDE,INCLUDE@}
3517
3518         /RANK [INTO @var{var_list}]
3519         /NTILES(k) [INTO @var{var_list}]
3520         /NORMAL [INTO @var{var_list}]
3521         /PERCENT [INTO @var{var_list}]
3522         /RFRACTION [INTO @var{var_list}]
3523         /PROPORTION [INTO @var{var_list}]
3524         /N [INTO @var{var_list}]
3525         /SAVAGE [INTO @var{var_list}]
3526 @end display
3527
3528 The @cmd{RANK} command ranks variables and stores the results into new
3529 variables.
3530
3531 The @subcmd{VARIABLES} subcommand, which is mandatory, specifies one or
3532 more variables whose values are to be ranked.
3533 After each variable, @samp{A} or @samp{D} may appear, indicating that
3534 the variable is to be ranked in ascending or descending order.
3535 Ascending is the default.
3536 If a @subcmd{BY} keyword appears, it should be followed by a list of variables
3537 which are to serve as group variables.
3538 In this case, the cases are gathered into groups, and ranks calculated
3539 for each group.
3540
3541 The @subcmd{TIES} subcommand specifies how tied values are to be treated.  The
3542 default is to take the mean value of all the tied cases.
3543
3544 The @subcmd{FRACTION} subcommand specifies how proportional ranks are to be
3545 calculated.  This only has any effect if @subcmd{NORMAL} or @subcmd{PROPORTIONAL} rank
3546 functions are requested.
3547
3548 The @subcmd{PRINT} subcommand may be used to specify that a summary of the rank
3549 variables created should appear in the output.
3550
3551 The function subcommands are @subcmd{RANK}, @subcmd{NTILES}, @subcmd{NORMAL}, @subcmd{PERCENT}, @subcmd{RFRACTION},
3552 @subcmd{PROPORTION} and @subcmd{SAVAGE}.  Any number of function subcommands may appear.
3553 If none are given, then the default is RANK.
3554 The @subcmd{NTILES} subcommand must take an integer specifying the number of
3555 partitions into which values should be ranked.
3556 Each subcommand may be followed by the @subcmd{INTO} keyword and a list of
3557 variables which are the variables to be created and receive the rank
3558 scores.  There may be as many variables specified as there are
3559 variables named on the @subcmd{VARIABLES} subcommand.  If fewer are specified,
3560 then the variable names are automatically created.
3561
3562 The @subcmd{MISSING} subcommand determines how user missing values are to be
3563 treated. A setting of @subcmd{EXCLUDE} means that variables whose values are
3564 user-missing are to be excluded from the rank scores. A setting of
3565 @subcmd{INCLUDE} means they are to be included.  The default is @subcmd{EXCLUDE}.
3566
3567 @include regression.texi
3568
3569
3570 @node RELIABILITY
3571 @section RELIABILITY
3572
3573 @vindex RELIABILITY
3574 @display
3575 RELIABILITY
3576         /VARIABLES=@var{var_list}
3577         /SCALE (@var{name}) = @{@var{var_list}, ALL@}
3578         /MODEL=@{ALPHA, SPLIT[(@var{n})]@}
3579         /SUMMARY=@{TOTAL,ALL@}
3580         /MISSING=@{EXCLUDE,INCLUDE@}
3581 @end display
3582
3583 @cindex Cronbach's Alpha
3584 The @cmd{RELIABILITY} command performs reliability analysis on the data.
3585
3586 The @subcmd{VARIABLES} subcommand is required. It determines the set of variables
3587 upon which analysis is to be performed.
3588
3589 The @subcmd{SCALE} subcommand determines the  variables for which
3590 reliability is to be calculated.  If @subcmd{SCALE} is omitted, then analysis for
3591 all variables named in the @subcmd{VARIABLES} subcommand are used.
3592 Optionally, the @var{name} parameter may be specified to set a string name
3593 for the scale.
3594
3595 The @subcmd{MODEL} subcommand determines the type of analysis. If @subcmd{ALPHA} is specified,
3596 then Cronbach's Alpha is calculated for the scale.  If the model is @subcmd{SPLIT},
3597 then the variables  are divided into 2 subsets.  An optional parameter
3598 @var{n} may be given, to specify how many variables to be in the first subset.
3599 If @var{n} is omitted, then it defaults to one half of the variables in the
3600 scale, or one half minus one if there are an odd number of variables.
3601 The default model is @subcmd{ALPHA}.
3602
3603 By default, any cases with user missing, or system missing values for
3604 any variables given in the @subcmd{VARIABLES} subcommand are omitted
3605 from the analysis.  The @subcmd{MISSING} subcommand determines whether
3606 user missing values are included or excluded in the analysis.
3607
3608 The @subcmd{SUMMARY} subcommand determines the type of summary analysis to be performed.
3609 Currently there is only one type: @subcmd{SUMMARY=TOTAL}, which displays per-item
3610 analysis tested against the totals.
3611
3612 @subsection Example - Reliability
3613
3614 Before analysing the results of a survey -- particularly for a multiple choice survey --
3615 it is desireable to know whether the respondents have considered their answers
3616 or simply provided random answers.
3617
3618 In the following example the survey results from the file @file{hotel.sav} are used.
3619 All five survey questions are included in the reliability analysis.
3620 However, before running the analysis, the data must be preprocessed.
3621 An examination of the survey questions reveals that two questions, @i{viz:} v3 and v5
3622 are negatively worded, whereas the others are positively worded.
3623 All questions must be based upon the same scale for the analysis to be meaningful.
3624 One could use the @cmd{RECODE} command (@pxref{RECODE}), however a simpler way is
3625 to use @cmd{COMPUTE} (@pxref{COMPUTE}) and this is what is done in @ref{reliability:ex}.
3626
3627 @float Example, reliability:ex
3628 @psppsyntax {reliability.sps}
3629 @caption {Investigating the reliability of survey responses}
3630 @end float
3631
3632 In this case, all variables in the data set are used.  So we can use the special
3633 keyword @samp{ALL} (@pxref{BNF}).
3634
3635 @float Screenshot, reliability:src
3636 @psppimage {reliability}
3637 @caption {Reliability dialog box with all variables selected}
3638 @end float
3639
3640 @ref{reliability:res} shows that Cronbach's Alpha is 0.11  which is a value normally considered too
3641 low to indicate consistency within the data.  This is possibly due to the small number of
3642 survey questions.  The survey should be redesigned before serious use of the results are
3643 applied.
3644
3645 @float Result, reliability:res
3646 @psppoutput {reliability}
3647 @caption {The results of the reliability command on @file{hotel.sav}}
3648 @end float
3649
3650
3651 @node ROC
3652 @section ROC
3653
3654 @vindex ROC
3655 @cindex Receiver Operating Characteristic
3656 @cindex Area under curve
3657
3658 @display
3659 ROC     @var{var_list} BY @var{state_var} (@var{state_value})
3660         /PLOT = @{ CURVE [(REFERENCE)], NONE @}
3661         /PRINT = [ SE ] [ COORDINATES ]
3662         /CRITERIA = [ CUTOFF(@{INCLUDE,EXCLUDE@}) ]
3663           [ TESTPOS (@{LARGE,SMALL@}) ]
3664           [ CI (@var{confidence}) ]
3665           [ DISTRIBUTION (@{FREE, NEGEXPO @}) ]
3666         /MISSING=@{EXCLUDE,INCLUDE@}
3667 @end display
3668
3669
3670 The @cmd{ROC} command is used to plot the receiver operating characteristic curve
3671 of a dataset, and to estimate the area under the curve.
3672 This is useful for analysing the efficacy of a variable as a predictor of a state of nature.
3673
3674 The mandatory @var{var_list} is the list of predictor variables.
3675 The variable @var{state_var} is the variable whose values represent the actual states,
3676 and @var{state_value} is the value of this variable which represents the positive state.
3677
3678 The optional subcommand @subcmd{PLOT} is used to determine if and how the @subcmd{ROC} curve is drawn.
3679 The keyword @subcmd{CURVE} means that the @subcmd{ROC} curve should be drawn, and the optional keyword @subcmd{REFERENCE},
3680 which should be enclosed in parentheses, says that the diagonal reference line should be drawn.
3681 If the keyword @subcmd{NONE} is given, then no @subcmd{ROC} curve is drawn.
3682 By default, the curve is drawn with no reference line.
3683
3684 The optional subcommand @subcmd{PRINT} determines which additional
3685 tables should be printed.  Two additional tables are available.  The
3686 @subcmd{SE} keyword says that standard error of the area under the
3687 curve should be printed as well as the area itself.  In addition, a
3688 p-value for the null hypothesis that the area under the curve equals
3689 0.5 is printed.   The @subcmd{COORDINATES} keyword says that a
3690 table of coordinates of the @subcmd{ROC} curve should be printed.
3691
3692 The @subcmd{CRITERIA} subcommand has four optional parameters:
3693 @itemize @bullet
3694 @item The @subcmd{TESTPOS} parameter may be @subcmd{LARGE} or @subcmd{SMALL}.
3695 @subcmd{LARGE} is the default, and says that larger values in the predictor variables are to be
3696 considered positive.  @subcmd{SMALL} indicates that smaller values should be considered positive.
3697
3698 @item The @subcmd{CI} parameter specifies the confidence interval that should be printed.
3699 It has no effect if the @subcmd{SE} keyword in the @subcmd{PRINT} subcommand has not been given.
3700
3701 @item The @subcmd{DISTRIBUTION} parameter determines the method to be used when estimating the area
3702 under the curve.
3703 There are two possibilities, @i{viz}: @subcmd{FREE} and @subcmd{NEGEXPO}.
3704 The @subcmd{FREE} method uses a non-parametric estimate, and the @subcmd{NEGEXPO} method a bi-negative
3705 exponential distribution estimate.
3706 The @subcmd{NEGEXPO} method should only be used when the number of positive actual states is
3707 equal to the number of negative actual states.
3708 The default is @subcmd{FREE}.
3709
3710 @item The @subcmd{CUTOFF} parameter is for compatibility and is ignored.
3711 @end itemize
3712
3713 The @subcmd{MISSING} subcommand determines whether user missing values are to
3714 be included or excluded in the analysis.  The default behaviour is to
3715 exclude them.
3716 Cases are excluded on a listwise basis; if any of the variables in @var{var_list}
3717 or if the variable @var{state_var} is missing, then the entire case is
3718 excluded.
3719
3720 @c  LocalWords:  subcmd subcommand