some basic ctables docs
authorBen Pfaff <blp@cs.stanford.edu>
Sat, 26 Feb 2022 03:54:55 +0000 (19:54 -0800)
committerBen Pfaff <blp@cs.stanford.edu>
Sat, 26 Feb 2022 03:54:55 +0000 (19:54 -0800)
doc/automake.mk
doc/pspp-figures/ctables1.sps [new file with mode: 0644]
doc/pspp-figures/ctables2.sps [new file with mode: 0644]
doc/pspp-figures/ctables3.sps [new file with mode: 0644]
doc/pspp-figures/ctables4.sps [new file with mode: 0644]
doc/pspp-figures/ctables5.sps [new file with mode: 0644]
doc/statistics.texi
examples/nhtsa-drinking-2008.sav [new file with mode: 0644]
examples/nhtsa-drinking-2008.sps [new file with mode: 0644]

index 63972bb3e49bbc869ada2657543ad5a96e7af048..cd80a674860105349e135768fb42869bb6dcd2eb 100644 (file)
@@ -117,6 +117,11 @@ FIGURE_SYNTAX = \
  doc/pspp-figures/chisquare.sps \
  doc/pspp-figures/compute.sps \
  doc/pspp-figures/count.sps \
  doc/pspp-figures/chisquare.sps \
  doc/pspp-figures/compute.sps \
  doc/pspp-figures/count.sps \
+ doc/pspp-figures/ctables1.sps \
+ doc/pspp-figures/ctables2.sps \
+ doc/pspp-figures/ctables3.sps \
+ doc/pspp-figures/ctables4.sps \
+ doc/pspp-figures/ctables5.sps \
  doc/pspp-figures/crosstabs.sps \
  doc/pspp-figures/descriptives.sps \
  doc/pspp-figures/flip.sps \
  doc/pspp-figures/crosstabs.sps \
  doc/pspp-figures/descriptives.sps \
  doc/pspp-figures/flip.sps \
diff --git a/doc/pspp-figures/ctables1.sps b/doc/pspp-figures/ctables1.sps
new file mode 100644 (file)
index 0000000..4876fa2
--- /dev/null
@@ -0,0 +1,2 @@
+GET FILE='nhtsa.sav'.
+CTABLES /TABLE=AgeGroup.
\ No newline at end of file
diff --git a/doc/pspp-figures/ctables2.sps b/doc/pspp-figures/ctables2.sps
new file mode 100644 (file)
index 0000000..38b09aa
--- /dev/null
@@ -0,0 +1,2 @@
+GET FILE='nhtsa.sav'.
+CTABLES /TABLE=AgeGroup BY qns3a.
\ No newline at end of file
diff --git a/doc/pspp-figures/ctables3.sps b/doc/pspp-figures/ctables3.sps
new file mode 100644 (file)
index 0000000..4736cce
--- /dev/null
@@ -0,0 +1,2 @@
+GET FILE='nhtsa.sav'.
+CTABLES /TABLE AgeGroup > qns3a BY qn86.
diff --git a/doc/pspp-figures/ctables4.sps b/doc/pspp-figures/ctables4.sps
new file mode 100644 (file)
index 0000000..4ddee23
--- /dev/null
@@ -0,0 +1,2 @@
+GET FILE='nhtsa.sav'.
+CTABLES /TABLE AgeGroup + qn1 BY qns3a.
diff --git a/doc/pspp-figures/ctables5.sps b/doc/pspp-figures/ctables5.sps
new file mode 100644 (file)
index 0000000..ba12f4b
--- /dev/null
@@ -0,0 +1,3 @@
+GET FILE='nhtsa.sav'.
+CTABLES /TABLE qn26 + qn27 > qns3a.
+CTABLES /TABLE (qn26 + qn27) > qns3a.
index c7abe4d88d4cb94a88a9e098913bdaa07656f486..6957b3836eae3a2c07f8bad2f64d30d781db1249 100644 (file)
@@ -30,7 +30,6 @@ far.
 * ONEWAY::                      One way analysis of variance.
 * QUICK CLUSTER::               K-Means clustering.
 * RANK::                        Compute rank scores.
 * ONEWAY::                      One way analysis of variance.
 * QUICK CLUSTER::               K-Means clustering.
 * RANK::                        Compute rank scores.
-* REGRESSION::                  Linear regression.
 * RELIABILITY::                 Reliability analysis.
 * ROC::                         Receiver Operating Characteristic.
 @end menu
 * RELIABILITY::                 Reliability analysis.
 * ROC::                         Receiver Operating Characteristic.
 @end menu
@@ -514,9 +513,9 @@ The @cmd{GRAPH} command produces graphical plots of data. Only one of the subcom
 can be produced per call of @cmd{GRAPH}. The @subcmd{MISSING} is optional.
 
 @menu
 can be produced per call of @cmd{GRAPH}. The @subcmd{MISSING} is optional.
 
 @menu
