X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Fstatistics.texi;fp=doc%2Fstatistics.texi;h=dfc3aad875bc3d32b5b12b81966700a2703c684c;hb=4e8bfea364b7a1d2d496e14dfefc9dfeefff8d11;hp=01976e27c950fa4ef21087dc40e0fadbd668a3ee;hpb=b81922824d04dfc85e777827c3f978450dc62594;p=pspp

diff --git a/doc/statistics.texi b/doc/statistics.texi
index 01976e27c9..dfc3aad875 100644
--- a/doc/statistics.texi
+++ b/doc/statistics.texi
@@ -20,6 +20,7 @@ far.
 * GRAPH::                       Plot data.
 * CORRELATIONS::                Correlation tables.
 * CROSSTABS::                   Crosstabulation tables.
+* CTABLES::                     Custom tables.
 * FACTOR::                      Factor analysis and Principal Components analysis.
 * GLM::                         Univariate Linear Models.
 * LOGISTIC REGRESSION::         Bivariate Logistic Regression.
@@ -29,7 +30,6 @@ far.
 * 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
@@ -897,6 +897,479 @@ person's occupation.
 @caption {The results of a test of independence between @exvar{sex} and @exvar{occupation}}
 @end float
 
+@node CTABLES
+@section CTABLES
+
+@vindex CTABLES
+@cindex custom tables
+@cindex tables, custom
+
+@code{CTABLES} has the following overall syntax.  At least one
+@code{TABLE} subcommand is required:
+
+@display
+@t{CTABLES}
+  @dots{}@i{global subcommands}@dots{}
+  [@t{/TABLE} @i{axis} [@t{BY} @i{axis} [@t{BY} @i{axis}]]
+   @dots{}@i{per-table subcommands}@dots{}]@dots{}
+@end display
+
+@noindent
+where each @i{axis} may be empty or take one of the following forms:
+
+@display
+@i{variable}
+@i{variable} @t{[}@{@t{C} @math{|} @t{S}@}@t{]}
+@i{axis} + @i{axis}
+@i{axis} > @i{axis}
+(@i{axis})
+@i{axis} @t{(}@i{summary} [@i{string}] [@i{format}]@t{)}
+@end display
+
+The following subcommands precede the first @code{TABLE} subcommand
+and apply to all of the output tables.  All of these subcommands are
+optional:
+
+@display
+@t{/FORMAT}
+    [@t{MINCOLWIDTH=}@{@t{DEFAULT} @math{|} @i{width}@}]
+    [@t{MAXCOLWIDTH=}@{@t{DEFAULT} @math{|} @i{width}@}]
+    [@t{UNITS=}@{@t{POINTS} @math{|} @t{INCHES} @math{|} @t{CM}@}]
+    [@t{EMPTY=}@{@t{ZERO} @math{|} @t{BLANK} @math{|} @i{string}@}]
+    [@t{MISSING=}@i{string}]
+@t{/VLABELS}
+    @t{VARIABLES=}@i{variables}
+    @t{DISPLAY}=@{@t{DEFAULT} @math{|} @t{NAME} @math{|} @t{LABEL} @math{|} @t{BOTH} @math{|} @t{NONE}@}
+@t{/MRSETS COUNTDUPLICATES=}@{@t{YES} @math{|} @t{NO}@}
+@t{/SMISSING} @{@t{VARIABLE} @math{|} @t{LISTWISE}@}
+@t{/PCOMPUTE} @t{&}@i{category}@t{=EXPR(}@i{expression}@t{)}
+@t{/PPROPERTIES} @t{&}@i{category}@dots{}
+    [@t{LABEL=}@i{string}]
+    [@t{FORMAT=}[@i{summary} @i{format}]@dots{}]
+    [@t{HIDESOURCECATS=}@{@t{NO} @math{|} @t{YES}@}
+@t{/WEIGHT VARIABLE=}@i{variable}
+@t{/HIDESMALLCOUNTS COUNT=@i{count}}
+@end display
+
+The following subcommands follow @code{TABLE} and apply only to the
+previous @code{TABLE}.  All of these subcommands are optional:
+
+@display
+@t{/SLABELS}
+    [@t{POSITION=}@{@t{COLUMN} @math{|} @t{ROW} @math{|} @t{LAYER}@}]
+    [@t{VISIBLE=}@{@t{YES} @math{|} @t{NO}@}]
+@t{/CLABELS} @{@t{AUTO} @math{|} @{@t{ROWLABELS}@math{|}@t{COLLABELS}@}@t{=}@{@t{OPPOSITE}@math{|}@t{LAYER}@}@}
+@t{/CRITERIA CILEVEL=}@i{percentage}
+@t{/CATEGORIES} @t{VARIABLES=}@i{variables}
+    @{@t{[}@i{value}@t{,} @i{value}@dots{}@t{]}
+   @math{|} [@t{ORDER=}@{@t{A} @math{|} @t{D}@}]
+     [@t{KEY=}@{@t{VALUE} @math{|} @t{LABEL} @math{|} @i{summary}@t{(}@i{variable}@t{)}@}]
+     [@t{MISSING=}@{@t{EXCLUDE} @math{|} @t{INCLUDE}@}]@}
+    [@t{TOTAL=}@{@t{NO} @math{|} @t{YES}@} [@t{LABEL=}@i{string}] [@t{POSITION=}@{@t{AFTER} @math{|} @t{BEFORE}@}]]
+    [@t{EMPTY=}@{@t{INCLUDE} @math{|} @t{EXCLUDE}@}]
+@t{/TITLES}
+    [@t{TITLE=}@i{string}@dots{}]
+    [@t{CAPTION=}@i{string}@dots{}]
+    [@t{CORNER=}@i{string}@dots{}]
+@t{/SIGTEST TYPE=CHISQUARE}
+    [@t{ALPHA=}@i{siglevel}]
+    [@t{INCLUDEMRSETS=}@{@t{YES} @math{|} @t{NO}@}]
+    [@t{CATEGORIES=}@{@t{ALLVISIBLE} @math{|} @t{SUBTOTALS}@}]
+@t{/COMPARETEST TYPE=}@{@t{PROP} @math{|} @t{MEAN}@}
+    [@t{ALPHA=}@i{value}[@t{,} @i{value}]]
+    [@t{ADJUST=}@{@t{BONFERRONI} @math{|} @t{BH} @math{|} @t{NONE}@}]
+    [@t{INCLUDEMRSETS=}@{@t{YES} @math{|} @t{NO}@}]
+    [@t{MEANSVARIANCE=}@{@t{ALLCATS} @math{|} @t{TESTEDCATS}@}]
+    [@t{CATEGORIES=}@{@t{ALLVISIBLE} @math{|} @t{SUBTOTALS}@}]
+    [@t{MERGE=}@{@t{NO} @math{|} @t{YES}@}]
+    [@t{STYLE=}@{@t{APA} @math{|} @t{SIMPLE}@}]
+    [@t{SHOWSIG=}@{@t{NO} @math{|} @t{YES}@}]
+@end display
+
+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.
+
+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::
+* CTABLES Data Summarization::
+@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.  At least one must specify an axis expression.
+
+@menu
+* CTABLES Categorical Variable Basics::
+* CTABLES Scalar Variable Basics::
+* CTABLES Overriding Measurement Level::
+* CTABLES Multiple Response Sets::
+@end menu
+
+@node CTABLES Categorical Variable Basics
+@subsubsection Categorical 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{>} ``nesting'' operator nests multiple variables on a single
+axis, e.g.:
+
+@example
+CTABLES /TABLE qn105ba BY AgeGroup > qns3a.
+@end example
+@psppoutput {ctables3}
+
+@noindent
+The @samp{+} ``stacking'' operator allows a single output table to
+include multiple data analyses.  With @samp{+}, @code{CTABLES} divides
+the output table into multiple @dfn{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
+When @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 CTABLES Scalar Variable Basics
+@subsubsection Scalar Variables
+
+For a categorical variable, @code{CTABLES} divides the table into a
+cell per category.  For a scalar variables, @code{CTABLES} instead
+calculates a summary measure, by default the mean, of the values that
+fall into a cell.  For example, if the only variable specified is a
+scalar variable, then the output is a single cell that holds the mean
+of all of the data:
+
+@example
+CTABLES /TABLE qnd1.
+@end example
+@psppoutput {ctables6}
+
+A scalar variable may nest with categorical variables.  The following
+example shows the mean age of survey respondents across gender and
+language groups:
+
+@example
+CTABLES /TABLE qns3a > qnd1 BY region.
+@end example
+@psppoutput {ctables7}
+
+The order of nesting of scalar and categorical variables affects table
+labeling, but it does not affect the data displayed in the table.  The
+following example shows how the output changes when the nesting order
+of the scalar and categorical variable are interchanged:
+
+@example
+CTABLES /TABLE qnd1 > qns3a BY region.
+@end example
+@psppoutput {ctables8}
+
+Only a single scalar variable may appear in each section; that is, a
+scalar variable may not nest inside a scalar variable directly or
+indirectly.  Scalar variables may only appear on one axis within
+@code{TABLE}.
+
+@node CTABLES Overriding Measurement Level
+@subsubsection Overriding Measurement Level
+
+By default, @code{CTABLES} uses a variable's measurement level to
+decide whether to treat it as categorical or scalar.  Variables
+assigned the nominal or ordinal measurement level are treated as
+categorical, and scalar variables are treated as scalar.
+
+Use the @code{VARIABLE LEVEL} command to change a variable's
+measurement level (@pxref{VARIABLE LEVEL}).  To treat a variable as
+categorical or scalar only for one use on @code{CTABLES}, add
+@samp{[C]} or @samp{[S]}, respectively, after the variable name.  The
+following example shows how to analyze the scalar variable @code{qn20}
+as categorical:
+
+@example
+CTABLES /TABLE qn20 [C] BY qns3a.
+@end example
+@psppoutput {ctables9}
+
+@node CTABLES Multiple Response Sets
+@subsubheading Multiple Response Sets
+
+The @code{CTABLES} command does not yet support multiple response
+sets.
+
+@node CTABLES Data Summarization
+@subsection Data Summarization
+
+The @code{CTABLES} command allows the user to control how the data are
+summarized with summary specifications, which are enclosed in square
+brackets following a variable name on the @code{TABLE} subcommand.
+When all the variables are categorical, summary specifications can be
+given for the innermost nested variables on any one axis.  When a
+scalar variable is present, only the scalar variable may have summary
+specifications.  The following example includes a summary
+specification for column and row percentages for categorical
+variables, and mean and median for a scalar variable:
+
+@example
+CTABLES
+    /TABLE=qnd1 [MEAN, MEDIAN] BY qns3a
+    /TABLE=AgeGroup [COLPCT, ROWPCT] BY qns3a.
+@end example
+@psppoutput {ctables10}
+
+A summary specification may override the default label and format by
+appending a string or format specification or both (in that order) to
+the summary function name.  For example:
+
+@example
+CTABLES /TABLE=AgeGroup [COLPCT 'Gender %' PCT5.0,
+                         ROWPCT 'Age Group %' PCT5.0]
+               BY qns3a.
+@end example
+@psppoutput {ctables11}
+
+Parentheses provide a shorthand to apply summary specifications to
+multiple variables.  For example, both of these commands:
+
+@example
+CTABLES /TABLE=AgeGroup[COLPCT] + qns1[COLPCT] BY qns3a.
+CTABLES /TABLE=(AgeGroup + qns1)[COLPCT] BY qns3a.
+@end example
+
+@noindent
+produce the same output shown below:
+
+@psppoutput {ctables12}
+
+The following section lists the available summary functions.
+
+@menu
+* CTABLES Summary Functions::
+@end menu
+
+@node CTABLES Summary Functions
+@subsubsection Summary Functions
+
+This section lists the summary functions that can be applied to cells
+in @code{CTABLES}.  Many of these functions have an @var{area} in
+their names.  The supported areas are:
+
+@itemize @bullet
+@item
+Areas that correspond to parts of @dfn{subtables}, whose contents are
+the cells that pair an innermost row variable and an innermost column
+variable:
+
+@table @code
+@item ROW
+A row within a subtable.
+
+@item COL
+A column within a subtable.
+
+@item SUBTABLE
+All the cells in a subtable
+@end table
+
+@item
+Areas that correspond to parts of @dfn{sections}, where stacked
+variables divide each section from another:
+
+@table @code
+@item TABLE
+An entire section.
+
+@item LAYER
+A layer within a section.
+
+@item LAYERROW
+A row in one layer within a section.
+
+@item LAYERCOL
+A column in one layer within a section.
+@end table
+@end itemize
+
+The following summary functions may be applied to any variable
+regardless of whether it is categorical or scalar.  The default label
+for each function is listed in parentheses:
+
+@table @asis
+@item @code{COUNT} (``Count'')
+The sum of weights in a cell.
+
+@item @code{@i{area}PCT} or @code{@i{area}PCT.COUNT} (``@i{Area} %'')
+A percentage within the specified @var{area}.
+
+@item @code{@i{area}PCT.VALIDN} (``@i{Area} Valid N %'')
+A percentage of valid values within the specified @var{area}.
+
+@item @code{@i{area}PCT.TOTALN} (``@i{Area} Total N %'')
+A percentage of total values within the specified @var{area}.
+@end table
+
+The following summary functions apply only to scale variables:
+
+@table @asis
+@item @code{MAXIMUM} (``Maximum'')
+The largest value.
+
+@item @code{MEAN} (``Mean'')
+The mean.
+
+@item @code{MEDIAN} (``Median'')
+The median value.
+
+@item @code{MINIMUM} (``Minimum'')
+The smallest value.
+
+@item @code{MISSING} (``Missing'')
+Sum of weights of user- and system-missing values.
+
+@item @code{MODE} (``Mode'')
+The highest-frequency value.  Ties are broken by taking the smallest mode.
+
+@item @code{@i{area}PCT.SUM} (``@i{Area} Sum %'')
+Percentage of the sum of the values across @var{area}.
+
+@item @code{PTILE} @i{n} (``Percentile @i{n}'')
+The @var{n}th percentile, where @math{0 @leq{} @var{n} @leq{} 100}.
+
+@item @code{RANGE} (``Range'')
+The maximum minus the minimum.
+
+@item @code{SEMEAN} (``Std Error of Mean'')
+The standard error of the mean.
+
+@item @code{STDDEV} (``Std Deviation'')
+The standard deviation.
+
+@item @code{SUM} (``Sum'')
+The sum.
+
+@item @code{TOTALN} (``Total N'')
+The sum of total count weights.
+
+@item @code{VALIDN} (``Valid N'')
+The sum of valid count weights.
+
+@item @code{VARIANCE} (``Variance'')
+The variance.
+@end table
+
+If the @code{WEIGHT} subcommand specified an adjustment weight
+variable, then the following summary functions use its value instead
+of the dictionary weight variable.  Otherwise, they are equivalent to
+the summary function without the @samp{E}-prefix:
+
+@itemize @bullet
+@item
+@code{ECOUNT} (``Adjusted Count'')
+
+@item
+@code{ETOTALN} (``Adjusted Total N'')
+
+@item
+@code{EVALIDN} (``Adjusted Valid N'')
+@end itemize
+
+The following summary functions with a @samp{U}-prefix are equivalent
+to the same ones without the prefix, except that they use unweighted
+counts:
+
+@itemize @bullet
+@item
+@code{UCOUNT} (``Unweighted Count'')
+
+@item
+@code{U@i{area}PCT} or @code{U@i{area}PCT.COUNT} (``Unweighted @i{Area} %'')
+
+@item
+@code{U@i{area}PCT.VALIDN} (``Unweighted @i{Area} Valid N %'')
+
+@item
+@code{U@i{area}PCT.TOTALN} (``Unweighted @i{Area} Total N %'')
+
+@item
+@code{UMEAN} (``Unweighted Mean'')
+
+@item
+@code{UMEDIAN} (``Unweighted Median'')
+
+@item
+@code{UMISSING} (``Unweighted Missing'')
+
+@item
+@code{UMODE} (``Unweight Mode'')
+
+@item
+@code{U@i{area}PCT.SUM} (``Unweighted @i{Area} Sum %'')
+
+@item
+@code{UPTILE} @i{n} (``Unweighted Percentile @i{n}'') 
+
+@item
+@code{USEMEAN} (``Unweighted Std Error of Mean'')
+
+@item
+@code{USTDDEV} (``Unweighted Std Deviation'')
+
+@item
+@code{USUM} (``Unweighted Sum'')
+
+@item
+@code{UTOTALN} (``Unweighted Total N'')
+
+@item
+@code{UVALIDN} (``Unweighted Valid N'')
+
+@item
+@code{UVARIANCE} (``Unweighted Variance'')
+@end itemize
 
 @node FACTOR
 @section FACTOR