-* SCATTERPLOT::             Cartesian Plots
-* HISTOGRAM::               Histograms
-* BAR CHART::               Bar Charts
+* SCATTERPLOT::                 Cartesian Plots
+* HISTOGRAM::                   Histograms
+* BAR CHART::                   Bar Charts
 @end menu
 
 @node SCATTERPLOT
 @end menu
 
 @node SCATTERPLOT
@@ -987,16 +986,81 @@ previous @code{TABLE}.  All of these subcommands are optional:
     [@t{SHOWSIG=}@{@t{NO} @math{|} @t{YES}@}]
 @end display
 
     [@t{SHOWSIG=}@{@t{NO} @math{|} @t{YES}@}]
 @end display
 
-The @code{CTABLES} (aka ``custom tables'') command outputs
-multi-dimensional tables, offering many options for table
-summarization and formatting.
+The @code{CTABLES} (aka ``custom tables'') command produces
+multi-dimensional tables from categorical and scale data.  It offers
+many options for data summarization and formatting.
 
 
-@code{TABLE}, the only required subcommand, specifies the variables to
-include on each dimension, using the syntax @t{/TABLE} @i{rows} @t{BY}
-@i{columns} @t{BY} @i{layers}, in which @i{rows}, @i{columns}, and
-@i{layers} is each empty or an @i{axis}.  The simplest form of
-@i{axis} is just a variable name.  
+This section's examples use data from the 2008 (USA) National Survey
+of Drinking and Driving Attitudes and Behaviors, a public domain data
+set from the (USA) National Highway Traffic Administration and
+available at @url{https://data.transportation.gov}.  @pspp{} includes
+this data set, with a slightly modified dictionary, as
+@file{examples/nhtsa.sav}.
 
 
+@menu
+* CTABLES Basics::
+@end menu
+
+@node CTABLES Basics
+@subsection Basics
+
+The only required subcommand is @code{TABLE}, which specifies the
+variables to include along each axis:
+@display
+@t{/TABLE} @i{rows} [@t{BY} @i{columns} [@t{BY} @i{layers}]]
+@end display
+@noindent
+In @code{TABLE}, each of @var{rows}, @var{columns}, and @var{layers}
+is either empty or an axis expression that specifies one or more
+variables.  An axis expression that names a categorical variable
+divides the data into cells according to the values of that variable.
+When all the variables named on @code{TABLE} are categorical, by
+default each cell displays the number of cases that it contains, so
+specifying a single variable yields a frequency table:
+
+@example
+CTABLES /TABLE=AgeGroup.
+@end example
+@psppoutput {ctables1}
+
+@noindent
+Specifying a row and a column categorical variable yields a
+crosstabulation:
+
+@example
+CTABLES /TABLE=AgeGroup BY qns3a.
+@end example
+@psppoutput {ctables2}
+
+@noindent
+The @samp{>} operator nests multiple variables on a single axis, e.g.:
+
+@example
+CTABLES /TABLE qn105ba BY AgeGroup > qns3a.
+@end example
+@psppoutput {ctables3}
+
+@noindent
+The @samp{+} operator allows a single output table to include multiple
+data analyses.  With @samp{+}, @code{CTABLES} divides the output table
+into multiple sections, each of which includes an analysis of the full
+data set.  For example, the following command separately tabulates age
+group and driving frequency by gender:
+
+@example
+CTABLES /TABLE AgeGroup + qn1 BY qns3a.
+@end example
+@psppoutput {ctables4}
+
+@noindent
+If @samp{+} and @samp{>} are used together, @samp{>} binds more
+tightly.  Use parentheses to override operator precedence.  Thus:
+
+@example
+CTABLES /TABLE qn26 + qn27 > qns3a.
+CTABLES /TABLE (qn26 + qn27) > qns3a.
+@end example
+@psppoutput {ctables5}
 
 @node FACTOR
 @section FACTOR
 
 @node FACTOR
 @section FACTOR
@@ -1503,19 +1567,19 @@ is used.
 
 
 @menu
 
 
 @menu
-* BINOMIAL::                Binomial Test
-* CHISQUARE::               Chi-square Test
-* COCHRAN::                 Cochran Q Test
-* FRIEDMAN::                Friedman Test
-* KENDALL::                 Kendall's W Test
-* KOLMOGOROV-SMIRNOV::      Kolmogorov Smirnov Test
-* KRUSKAL-WALLIS::          Kruskal-Wallis Test
-* MANN-WHITNEY::            Mann Whitney U Test
-* MCNEMAR::                 McNemar Test
-* MEDIAN::                  Median Test
-* RUNS::                    Runs Test
-* SIGN::                    The Sign Test
-* WILCOXON::                Wilcoxon Signed Ranks Test
+* BINOMIAL::                    Binomial Test
+* CHISQUARE::                   Chi-square Test
+* COCHRAN::                     Cochran Q Test
+* FRIEDMAN::                    Friedman Test
+* KENDALL::                     Kendall's W Test
+* KOLMOGOROV-SMIRNOV::          Kolmogorov Smirnov Test
+* KRUSKAL-WALLIS::              Kruskal-Wallis Test
+* MANN-WHITNEY::                Mann Whitney U Test
+* MCNEMAR::                     McNemar Test
+* MEDIAN::                      Median Test
+* RUNS::                        Runs Test
+* SIGN::                        The Sign Test
+* WILCOXON::                    Wilcoxon Signed Ranks Test
 @end menu
 
 
 @end menu
 
 
diff --git a/examples/nhtsa-drinking-2008.sav b/examples/nhtsa-drinking-2008.sav
new file mode 100644 (file)
index 0000000..bae9e01
Binary files /dev/null and b/examples/nhtsa-drinking-2008.sav differ
diff --git a/examples/nhtsa-drinking-2008.sps b/examples/nhtsa-drinking-2008.sps
new file mode 100644 (file)
index 0000000..1f56cbb
--- /dev/null
@@ -0,0 +1,96 @@
+GET 'nhtsa-drinking-2008.sav'.
+VARIABLE LEVEL
+   ALL (NOMINAL)
+   ID QN18 QN19A QN20 QN23 QN31 QN35 QN36 QN38 QN41 QN44 QN52 QN65 QN66 QN114 QN121 QN126 QND1 QND1B QND9 (SCALE).
+FORMATS
+    State QNS1 QN1 (F2.0)
+    QN100 QN102 QN103 QN116 QN123 QN131A QN133 QN139A QN139E QN139G QN139H (F1.0).
+MISSING VALUES
+    QNS1 (97, 98, 99)
+    QN1 (6, 7)
+    QN15 (8, 9)
+    QN17 (2, 3)
+    QN18 (98, 99)
+    QN19A (97, 98, 99)
+    QN20 QN23 (98, 99)
+    QN26 QN27 QN28 QN29 (3, 4)
+    QN31 (98, 99)
+    QN33 (3, 4)
+    QN35 (998, 999)
+    QN36 (98, 99)
+    QN37 (2, 3)
+    QN38 (998, 999)
+    QN39H (0)
+    QN39M (0)
+    QN41 (998, 999)
+    QN43A (3, 4)
+    QN44 (98, 99)
+    QN44A (98, 99)
+    QN49 (5, 6)
+    QN52 (998, 999)
+    QN56 (2, 3)
+    QN57 (3, 4)
+    QN61 (3, 4)
+    QN64B (3, 4)
+    QN65 (98, 99)
+    QN65A (3, 4)
+    QN66 (98, 99)
+    QN86 (3, 4)
+    QN87 (6, 7)
+    QN88_1 QN88_2 QN88_3 (2, 3)
+    QN89 QN90 QN90A (3, 4)
+    QN91_1 QN91_2 QN91_3 (2, 3)
+    QN96A (3, 4)
+    QN100 (3, 4)
+    QN101 (2, 3)
+    QN102 QN102B QN102C (3, 4)
+    QN103 (4, 5)
+    QN105BA QN105BB QN105BC QN105BD (6, 7)
+    QN113 (3, 4)
+    QN114 (98, 99)
+    QN116 (7, 8)
+    QN120 (3, 4)
+    QN121 (998, 999)
+    QN122C (6, 7)
+    QN123 (3, 4)
+    QN126 (98, 99)
+    QN131A (3, 4)
+    QN132A (3, 4)
+    QN133 (3, 4)
+    QN139A QN139E QN139G QN139H QN139K QN139L QN139M QN139N (6, 7)
+    QN139_A (3, 4)
+    QN139_B (98, 99)
+    QN139CA QN139CE QN139CF QN139CG QN139CH QN139CK QN139CL QN139CN (6, 7)
+    QN140AA QN140AB QN140AC QN140AD QN140AE QN140AF (6, 7)
+    QND1 (998, 999)
+    QND1B (8, 9)
+    QND2_1 QND2_2 QND2_3 (2, 3)
+    QND3 (10, 11)
+    QND5 (3, 4)
+    QND5A (9, 10)
+    QND6_1 QND6_2 QND6_3 QND6_4 QND6_5 (2, 3)
+    QND7A (3, 4)
+    QND8 (8, 9)
+    QND9 (997, 998, 999)
+    QND11A (3, 4)
+    QND11 (6, 7).
+RECODE QND1 (LO THRU 15=1)
+            (16 THRU 25=2)
+            (26 THRU 35=3)
+            (36 THRU 45=4)
+            (46 THRU 55=5)
+            (56 THRU 65=6)
+            (66 THRU HI=7)
+       INTO AgeGroup.
+VAR LEVEL AgeGroup (NOMINAL).
+VARIABLE LABEL AgeGroup 'Age group'.
+VALUE LABELS
+    /AgeGroup
+     1 '15 or younger'
+     2 '16 to 25'
+     3 '26 to 35'
+     4 '36 to 45'
+     5 '46 to 55'
+     6 '56 to 65'
+     7 '66 or older'.
+SAVE OUTFILE='nhtsa.sav'.