File: pspp.xml

package info (click to toggle)
pspp 2.1.1-1
links: PTS, VCS
area: main
in suites: forky, sid
size: 69,768 kB
sloc: ansic: 276,489; xml: 18,462; sh: 6,445; python: 2,881; makefile: 125; perl: 64
file content (19576 lines) | stat: -rw-r--r-- 1,158,913 bytes
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY tex "TeX">
  <!ENTITY latex "LaTeX">
]>
<book id="pspp.xml" lang="en">
<title>PSPP Users&#8217; Guide</title>
<subtitle>GNU PSPP Statistical Analysis Software
Release 2.1.1</subtitle>
<titleabbrev>PSPP</titleabbrev>
<bookinfo><title>PSPP Users&#8217; Guide</title>
<subtitle>GNU PSPP Statistical Analysis Software
Release 2.1.1</subtitle>
<titleabbrev>PSPP</titleabbrev>
<legalnotice><para>This manual is for GNU PSPP version 2.1.1,
software for statistical analysis.
</para>
<para>Copyright &#169; 1997, 1998, 2004, 2005, 2009, 2012, 2013, 2014, 2016, 2019, 2020, 2023 Free Software Foundation, Inc.
</para>
<blockquote><para>Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled &quot;GNU
Free Documentation License&quot;.
</para></blockquote></legalnotice></bookinfo>
<chapter label="1" id="Introduction">
<title>Introduction</title>
<indexterm role="cp"><primary>introduction</primary></indexterm>

<indexterm role="cp"><primary>PSPP language</primary></indexterm>
<indexterm role="cp"><primary>language, PSPP</primary></indexterm>
<para>PSPP is a tool for statistical analysis of sampled data.
It reads the data, analyzes the data according to commands provided, and writes the results
to a listing file,  to the standard output or to a window of the graphical display.
</para>
<para>The language accepted by PSPP is similar to those accepted by SPSS
statistical products.
The details of PSPP&#8217;s language are given later in this manual.
</para>
<indexterm role="cp"><primary>PostScript</primary></indexterm>
<indexterm role="cp"><primary>PDF</primary></indexterm>
<indexterm role="cp"><primary>HTML</primary></indexterm>
<indexterm role="cp"><primary>DocBook</primary></indexterm>
<para>PSPP produces tables and charts as output, which it can produce in
several formats; currently, ASCII, PostScript, PDF, HTML, DocBook and &tex; are
supported.
</para>
<para>The current version of PSPP, 2.1.1, is incomplete in
terms of its statistical procedure support.  PSPP is a work in progress.
The authors hope to fully support all features in the products
that PSPP replaces, eventually.  The authors welcome questions,
comments, donations, and code submissions.  See <link linkend="Bugs">Submitting Bug
Reports</link>, for instructions on contacting the authors.
<!-- PSPP - a program for statistical analysis. -->
<!-- Copyright (C) 2017, 2020 Free Software Foundation, Inc. -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.3 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<!-- A copy of the license is included in the section entitled "GNU -->
<!-- Free Documentation License". -->
<!-- -->
</para></chapter>
<chapter label="2" id="License">
<title>Your rights and obligations</title>
<indexterm role="cp"><primary>license</primary></indexterm>
<indexterm role="cp"><primary>licence</primary></indexterm>
<indexterm role="cp"><primary>your rights and obligations</primary></indexterm>
<indexterm role="cp"><primary>rights, your</primary></indexterm>
<indexterm role="cp"><primary>copyright</primary></indexterm>
<indexterm role="cp"><primary>obligations, your</primary></indexterm>

<para>PSPP is not in the public domain. It is copyrighted and there are
restrictions on its distribution, but these restrictions are designed
to permit everything that a good cooperating citizen would want to do.
What is not allowed is to try to prevent others from further sharing
any version of this program that they might get from you.
</para>
<para>Specifically, we want to make sure that you have the right to give
away copies of PSPP, that you receive source code or else can get it
if you want it, that you can change these programs or use pieces of
them in new free programs, and that you know you can do these things.
</para>
<para>To make sure that everyone has such rights, we have to forbid you to
deprive anyone else of these rights.  For example, if you distribute
copies of PSPP, you must give the recipients all the rights that you
have.  You must make sure that they, too, receive or can get the
source code.  And you must tell them their rights.
</para>
<para>Also, for our own protection, we must make certain that everyone finds
out that there is no warranty for PSPP.  If these programs are
modified by someone else and passed on, we want their recipients to
know that what they have is not what we distributed, so that any
problems introduced by others will not reflect on our reputation.
</para>
<para>Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary.  To prevent this, we have made it clear that any
patent must be licensed for everyone&#8217;s free use or not licensed at all.
</para>
<para>The precise conditions of the license for PSPP are found in the
GNU General Public License.  You should have received a copy of
the GNU General Public License along  with this program; if not, write
to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
Floor, Boston, MA 02110-1301 USA. This manual specifically
is covered by the GNU Free Documentation License (see <link linkend="GNU-Free-Documentation-License">GNU Free
Documentation License</link>).
</para>
<!-- PSPP - a program for statistical analysis. -->
<!-- Copyright (C) 2017, 2020 Free Software Foundation, Inc. -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.3 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<!-- A copy of the license is included in the section entitled "GNU -->
<!-- Free Documentation License". -->
<!-- -->
</chapter>
<chapter label="3" id="Invoking-PSPP">
<title>Invoking <command>pspp</command></title>
<indexterm role="cp"><primary>invocation</primary></indexterm>
<indexterm role="cp"><primary>PSPP, invoking</primary></indexterm>

<para>PSPP has two separate user interfaces.  This chapter describes
<command>pspp</command>, PSPP&#8217;s command-line driven text-based user interface.
The following chapter briefly describes PSPPIRE, the graphical user
interface to PSPP.
</para>
<para>The sections below describe the <command>pspp</command> program&#8217;s command-line
interface.
</para>

<sect1 label="3.1" id="Main-Options">
<title>Main Options</title>

<para>Here is a summary of all the options, grouped by type, followed by
explanations in the same order.
</para>
<para>In the table, arguments to long options also apply to any
corresponding short options.
</para>
<variablelist><varlistentry><term><emphasis>Non-option arguments</emphasis>
</term><listitem><screen><replaceable>syntax-file</replaceable>
</screen>
</listitem></varlistentry><varlistentry><term><emphasis>Output options</emphasis>
</term><listitem><screen>-o, --output=<replaceable>output-file</replaceable>
-O <replaceable>option</replaceable>=<replaceable>value</replaceable>
-O format=<replaceable>format</replaceable>
-O device={terminal|listing}
--no-output
--table-look=<replaceable>file</replaceable>
-e, --error-file=<replaceable>error-file</replaceable>
</screen>
</listitem></varlistentry><varlistentry><term><emphasis>Language options</emphasis>
</term><listitem><screen>-I, --include=<replaceable>dir</replaceable>
-I-, --no-include
-b, --batch
-i, --interactive
-r, --no-statrc
-a, --algorithm={compatible|enhanced}
-x, --syntax={compatible|enhanced}
--syntax-encoding=<replaceable>encoding</replaceable>
</screen>
</listitem></varlistentry><varlistentry><term><emphasis>Informational options</emphasis>
</term><listitem><screen>-h, --help
-V, --version
</screen>
</listitem></varlistentry><varlistentry><term><emphasis>Other options</emphasis>
</term><listitem><screen>-s, --safer
--testing-mode
</screen></listitem></varlistentry></variablelist>
<variablelist><varlistentry><term><replaceable>syntax-file</replaceable>
</term><listitem><para>Read and execute the named syntax file.  If no syntax files are
specified, PSPP prompts for commands.  If any syntax files are
specified, PSPP by default exits after it runs them, but you may make
it prompt for commands by specifying &#8216;<literal>-</literal>&#8217; as an additional syntax
file.
</para>
</listitem></varlistentry><varlistentry><term><option>-o <replaceable>output-file</replaceable></option>
</term><listitem><para>Write output to <replaceable>output-file</replaceable>.  PSPP has several different output
drivers that support output in various formats (use <option>--help</option> to
list the available formats).  Specify this option more than once to
produce multiple output files, presumably in different formats.
</para>
<para>Use &#8216;<literal>-</literal>&#8217; as <replaceable>output-file</replaceable> to write output to standard output.
</para>
<para>If no <option>-o</option> option is used, then PSPP writes text and CSV
output to standard output and other kinds of output to whose name is
based on the format, <emphasis>e.g.</emphasis> <filename>pspp.pdf</filename> for PDF output.
</para>
</listitem></varlistentry><varlistentry><term><option>-O <replaceable>option</replaceable>=<replaceable>value</replaceable></option>
</term><listitem><para>Sets an option for the output file configured by a preceding
<option>-o</option>.  Most options are specific to particular output formats.
A few options that apply generically are listed below.
</para>
</listitem></varlistentry><varlistentry><term><option>-O format=<replaceable>format</replaceable></option>
</term><listitem><para>PSPP uses the extension of the file name given on <option>-o</option> to
select an output format.  Use this option to override this choice by
specifying an alternate format, <emphasis>e.g.</emphasis> <option>-o pspp.out -O format=html</option> to
write HTML to a file named <filename>pspp.out</filename>.  Use <option>--help</option> to
list the available formats.
</para>
</listitem></varlistentry><varlistentry><term><option>-O device={terminal|listing}</option>
</term><listitem><para>Sets whether PSPP considers the output device configured by the
preceding <option>-o</option> to be a terminal or a listing device.  This
affects what output will be sent to the device, as configured by the
SET command&#8217;s output routing subcommands (see <link linkend="SET">SET</link>).  By default,
output written to standard output is considered a terminal device and
other output is considered a listing device.
</para>
</listitem></varlistentry><varlistentry><term><option>--no-output</option>
</term><listitem><para>Disables output entirely, if neither <option>-o</option> nor <option>-O</option> is
also used.  If one of those options is used, <option>--no-output</option> has
no effect.
</para>
</listitem></varlistentry><varlistentry><term><option>--table-look=<replaceable>file</replaceable></option>
</term><listitem><para>Reads a table style from <replaceable>file</replaceable> and applies it to all PSPP
table output.  The file should be a TableLook <filename>.stt</filename> or
<filename>.tlo</filename> file.  PSPP searches for <replaceable>file</replaceable> in the current
directory, then in <filename>.pspp/looks</filename> in the user&#8217;s home directory,
then in a <filename>looks</filename> subdirectory inside PSPP&#8217;s data directory
(usually <filename>/usr/local/share/pspp</filename>).  If PSPP cannot find
<replaceable>file</replaceable> under the given name, it also tries adding a <filename>.stt</filename>
extension.
</para>
<para>When this option is not specified, PSPP looks for
<filename>default.stt</filename> using the algorithm above, and otherwise it falls
back to a default built-in style.
</para>
<para>Using <literal>SET TLOOK</literal> in PSPP syntax overrides the style set on
the command line (see <link linkend="SET">SET</link>).
</para>
</listitem></varlistentry><varlistentry><term><option>-e <replaceable>error-file</replaceable></option>
</term><term><option>--error-file=<replaceable>error-file</replaceable></option>
</term><listitem><para>Configures a file to receive PSPP error, warning, and note messages in
plain text format.  Use &#8216;<literal>-</literal>&#8217; as <replaceable>error-file</replaceable> to write messages
to standard output.  The default error file is standard output in the
absence of these options, but this is suppressed if an output device
writes to standard output (or another terminal), to avoid printing
every message twice.  Use &#8216;<literal>none</literal>&#8217; as <replaceable>error-file</replaceable> to
explicitly suppress the default.
</para>
</listitem></varlistentry><varlistentry><term><option>-I <replaceable>dir</replaceable></option>
</term><term><option>--include=<replaceable>dir</replaceable></option>
</term><listitem><para>Appends <replaceable>dir</replaceable> to the set of directories searched by the <literal>INCLUDE</literal>
(see <link linkend="INCLUDE">INCLUDE</link>) and <literal>INSERT</literal> (see <link linkend="INSERT">INSERT</link>) commands.
</para>
</listitem></varlistentry><varlistentry><term><option>-I-</option>
</term><term><option>--no-include</option>
</term><listitem><para>Clears all directories from the include path, including directories
inserted in the include path by default.  The default include path is
<filename>.</filename> (the current directory), followed by <filename>.pspp</filename> in the
user&#8217;s home directory, followed by PSPP&#8217;s system configuration
directory (usually <filename>/etc/pspp</filename> or <filename>/usr/local/etc/pspp</filename>).
</para>
</listitem></varlistentry><varlistentry><term><option>-b</option>
</term></varlistentry><varlistentry><term><option>--batch</option>
</term></varlistentry><varlistentry><term><option>-i</option>
</term><term><option>--interactive</option>
</term><listitem><para>These options forces syntax files to be interpreted in batch mode or
interactive mode, respectively, rather than the default &#8220;auto&#8221; mode.
See <link linkend="Syntax-Variants">Syntax Variants</link>, for a description of the differences.
</para>
</listitem></varlistentry><varlistentry><term><option>-r</option>
</term><term><option>--no-statrc</option>
</term><listitem><para>By default, at startup PSPP searches for a file named <filename>rc</filename> in
the include path (described above) and, if it finds one, runs the
commands in it.  This option disables this behavior.
</para>
</listitem></varlistentry><varlistentry><term><option>-a {enhanced|compatible}</option>
</term><term><option>--algorithm={enhanced|compatible}</option>
</term><listitem><para>With <literal>enhanced</literal>, the default, PSPP uses the best implemented
algorithms for statistical procedures.  With <literal>compatible</literal>,
however, PSPP will in some cases use inferior algorithms to produce
the same results as the proprietary program SPSS.
</para>
<para>Some commands have subcommands that override this setting on a per
command basis.
</para>
</listitem></varlistentry><varlistentry><term><option>-x {enhanced|compatible}</option>
</term><term><option>--syntax={enhanced|compatible}</option>
</term><listitem><para>With <literal>enhanced</literal>, the default, PSPP accepts its own extensions
beyond those compatible with the proprietary program SPSS.  With
<literal>compatible</literal>, PSPP rejects syntax that uses these extensions.
</para>
</listitem></varlistentry><varlistentry><term><option>--syntax-encoding=<replaceable>encoding</replaceable></option>
</term><listitem><para>Specifies <replaceable>encoding</replaceable> as the encoding for syntax files named on the
command line.  The <replaceable>encoding</replaceable> also becomes the default encoding
for other syntax files read during the PSPP session by the
<literal>INCLUDE</literal> and <literal>INSERT</literal> commands.  See <link linkend="INSERT">INSERT</link>, for the
accepted forms of <replaceable>encoding</replaceable>.
</para>
</listitem></varlistentry><varlistentry><term><option>--help</option>
</term><listitem><para>Prints a message describing PSPP command-line syntax and the available
device formats, then exits.
</para>
</listitem></varlistentry><varlistentry><term><option>-V</option>
</term><term><option>--version</option>
</term><listitem><para>Prints a brief message listing PSPP&#8217;s version, warranties you don&#8217;t
have, copying conditions and copyright, and e-mail address for bug
reports, then exits.
</para>
</listitem></varlistentry><varlistentry><term><option>-s</option>
</term><term><option>--safer</option>
</term><listitem><para>Disables certain unsafe operations.  This includes the <literal>ERASE</literal> and
<literal>HOST</literal> commands, as well as use of pipes as input and output files.
</para>
</listitem></varlistentry><varlistentry><term><option>--testing-mode</option>
</term><listitem><para>Invoke heuristics to assist with testing PSPP.  For use
by <command>make check</command> and similar scripts.
</para></listitem></varlistentry></variablelist>
</sect1>
<sect1 label="3.2" id="PDF-PostScript-SVG-and-PNG-Output-Options">
<title>PDF, PostScript, SVG, and PNG Output Options</title>
<indexterm role="cp"><primary>PDF</primary></indexterm>
<indexterm role="cp"><primary>Postscript</primary></indexterm>
<indexterm role="cp"><primary>SVG</primary></indexterm>
<indexterm role="cp"><primary>PNG</primary></indexterm>

<para>To produce output in PDF, PostScript, SVG, or PNG format, specify
<option>-o <replaceable>file</replaceable></option> on the PSPP command line, optionally
followed by any of the options shown in the table below to customize
the output format.
</para>
<para>PDF, PostScript, and SVG use real units: each dimension among the
options listed below may have a suffix &#8216;<literal>mm</literal>&#8217; for millimeters,
&#8216;<literal>in</literal>&#8217; for inches, or &#8216;<literal>pt</literal>&#8217; for points.  Lacking a suffix,
numbers below 50 are assumed to be in inches and those above 50 are
assumed to be in millimeters.
</para>
<para>PNG files are pixel-based, so dimensions in PNG output must ultimately
be measured in pixels.  For output to these files, PSPP translates the
specified dimensions to pixels at 72 pixels per inch.  For PNG output
only, fonts are by default rendered larger than this, at 96 pixels per
inch.
</para>
<para>An SVG or PNG file can only hold a single page.  When PSPP outputs
more than one page to SVG or PNG, it creates multiple files.  It
outputs the second page to a file named with a <literal>-2</literal> suffix, the
third with a <literal>-3</literal> suffix, and so on.
</para>
<variablelist><varlistentry><term><option>-O format={pdf|ps|svg|png}</option>
</term><listitem><para>Specify the output format.  This is only necessary if the file name
given on <option>-o</option> does not end in <filename>.pdf</filename>, <filename>.ps</filename>,
<filename>.svg</filename>, or <filename>.png</filename>.
</para>
</listitem></varlistentry><varlistentry><term><option>-O paper-size=<replaceable>paper-size</replaceable></option>
</term><listitem><para>Paper size, as a name (<emphasis>e.g.</emphasis> <literal>a4</literal>, <literal>letter</literal>) or
measurements (<emphasis>e.g.</emphasis> <literal>210x297</literal>, <literal>8.5x11in</literal>).
</para>
<para>The default paper size is taken from the <envar>PAPERSIZE</envar> environment
variable or the file indicated by the <envar>PAPERCONF</envar> environment
variable, if either variable is set.  If not, and your system supports
the <literal>LC_PAPER</literal> locale category, then the default paper size is
taken from the locale.  Otherwise, if <filename>/etc/papersize</filename> exists,
the default paper size is read from it.  As a last resort, A4 paper is
assumed.
</para>
</listitem></varlistentry><varlistentry><term><option>-O foreground-color=<replaceable>color</replaceable></option>
</term><listitem><para>Sets <replaceable>color</replaceable> as the default color for lines and text.  Use a CSS
color format (e.g. <literal>#<replaceable>rr</replaceable><replaceable>gg</replaceable><replaceable>bb</replaceable></literal>) or name (e.g.
<literal>black</literal>) as <replaceable>color</replaceable>.
</para>
</listitem></varlistentry><varlistentry><term><option>-O orientation=<replaceable>orientation</replaceable></option>
</term><listitem><para>Either <literal>portrait</literal> or <literal>landscape</literal>.  Default: <literal>portrait</literal>.
</para>
</listitem></varlistentry><varlistentry><term><option>-O left-margin=<replaceable>dimension</replaceable></option>
</term><term><option>-O right-margin=<replaceable>dimension</replaceable></option>
</term><term><option>-O top-margin=<replaceable>dimension</replaceable></option>
</term><term><option>-O bottom-margin=<replaceable>dimension</replaceable></option>
</term><listitem><para>Sets the margins around the page.  See
below for the allowed forms of <replaceable>dimension</replaceable>. Default: <literal>0.5in</literal>.
</para>
</listitem></varlistentry><varlistentry><term><option>-O object-spacing=<replaceable>dimension</replaceable></option>
</term><listitem><para>Sets the amount of vertical space between objects (such as headings or
tables).
</para>
</listitem></varlistentry><varlistentry><term><option>-O prop-font=<replaceable>font-name</replaceable></option>
</term><listitem><para>Sets the default font used for ordinary text.  Most systems support
CSS-like font names such as &#8220;Sans Serif&#8221;, but a wide range of
system-specific fonts are likely to be supported as well.
</para>
<para>Default: proportional font <literal>Sans Serif</literal>.
</para>
</listitem></varlistentry><varlistentry><term><option>-O font-size=<replaceable>font-size</replaceable></option>
</term><listitem><para>Sets the size of the default fonts, in thousandths of a point.  Default:
10000 (10 point).
</para>
</listitem></varlistentry><varlistentry><term><option>-O trim=true</option>
</term><listitem><para>This option makes PSPP trim empty space around each page of output,
before adding the margins.  This can make the output easier to include
in other documents.
</para>
</listitem></varlistentry><varlistentry><term><option>-O outline=<replaceable>boolean</replaceable></option>
</term><listitem><para>For PDF output only, this option controls whether PSPP includes an
outline in the output file.  PDF viewers usually display the outline
as a side bar that allows for easy navigation of the file.
The default is true unless <option>-O trim=true</option> is also specified.
(The Cairo graphics library that PSPP uses to produce PDF output has a
bug that can cause a crash when outlines and trimming are used
together.)
</para>
</listitem></varlistentry><varlistentry><term><option>-O font-resolution=<replaceable>dpi</replaceable></option>
</term><listitem><para>Sets the resolution for font rendering, in dots per inch.  For PDF,
PostScript, and SVG output, the default is 72 dpi, so that a 10-point
font is rendered with a height of 10 points.  For PNG output, the
default is 96 dpi, so that a 10-point font is rendered with a height
of <inlineequation><mathphrase>10 / 72 * 96 = 13.3</mathphrase></inlineequation> pixels.  Use a larger <replaceable>dpi</replaceable> to
enlarge text output, or a smaller <replaceable>dpi</replaceable> to shrink it.
</para></listitem></varlistentry></variablelist>
</sect1>
<sect1 label="3.3" id="Plain-Text-Output-Options">
<title>Plain Text Output Options</title>

<para>PSPP can produce plain text output, drawing boxes using ASCII or
Unicode line drawing characters.  To produce plain text output,
specify <option>-o <replaceable>file</replaceable></option> on the PSPP command line, optionally
followed by options from the table below to customize the output
format.
</para>
<para>Plain text output is encoded in UTF-8.
</para>
<variablelist><varlistentry><term><option>-O format=txt</option>
</term><listitem><para>Specify the output format.  This is only necessary if the file name
given on <option>-o</option> does not end in <filename>.txt</filename> or <filename>.list</filename>.
</para>
</listitem></varlistentry><varlistentry><term><option>-O charts={<replaceable>template</replaceable>.png|none}</option>
</term><listitem><para>Name for chart files included in output.  The value should be a file
name that includes a single &#8216;<literal>#</literal>&#8217; and ends in <filename>png</filename>.  When a
chart is output, the &#8216;<literal>#</literal>&#8217; is replaced by the chart number.  The
default is the file name specified on <option>-o</option> with the extension
stripped off and replaced by <filename>-#.png</filename>.
</para>
<para>Specify <literal>none</literal> to disable chart output.
</para>
</listitem></varlistentry><varlistentry><term><option>-O foreground-color=<replaceable>color</replaceable></option>
</term><term><option>-O background-color=<replaceable>color</replaceable></option>
</term><listitem><para>Sets <replaceable>color</replaceable> as the color to be used for the background or foreground to
be used for charts.
Color should be given in the format <literal>#<replaceable>RRRR</replaceable><replaceable>GGGG</replaceable><replaceable>BBBB</replaceable></literal>,
where <replaceable>RRRR</replaceable>, <replaceable>GGGG</replaceable> and <replaceable>BBBB</replaceable> are 4 character hexadecimal
representations of the red, green and blue components respectively.
If charts are disabled, this option has no effect.
</para>
</listitem></varlistentry><varlistentry><term><option>-O width=<replaceable>columns</replaceable></option>
</term><listitem><para>Width of a page, in columns.  If unspecified or given as <literal>auto</literal>,
the default is the width of the terminal, for interactive output, or
the WIDTH setting (see <link linkend="SET">SET</link>), for output to a file.
</para>
</listitem></varlistentry><varlistentry><term><option>-O box={ascii|unicode}</option>
</term><listitem><para>Sets the characters used for lines in tables.
If set to
<literal>ascii</literal>, output uses use the characters &#8216;<literal>-</literal>&#8217;, &#8216;<literal>|</literal>&#8217;, and &#8216;<literal>+</literal>&#8217; for single-width
lines and &#8216;<literal>=</literal>&#8217; and &#8216;<literal>#</literal>&#8217; for double-width lines.
If set to <literal>unicode</literal> then, output uses Unicode box drawing characters.
The default is <literal>unicode</literal> if the locale&#8217;s character encoding is &quot;UTF-8&quot;
or <literal>ascii</literal> otherwise.
</para>
</listitem></varlistentry><varlistentry><term><option>-O emphasis={none|bold|underline}</option>
</term><listitem><para>How to emphasize text.  Bold and underline emphasis are achieved with
overstriking, which may not be supported by all the software to which
you might pass the output.  Default: <literal>none</literal>.
</para></listitem></varlistentry></variablelist>
</sect1>
<sect1 label="3.4" id="SPV-Output-Options">
<title>SPV Output Options</title>

<para>SPSS 16 and later write <filename>.spv</filename> files to represent the contents of
its output editor.  To produce output in <filename>.spv</filename> format, specify
<option>-o <replaceable>file</replaceable></option> on the PSPP command line, optionally
followed by any of the options shown in the table below to customize
the output format.
</para>
<variablelist><varlistentry><term><option>-O format=spv</option>
</term><listitem><para>Specify the output format.  This is only necessary if the file name
given on <option>-o</option> does not end in <filename>.spv</filename>.
</para>
</listitem></varlistentry><varlistentry><term><option>-O paper-size=<replaceable>paper-size</replaceable></option>
</term><term><option>-O left-margin=<replaceable>dimension</replaceable></option>
</term><term><option>-O right-margin=<replaceable>dimension</replaceable></option>
</term><term><option>-O top-margin=<replaceable>dimension</replaceable></option>
</term><term><option>-O bottom-margin=<replaceable>dimension</replaceable></option>
</term><term><option>-O object-spacing=<replaceable>dimension</replaceable></option>
</term><listitem><para>These have the same syntax and meaning as for PDF output.  See <link linkend="PDF-PostScript-SVG-and-PNG-Output-Options">PDF
PostScript SVG and PNG Output Options</link>, for details.
</para></listitem></varlistentry></variablelist>
</sect1>
<sect1 label="3.5" id="TeX-Output-Options">
<title>TeX Output Options</title>
<indexterm role="cp"><primary>&tex;</primary></indexterm>
<indexterm role="cp"><primary>tex</primary></indexterm>

<para>If you want to publish statistical results in professional or academic
journals, you will probably want to provide results in &tex; format.
To do this, specify <option>-o <replaceable>file</replaceable></option> on the PSPP command line where
<replaceable>file</replaceable> is a file name ending in <filename>.tex</filename>, or you can specify
<option>-O format=tex</option>.
</para>
<para>The resulting file can be directly processed using &tex; or you can manually
edit the file to add commentary text.
Alternatively, you can cut and paste desired sections to another &tex; file.
</para>
</sect1>
<sect1 label="3.6" id="HTML-Output-Options">
<title>HTML Output Options</title>
<indexterm role="cp"><primary>HTML</primary></indexterm>
<para>To produce output in HTML format, specify <option>-o <replaceable>file</replaceable></option> on
the PSPP command line, optionally followed by any of the options shown
in the table below to customize the output format.
</para>
<variablelist><varlistentry><term><option>-O format=html</option>
</term><listitem><para>Specify the output format.  This is only necessary if the file name
given on <option>-o</option> does not end in <filename>.html</filename>.
</para>
</listitem></varlistentry><varlistentry><term><option>-O charts={<replaceable>template</replaceable>.png|none}</option>
</term><listitem><para>Sets the name used for chart files.  See <link linkend="Plain-Text-Output-Options">Plain Text Output Options</link>,
for details.
</para>
</listitem></varlistentry><varlistentry><term><option>-O borders=<replaceable>boolean</replaceable></option>
</term><listitem><para>Decorate the tables with borders.  If set to false, the tables produced
will have no borders.  The default value is true.
</para>
</listitem></varlistentry><varlistentry><term><option>-O bare=<replaceable>boolean</replaceable></option>
</term><listitem><para>The HTML output driver ordinarily outputs a complete HTML document.
If set to true, the driver instead outputs only what would normally be
the contents of the <literal>body</literal> element.  The default value is false.
</para>
</listitem></varlistentry><varlistentry><term><option>-O css=<replaceable>boolean</replaceable></option>
</term><listitem><para>Use cascading style sheets.  Cascading style sheets give an improved appearance
and can be used to produce pages which fit a certain web site&#8217;s style.
The default value is true.
</para>
</listitem></varlistentry></variablelist>
</sect1>
<sect1 label="3.7" id="OpenDocument-Output-Options">
<title>OpenDocument Output Options</title>

<para>To produce output as an OpenDocument text (ODT) document, specify
<option>-o <replaceable>file</replaceable></option> on the PSPP command line.  If <replaceable>file</replaceable> does
not end in <filename>.odt</filename>, you must also specify <option>-O format=odt</option>.
</para>
<para>ODT support is only available if your installation of PSPP was
compiled with the libxml2 library.
</para>
<para>The OpenDocument output format does not have any configurable options.
</para>
</sect1>
<sect1 label="3.8" id="Comma_002dSeparated-Value-Output-Options">
<title>Comma-Separated Value Output Options</title>

<para>To produce output in comma-separated value (CSV) format, specify
<option>-o <replaceable>file</replaceable></option> on the PSPP command line, optionally followed
by any of the options shown in the table below to customize the output
format.
</para>
<variablelist><varlistentry><term><option>-O format=csv</option>
</term><listitem><para>Specify the output format.  This is only necessary if the file name
given on <option>-o</option> does not end in <filename>.csv</filename>.
</para>
</listitem></varlistentry><varlistentry><term><option>-O separator=<replaceable>field-separator</replaceable></option>
</term><listitem><para>Sets the character used to separate fields.  Default: a comma
(&#8216;<literal>,</literal>&#8217;).
</para>
</listitem></varlistentry><varlistentry><term><option>-O quote=<replaceable>qualifier</replaceable></option>
</term><listitem><para>Sets <replaceable>qualifier</replaceable> as the character used to quote fields that
contain white space, the separator (or any of the characters in the
separator, if it contains more than one character), or the quote
character itself.  If <replaceable>qualifier</replaceable> is longer than one character,
only the first character is used; if <replaceable>qualifier</replaceable> is the empty
string, then fields are never quoted.
</para>
</listitem></varlistentry><varlistentry><term><option>-O titles=<replaceable>boolean</replaceable></option>
</term><listitem><para>Whether table titles (brief descriptions) should be printed.  Default:
<literal>on</literal>.
</para>
</listitem></varlistentry><varlistentry><term><option>-O captions=<replaceable>boolean</replaceable></option>
</term><listitem><para>Whether table captions (more extensive descriptions) should be
printed.  Default: on.
</para></listitem></varlistentry></variablelist>
<para>The CSV format used is an extension to that specified in RFC 4180:
</para>
<variablelist><varlistentry><term>Tables
</term><listitem><para>Each table row is output on a separate line, and each column is output
as a field.  The contents of a cell that spans multiple rows or
columns is output only for the top-left row and column; the rest are
output as empty fields.
</para>
</listitem></varlistentry><varlistentry><term>Titles
</term><listitem><para>When a table has a title and titles are enabled, the title is output
just above the table as a single field prefixed by &#8216;<literal>Table:</literal>&#8217;.
</para>
</listitem></varlistentry><varlistentry><term>Captions
</term><listitem><para>When a table has a caption and captions are enabled, the caption is
output just below the table as a single field prefixed by
&#8216;<literal>Caption:</literal>&#8217;.
</para>
</listitem></varlistentry><varlistentry><term>Footnotes
</term><listitem><para>Within a table, footnote markers are output as bracketed letters
following the cell&#8217;s contents, <emphasis>e.g.</emphasis>&#160;&#8216;<literal>[a]</literal>&#8217;, &#8216;<literal>[b]</literal>&#8217;,
...  The footnotes themselves are output following the body of
the table, as a separate two-column table introduced with a line that
says &#8216;<literal>Footnotes:</literal>&#8217;.  Each row in the table represent one footnote:
the first column is the marker, the second column is the text.
</para>
</listitem></varlistentry><varlistentry><term>Text
</term><listitem><para>Text in output is printed as a field on a line by itself.  The TITLE
and SUBTITLE produce similar output, prefixed by &#8216;<literal>Title:</literal>&#8217; or
&#8216;<literal>Subtitle:</literal>&#8217;, respectively.
</para>
</listitem></varlistentry><varlistentry><term>Messages
</term><listitem><para>Errors, warnings, and notes are printed the same way as text.
</para>
</listitem></varlistentry><varlistentry><term>Charts
</term><listitem><para>Charts are not included in CSV output.
</para></listitem></varlistentry></variablelist>
<para>Successive output items are separated by a blank line.
</para>
</sect1>
</chapter>
<chapter label="4" id="Invoking-PSPPIRE">
<title>Invoking <command>psppire</command></title>
<sect1 label="4.1">
<title>The graphic user interface</title>
<indexterm role="cp"><primary>Graphic user interface</primary></indexterm>
<indexterm role="cp"><primary>PSPPIRE</primary></indexterm>

<para>The PSPPIRE graphic user interface for PSPP can perform all
functionality of the command line interface.  In addition it gives an
instantaneous view of the data, variables and statistical output.
</para>
<para>The graphic user interface can be started by typing <command>psppire</command> at a
command prompt.
Alternatively many systems have a system of interactive menus or buttons
from which <command>psppire</command> can be started by a series of mouse clicks.
</para>
<para>Once the principles of the PSPP system are understood,
the graphic user interface is designed to be largely intuitive, and
for this reason is covered only very briefly by this manual.
<!-- PSPP - a program for statistical analysis. -->
<!-- Copyright (C) 2017, 2020 Free Software Foundation, Inc. -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.3 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<!-- A copy of the license is included in the section entitled "GNU -->
<!-- Free Documentation License". -->
<!-- -->
</para>

</sect1>
</chapter>
<chapter label="5" id="Using-PSPP">
<title>Using PSPP</title>

<para>PSPP is a tool for the statistical analysis of sampled data.
You can use it to discover patterns in the data,
to explain differences in one subset of data in terms of another subset
and to find out
whether certain beliefs about the data are justified.
This chapter does not attempt to introduce the theory behind the
statistical analysis,
but it shows how such analysis can be performed using PSPP.
</para>
<para>For the purposes of this tutorial, it is assumed that you are using PSPP in its
interactive mode from the command line.
However, the example commands can also be typed into a file and executed in
a post-hoc mode by typing &#8216;<literal>pspp <replaceable>file-name</replaceable></literal>&#8217; at a shell prompt,
where <replaceable>file-name</replaceable> is the name of the file containing the commands.
Alternatively, from the graphical interface, you can select
File &#8594; New &#8594; Syntax to open a new syntax window
and use the Run menu when a syntax fragment is ready to be
executed.
Whichever method you choose, the syntax is identical.
</para>
<para>When using the interactive method, PSPP tells you that it&#8217;s waiting for your
data with a string like PSPP&gt; or data&gt;.
In the examples of this chapter, whenever you see text like this, it
indicates the prompt displayed by PSPP, <emphasis>not</emphasis> something that you
should type.
</para>
<para>Throughout this chapter reference is made to a number of sample data files.
So that you can try the examples for yourself,
you should have received these files along with your copy of PSPP.<!-- -->
<footnote><para>These files contain purely fictitious data.  They should not be used
for research purposes.</para></footnote>
</para><blockquote><para><emphasis role="bold">Please note:</emphasis> Normally these files are installed in the directory
<filename>//share/pspp/examples</filename>.
If however your system administrator or operating system vendor has
chosen to install them in a different location, you will have to adjust
the examples accordingly.
</para></blockquote>


<sect1 label="5.1" id="Preparation-of-Data-Files">
<title>Preparation of Data Files</title>


<para>Before analysis can commence,  the data must be loaded into PSPP and
arranged such that both PSPP and humans can understand what
the data represents.
There are two aspects of data:
</para>
<itemizedlist><listitem><para>The variables &#8212; these are the parameters of a quantity
 which has been measured or estimated in some way.
 For example height, weight and geographic location are all variables.
</para></listitem><listitem><para>The observations (also called &#8216;cases&#8217;) of the variables &#8212;
 each observation represents an instance when the variables were measured
 or observed.
</para></listitem></itemizedlist>
<para>For example, a data set which has the variables <emphasis role="bold">height</emphasis>, <emphasis role="bold">weight</emphasis>, and
<emphasis role="bold">name</emphasis>, might have the observations:
</para><screen>1881 89.2 Ahmed
1192 107.01 Frank
1230 67 Julie
</screen><para>The following sections explain how to define a dataset.
</para>

<sect2 label="5.1.1" id="Defining-Variables">
<title>Defining Variables</title>
<indexterm role="cp"><primary>variables</primary></indexterm>

<para>Variables come in two basic types, <emphasis>viz</emphasis>: <firstterm>numeric</firstterm> and <firstterm>string</firstterm>.
Variables such as age, height and satisfaction are numeric,
whereas name is a string variable.
String variables are best reserved for commentary data to assist the
human observer.
However they can also be used for nominal or categorical data.
</para>
<para>The following example defines two variables <emphasis role="bold">forename</emphasis> and <emphasis role="bold">height</emphasis>,
and reads data into them by manual input:
</para>
<screen>PSPP&gt; data list list /forename (A12) height.
PSPP&gt; begin data.
data&gt; Ahmed 188
data&gt; Bertram 167
data&gt; Catherine 134.231
data&gt; David 109.1
data&gt; end data
PSPP&gt;
</screen>
<para>There are several things to note about this example.
</para>
<itemizedlist><listitem><para>The words &#8216;<literal>data list list</literal>&#8217; are an example of the <literal>DATA LIST</literal>
command. See <link linkend="DATA-LIST">DATA LIST</link>.
It tells PSPP to prepare for reading data.
The word &#8216;<literal>list</literal>&#8217; intentionally appears twice.
The first occurrence is part of the <literal>DATA LIST</literal> call,
whilst the second
tells PSPP that the data is to be read as free format data with
one record per line.
</para>
</listitem><listitem><para>The &#8216;<literal>/</literal>&#8217; character is important. It marks the start of the list of
variables which you wish to define.
</para>
</listitem><listitem><para>The text &#8216;<literal>forename</literal>&#8217; is the name of the first variable,
and &#8216;<literal>(A12)</literal>&#8217; says that the variable <emphasis role="bold">forename</emphasis> is a string
variable and that its maximum length is 12 bytes.
The second variable&#8217;s name is specified by the text &#8216;<literal>height</literal>&#8217;.
Since no format is given, this variable has the default format.
Normally the default format expects numeric data, which should be
entered in the locale of the operating system.
Thus, the example is correct for English locales and other
locales which use a period (&#8216;<literal>.</literal>&#8217;) as the decimal separator.
However if you are using a system with a locale which uses the comma (&#8216;<literal>,</literal>&#8217;)
as the decimal separator, then you should in the subsequent lines substitute
&#8216;<literal>.</literal>&#8217; with &#8216;<literal>,</literal>&#8217;.
Alternatively, you could explicitly tell PSPP that the <emphasis role="bold">height</emphasis>
variable is to be read using a period as its decimal separator by appending the
text &#8216;<literal>DOT8.3</literal>&#8217; after the word &#8216;<literal>height</literal>&#8217;.
For more information on data formats, see <link linkend="Input-and-Output-Formats">Input and Output Formats</link>.
</para>

</listitem><listitem><para>Normally, PSPP displays the  prompt PSPP&gt; whenever it&#8217;s
expecting a command.
However, when it&#8217;s expecting data, the prompt changes to data&gt;
so that you know to enter data and not a command.
</para>
</listitem><listitem><para>At the end of every command there is a terminating &#8216;<literal>.</literal>&#8217; which tells
PSPP that the end of a command has been encountered.
You should not enter &#8216;<literal>.</literal>&#8217; when data is expected (<emphasis>ie.</emphasis> when
the data&gt; prompt is current) since it is appropriate only for
terminating commands.
</para></listitem></itemizedlist>
</sect2>
<sect2 label="5.1.2" id="Listing-the-data">
<title>Listing the data</title>
<indexterm role="vr"><primary>LIST</primary></indexterm>

<para>Once the data has been entered,
you could type
</para><screen>PSPP&gt; list /format=numbered.
</screen><para>to list the data.
The optional text &#8216;<literal>/format=numbered</literal>&#8217; requests the case numbers to be
shown along with the data.
It should show the following output:
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
</para><screen>           Data List
+-----------+---------+------+
|Case Number| forename|height|
+-----------+---------+------+
|1          |Ahmed    |188.00|
|2          |Bertram  |167.00|
|3          |Catherine|134.23|
|4          |David    |109.10|
+-----------+---------+------+
</screen><para>Note that the numeric variable <emphasis role="bold">height</emphasis> is displayed to 2 decimal
places, because the format for that variable is &#8216;<literal>F8.2</literal>&#8217;.
For a complete description of the <literal>LIST</literal> command, see <link linkend="LIST">LIST</link>.
</para>
</sect2>
<sect2 label="5.1.3" id="Reading-data-from-a-text-file">
<title>Reading data from a text file</title>
<indexterm role="cp"><primary>reading data</primary></indexterm>

<para>The previous example showed how to define a set of variables and to
manually enter the data for those variables.
Manual entering of data is tedious work, and often
a file containing the data will be have been previously
prepared.
Let us assume that you have a file called <filename>mydata.dat</filename> containing the
ascii encoded data:
</para><screen>Ahmed          188.00
Bertram        167.00
Catherine      134.23
David          109.10
&#160;             .
&#160;             .
&#160;             .
Zachariah      113.02
</screen><para>You can can tell the <literal>DATA LIST</literal> command to read the data directly from
this file instead of by manual entry, with a command like:
</para><screen>PSPP&gt; data list file='mydata.dat' list /forename (A12) height.
</screen><para>Notice however, that it is still necessary to specify the names of the
variables and their formats, since this information is not contained
in the file.
It is also possible to specify the file&#8217;s character encoding and other
parameters.
For full details refer to see <link linkend="DATA-LIST">DATA LIST</link>.
</para>
</sect2>
<sect2 label="5.1.4" id="Reading-data-from-a-pre_002dprepared-PSPP-file">
<title>Reading data from a pre-prepared PSPP file</title>
<indexterm role="cp"><primary>system files</primary></indexterm>
<indexterm role="vr"><primary>GET</primary></indexterm>

<para>When working with other PSPP users, or users of other software which
uses the PSPP data format, you may be given the data in
a pre-prepared PSPP file.
Such files contain not only the data, but the variable definitions,
along with their formats, labels and other meta-data.
Conventionally, these files (sometimes called &#8220;system&#8221; files)
have the suffix <filename>.sav</filename>, but that is
not mandatory.
The following syntax loads a file called <filename>my-file.sav</filename>.
</para><screen>PSPP&gt; get file='my-file.sav'.
</screen><para>You will encounter several instances of this in future examples.
</para>

</sect2>
<sect2 label="5.1.5" id="Saving-data-to-a-PSPP-file_002e">
<title>Saving data to a PSPP file.</title>
<indexterm role="cp"><primary>saving</primary></indexterm>
<indexterm role="vr"><primary>SAVE</primary></indexterm>

<para>If you want to save your data, along with the variable definitions so
that you or other PSPP users can use it later, you can do this with
the <literal>SAVE</literal> command.
</para>
<para>The following syntax will save the existing data and variables to a
file called <filename>my-new-file.sav</filename>.
</para><screen>PSPP&gt; save outfile='my-new-file.sav'.
</screen><para>If <filename>my-new-file.sav</filename> already exists, then it will be overwritten.
Otherwise it will be created.
</para>

</sect2>
<sect2 label="5.1.6" id="Reading-data-from-other-sources">
<title>Reading data from other sources</title>
<indexterm role="cp"><primary>comma separated values</primary></indexterm>
<indexterm role="cp"><primary>spreadsheets</primary></indexterm>
<indexterm role="cp"><primary>databases</primary></indexterm>

<para>Sometimes it&#8217;s useful to be able to read data from comma
separated text, from spreadsheets, databases or other sources.
In these instances you should
use the <literal>GET DATA</literal> command (see <link linkend="GET-DATA">GET DATA</link>).
</para>
</sect2>
<sect2 label="5.1.7" id="Exiting-PSPP">
<title>Exiting PSPP</title>

<para>Use the <literal>FINISH</literal> command to exit PSPP:
</para><screen>PSPP&gt; finish.
</screen>
</sect2>
</sect1>
<sect1 label="5.2" id="Data-Screening-and-Transformation">
<title>Data Screening and Transformation</title>

<indexterm role="cp"><primary>screening</primary></indexterm>
<indexterm role="cp"><primary>transformation</primary></indexterm>

<para>Once data has been entered, it is often desirable, or even necessary,
to transform it in some way before performing analysis upon it.
At the very least, it&#8217;s good practice to check for errors.
</para>

<sect2 label="5.2.1" id="Identifying-incorrect-data">
<title>Identifying incorrect data</title>
<indexterm role="cp"><primary>erroneous data</primary></indexterm>
<indexterm role="cp"><primary>errors, in data</primary></indexterm>

<para>Data from real sources is rarely error free.
PSPP has a number of procedures which can be used to help
identify data which might be incorrect.
</para>
<para>The <literal>DESCRIPTIVES</literal> command (see <link linkend="DESCRIPTIVES">DESCRIPTIVES</link>) is used to generate
simple linear statistics for a dataset.  It is also useful for
identifying potential problems in the data.
The example file <filename>physiology.sav</filename> contains a number of physiological
measurements of a sample of healthy adults selected at random.
However, the data entry clerk made a number of mistakes when entering
the data.
The following example illustrates the use of <literal>DESCRIPTIVES</literal> to screen this
data and identify the erroneous values:
</para>
<screen>PSPP&gt; get file='//share/pspp/examples/physiology.sav'.
PSPP&gt; descriptives sex, weight, height.
</screen>
<para>For this example, PSPP produces the following output:
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
</para><screen>                  Descriptive Statistics
+---------------------+--+-------+-------+-------+-------+
|                     | N|  Mean |Std Dev|Minimum|Maximum|
+---------------------+--+-------+-------+-------+-------+
|Sex of subject       |40|    .45|    .50|Male   |Female |
|Weight in kilograms  |40|  72.12|  26.70|  -55.6|   92.1|
|Height in millimeters|40|1677.12| 262.87|    179|   1903|
|Valid N (listwise)   |40|       |       |       |       |
|Missing N (listwise) | 0|       |       |       |       |
+---------------------+--+-------+-------+-------+-------+
</screen>
<para>The most interesting column in the output is the minimum value.
The <emphasis role="bold">weight</emphasis> variable has a minimum value of less than zero,
which is clearly erroneous.
Similarly, the <emphasis role="bold">height</emphasis> variable&#8217;s minimum value seems to be very low.
In fact, it is more than 5 standard deviations from the mean, and is a
seemingly bizarre height for an adult person.
</para>
<para>We can look deeper into these discrepancies by issuing an additional
<literal>EXAMINE</literal> command:
</para>
<screen>PSPP&gt; examine height, weight /statistics=extreme(3).
</screen>
<para>This command produces the following additional output (in part):
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
</para><screen>                   Extreme Values
+-------------------------------+-----------+-----+
|                               |Case Number|Value|
+-------------------------------+-----------+-----+
|Height in millimeters Highest 1|         14| 1903|
|                              2|         15| 1884|
|                              3|         12| 1802|
|                     ----------+-----------+-----+
|                      Lowest  1|         30|  179|
|                              2|         31| 1598|
|                              3|         28| 1601|
+-------------------------------+-----------+-----+
|Weight in kilograms   Highest 1|         13| 92.1|
|                              2|          5| 92.1|
|                              3|         17| 91.7|
|                     ----------+-----------+-----+
|                      Lowest  1|         38|-55.6|
|                              2|         39| 54.5|
|                              3|         33| 55.4|
+-------------------------------+-----------+-----+
</screen>
<para>From this new output, you can see that the lowest value of <emphasis role="bold">height</emphasis> is
179 (which we suspect to be erroneous), but the second lowest is 1598
which
we know from <literal>DESCRIPTIVES</literal>
is within 1 standard deviation from the mean.
Similarly, the lowest value of <emphasis role="bold">weight</emphasis> is
negative, but its second lowest value is plausible.
This suggests that the two extreme values are outliers and probably
represent data entry errors.
</para>
<para>The output also identifies the case numbers for each extreme value,
so we can see that
cases 30 and 38 are the ones with the erroneous values.
</para>
</sect2>
<sect2 label="5.2.2" id="Dealing-with-suspicious-data">
<title>Dealing with suspicious data</title>

<indexterm role="cp"><primary>SYSMIS</primary></indexterm>
<indexterm role="cp"><primary>recoding data</primary></indexterm>
<para>If possible, suspect data should be checked and re-measured.
However, this may not always be feasible, in which case the researcher may
decide to disregard these values.
PSPP has a feature whereby data can assume the special value &#8216;SYSMIS&#8217;, and
will be disregarded in future analysis. See <link linkend="Missing-Observations">Missing Observations</link>.
You can set the two suspect values to the &#8216;SYSMIS&#8217; value using the <literal>RECODE</literal>
command.
</para><screen>PSPP&gt; recode height (179 = SYSMIS).
PSPP&gt; recode weight (LOWEST THRU 0 = SYSMIS).
</screen><para>The first command says that for any observation which has a
<emphasis role="bold">height</emphasis> value of 179, that value should be changed to the SYSMIS
value.
The second command says that any <emphasis role="bold">weight</emphasis> values of zero or less
should be changed to SYSMIS.
From now on, they will be ignored in analysis.
For detailed information about the <literal>RECODE</literal> command see <link linkend="RECODE">RECODE</link>.
</para>
<para>If you now re-run the <literal>DESCRIPTIVES</literal> or <literal>EXAMINE</literal> commands from
the previous section,
you will see a data summary with more plausible parameters.
You will also notice that the data summaries indicate the two missing values.
</para>
</sect2>
<sect2 label="5.2.3" id="Inverting-negatively-coded-variables">
<title>Inverting negatively coded variables</title>

<indexterm role="cp"><primary>Likert scale</primary></indexterm>
<indexterm role="cp"><primary>Inverting data</primary></indexterm>
<para>Data entry errors are not the only reason for wanting to recode data.
The sample file <filename>hotel.sav</filename> comprises data gathered from a
customer satisfaction survey of clients at a particular hotel.
The following commands load the file and display its
variables and associated data:
</para>
<screen>PSPP&gt; get file='//share/pspp/examples/hotel.sav'.
PSPP&gt; display dictionary.
</screen>
<para>It yields the following output:
</para>
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                                   Variables
+----+--------+-------------+------------+-----+-----+---------+------+-------+
|    |        |             | Measurement|     |     |         | Print| Write |
|Name|Position|    Label    |    Level   | Role|Width|Alignment|Format| Format|
+----+--------+-------------+------------+-----+-----+---------+------+-------+
|v1  |       1|I am         |Ordinal     |Input|    8|Right    |F8.0  |F8.0   |
|    |        |satisfied    |            |     |     |         |      |       |
|    |        |with the     |            |     |     |         |      |       |
|    |        |level of     |            |     |     |         |      |       |
|    |        |service      |            |     |     |         |      |       |
|v2  |       2|The value for|Ordinal     |Input|    8|Right    |F8.0  |F8.0   |
|    |        |money was    |            |     |     |         |      |       |
|    |        |good         |            |     |     |         |      |       |
|v3  |       3|The staff    |Ordinal     |Input|    8|Right    |F8.0  |F8.0   |
|    |        |were slow in |            |     |     |         |      |       |
|    |        |responding   |            |     |     |         |      |       |
|v4  |       4|My concerns  |Ordinal     |Input|    8|Right    |F8.0  |F8.0   |
|    |        |were dealt   |            |     |     |         |      |       |
|    |        |with in an   |            |     |     |         |      |       |
|    |        |efficient    |            |     |     |         |      |       |
|    |        |manner       |            |     |     |         |      |       |
|v5  |       5|There was too|Ordinal     |Input|    8|Right    |F8.0  |F8.0   |
|    |        |much noise in|            |     |     |         |      |       |
|    |        |the rooms    |            |     |     |         |      |       |
+----+--------+-------------+------------+-----+-----+---------+------+-------+

                              Value Labels
+----------------------------------------------------+-----------------+
|Variable Value                                      |      Label      |
+----------------------------------------------------+-----------------+
|I am satisfied with the level of service           1|Strongly Disagree|
|                                                   2|Disagree         |
|                                                   3|No Opinion       |
|                                                   4|Agree            |
|                                                   5|Strongly Agree   |
+----------------------------------------------------+-----------------+
|The value for money was good                       1|Strongly Disagree|
|                                                   2|Disagree         |
|                                                   3|No Opinion       |
|                                                   4|Agree            |
|                                                   5|Strongly Agree   |
+----------------------------------------------------+-----------------+
|The staff were slow in responding                  1|Strongly Disagree|
|                                                   2|Disagree         |
|                                                   3|No Opinion       |
|                                                   4|Agree            |
|                                                   5|Strongly Agree   |
+----------------------------------------------------+-----------------+
|My concerns were dealt with in an efficient manner 1|Strongly Disagree|
|                                                   2|Disagree         |
|                                                   3|No Opinion       |
|                                                   4|Agree            |
|                                                   5|Strongly Agree   |
+----------------------------------------------------+-----------------+
|There was too much noise in the rooms              1|Strongly Disagree|
|                                                   2|Disagree         |
|                                                   3|No Opinion       |
|                                                   4|Agree            |
|                                                   5|Strongly Agree   |
+----------------------------------------------------+-----------------+
</screen>
<para>The output shows that all of the variables <emphasis role="bold">v1</emphasis> through <emphasis role="bold">v5</emphasis> are measured on a 5 point Likert scale,
with 1 meaning &#8220;Strongly disagree&#8221; and 5 meaning &#8220;Strongly agree&#8221;.
However, some of the questions are positively worded (<emphasis role="bold">v1</emphasis>, <emphasis role="bold">v2</emphasis>, <emphasis role="bold">v4</emphasis>) and others are negatively worded (<emphasis role="bold">v3</emphasis>, <emphasis role="bold">v5</emphasis>).
To perform meaningful analysis, we need to recode the variables so
that they all measure in the same direction.
We could use the <literal>RECODE</literal> command, with syntax such as:
</para><screen>recode v3 (1 = 5) (2 = 4) (4 = 2) (5 = 1).
</screen><para>However an easier and more elegant way uses the <literal>COMPUTE</literal>
command (see <link linkend="COMPUTE">COMPUTE</link>).
Since the variables are Likert variables in the range (1 &#8230; 5),
subtracting their value  from 6 has the effect of inverting them:
</para><screen>compute <replaceable>var</replaceable> = 6 - <replaceable>var</replaceable>.
</screen><para>The following section uses this technique to recode the variables
<emphasis role="bold">v3</emphasis> and <emphasis role="bold">v5</emphasis>.
After applying  <literal>COMPUTE</literal> for both variables,
all subsequent commands will use the inverted values.
</para>

</sect2>
<sect2 label="5.2.4" id="Testing-data-consistency">
<title>Testing data consistency</title>

<indexterm role="cp"><primary>reliability</primary></indexterm>
<indexterm role="cp"><primary>consistency</primary></indexterm>

<para>A sensible check to perform on survey data is the calculation of
reliability.
This gives the statistician some confidence that the questionnaires have been
completed thoughtfully.
If you examine the labels of variables <emphasis role="bold">v1</emphasis>,  <emphasis role="bold">v3</emphasis> and <emphasis role="bold">v4</emphasis>,
you will notice that they ask very similar questions.
One would therefore expect the values of these variables (after recoding)
to closely follow one another, and we can test that with the <literal>RELIABILITY</literal>
command (see <link linkend="RELIABILITY">RELIABILITY</link>).
The following example shows a PSPP session where the user recodes
negatively scaled variables and then requests reliability statistics for
<emphasis role="bold">v1</emphasis>, <emphasis role="bold">v3</emphasis>, and <emphasis role="bold">v4</emphasis>.
</para>
<screen>PSPP&gt; get file='//share/pspp/examples/hotel.sav'.
PSPP&gt; compute v3 = 6 - v3.
PSPP&gt; compute v5 = 6 - v5.
PSPP&gt; reliability v1, v3, v4.
</screen>
<para>This yields the following output:
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
</para><screen>Scale: ANY

Case Processing Summary
+--------+--+-------+
|Cases   | N|Percent|
+--------+--+-------+
|Valid   |17| 100.0%|
|Excluded| 0|    .0%|
|Total   |17| 100.0%|
+--------+--+-------+

    Reliability Statistics
+----------------+----------+
|Cronbach's Alpha|N of Items|
+----------------+----------+
|             .81|         3|
+----------------+----------+
</screen>
<para>As a rule of thumb, many statisticians consider a value of Cronbach&#8217;s Alpha of
0.7 or higher to indicate reliable data.
</para>
<para>Here, the value is 0.81, which suggests a high degree of reliability
among variables <emphasis role="bold">v1</emphasis>, <emphasis role="bold">v3</emphasis> and <emphasis role="bold">v4</emphasis>, so the data and
the recoding that we performed are vindicated.
</para>

</sect2>
<sect2 label="5.2.5" id="Testing-for-normality">
<title>Testing for normality</title>
<indexterm role="cp"><primary>normality, testing</primary></indexterm>

<para>Many statistical tests rely upon certain properties of the data.
One common property, upon which many linear tests depend, is that of
normality &#8212; the data must have been drawn from a normal distribution.
It is necessary then to ensure normality before deciding upon the
test procedure to use.  One way to do this uses the <literal>EXAMINE</literal> command.
</para>
<para>In the following example, a researcher was examining the failure rates
of equipment produced by an engineering company.
The file <filename>repairs.sav</filename> contains the mean time between
failures (<emphasis role="bold">mtbf</emphasis>) of some items of equipment subject to the study.
Before performing linear analysis on the data,
the researcher wanted to ascertain that the data is normally distributed.
</para>
<screen>PSPP&gt; get file='//share/pspp/examples/repairs.sav'.
PSPP&gt; examine mtbf
                /statistics=descriptives.
</screen>
<para>This produces the following output:
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
</para><screen>                                  Descriptives
+----------------------------------------------------------+---------+--------+
|                                                          |         |  Std.  |
|                                                          |Statistic|  Error |
+----------------------------------------------------------+---------+--------+
|Mean time between        Mean                             |     8.78|    1.10|
|failures (months)       ----------------------------------+---------+--------+
|                         95% Confidence Interval Lower    |     6.53|        |
|                         for Mean                Bound    |         |        |
|                                                 Upper    |    11.04|        |
|                                                 Bound    |         |        |
|                        ----------------------------------+---------+--------+
|                         5% Trimmed Mean                  |     8.20|        |
|                        ----------------------------------+---------+--------+
|                         Median                           |     8.29|        |
|                        ----------------------------------+---------+--------+
|                         Variance                         |    36.34|        |
|                        ----------------------------------+---------+--------+
|                         Std. Deviation                   |     6.03|        |
|                        ----------------------------------+---------+--------+
|                         Minimum                          |     1.63|        |
|                        ----------------------------------+---------+--------+
|                         Maximum                          |    26.47|        |
|                        ----------------------------------+---------+--------+
|                         Range                            |    24.84|        |
|                        ----------------------------------+---------+--------+
|                         Interquartile Range              |     6.03|        |
|                        ----------------------------------+---------+--------+
|                         Skewness                         |     1.65|     .43|
|                        ----------------------------------+---------+--------+
|                         Kurtosis                         |     3.41|     .83|
+----------------------------------------------------------+---------+--------+
</screen>
<para>A normal distribution has a skewness and kurtosis of zero.
The skewness of <emphasis role="bold">mtbf</emphasis> in the output above makes it clear
that the mtbf figures have a lot of positive skew and are therefore
not drawn from a normally distributed variable.
Positive skew can often be compensated for by applying a logarithmic
transformation, as in the following continuation of the example:
</para>
<screen>PSPP&gt; compute mtbf_ln = ln (mtbf).
PSPP&gt; examine mtbf_ln
                /statistics=descriptives.
</screen>
<para>which produces the following additional output:
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
</para><screen>                                Descriptives
+----------------------------------------------------+---------+----------+
|                                                    |Statistic|Std. Error|
+----------------------------------------------------+---------+----------+
|mtbf_ln Mean                                        |     1.95|       .13|
|       ---------------------------------------------+---------+----------+
|        95% Confidence Interval for Mean Lower Bound|     1.69|          |
|                                         Upper Bound|     2.22|          |
|       ---------------------------------------------+---------+----------+
|        5% Trimmed Mean                             |     1.96|          |
|       ---------------------------------------------+---------+----------+
|        Median                                      |     2.11|          |
|       ---------------------------------------------+---------+----------+
|        Variance                                    |      .49|          |
|       ---------------------------------------------+---------+----------+
|        Std. Deviation                              |      .70|          |
|       ---------------------------------------------+---------+----------+
|        Minimum                                     |      .49|          |
|       ---------------------------------------------+---------+----------+
|        Maximum                                     |     3.28|          |
|       ---------------------------------------------+---------+----------+
|        Range                                       |     2.79|          |
|       ---------------------------------------------+---------+----------+
|        Interquartile Range                         |      .88|          |
|       ---------------------------------------------+---------+----------+
|        Skewness                                    |     -.37|       .43|
|       ---------------------------------------------+---------+----------+
|        Kurtosis                                    |      .01|       .83|
+----------------------------------------------------+---------+----------+
</screen>
<para>The <literal>COMPUTE</literal> command in the first line above performs the
logarithmic transformation:
</para><screen>compute mtbf_ln = ln (mtbf).
</screen><para>Rather than redefining the existing variable, this use of <literal>COMPUTE</literal>
defines a new variable <emphasis role="bold">mtbf_ln</emphasis> which is
the natural logarithm of <emphasis role="bold">mtbf</emphasis>.
The final command in this example calls <literal>EXAMINE</literal> on this new variable.
The results show that both the skewness and
kurtosis for <emphasis role="bold">mtbf_ln</emphasis> are very close to zero.
This provides some confidence that the <emphasis role="bold">mtbf_ln</emphasis> variable is
normally distributed and thus safe for linear analysis.
In the event that no suitable transformation can be found,
then it would be worth considering
an appropriate non-parametric test instead of a linear one.
See <link linkend="NPAR-TESTS">NPAR TESTS</link>, for information about non-parametric tests.
</para>
</sect2>
</sect1>
<sect1 label="5.3" id="Hypothesis-Testing">
<title>Hypothesis Testing</title>

<indexterm role="cp"><primary>Hypothesis testing</primary></indexterm>
<indexterm role="cp"><primary>p-value</primary></indexterm>
<indexterm role="cp"><primary>null hypothesis</primary></indexterm>

<para>One of the most fundamental purposes of statistical analysis
is hypothesis testing.
Researchers commonly need to test hypotheses about a set of data.
For example, she might want to test whether one set of data comes from
the same distribution as another,
or
whether the mean of a dataset significantly differs from a particular
value.
This section presents just some of the possible tests that PSPP offers.
</para>
<para>The researcher starts by making a <firstterm>null hypothesis</firstterm>.
Often this is a hypothesis which he suspects to be false.
For example, if he suspects that <replaceable>A</replaceable> is greater than <replaceable>B</replaceable> he will
state the null hypothesis as <inlineequation><mathphrase><replaceable>A</replaceable> = <replaceable>B</replaceable></mathphrase></inlineequation>.<!-- -->
<footnote><para>This example assumes that it is already proven that <replaceable>B</replaceable> is
not greater than <replaceable>A</replaceable>.</para></footnote>
</para>
<para>The <firstterm>p-value</firstterm> is a recurring concept in hypothesis testing.
It is the highest acceptable probability that the evidence implying a
null hypothesis is false, could have been obtained when the null
hypothesis is in fact true.
Note that this is not the same as &#8220;the probability of making an
error&#8221; nor is it the same as &#8220;the probability of rejecting a
hypothesis when it is true&#8221;.
</para>



<sect2 label="5.3.1" id="Testing-for-differences-of-means">
<title>Testing for differences of means</title>

<indexterm role="cp"><primary>T-test</primary></indexterm>
<indexterm role="vr"><primary>T-TEST</primary></indexterm>

<para>A common statistical test involves hypotheses about means.
The <literal>T-TEST</literal> command is used to find out whether or not two separate
subsets have the same mean.
</para>
<para>A researcher suspected that the heights and core body
temperature of persons might be different depending upon their sex.
To investigate this, he posed two null hypotheses based on the data
from <filename>physiology.sav</filename> previously encountered:
</para><itemizedlist><listitem><para>The mean heights of males and females in the population are equal.
</para></listitem><listitem><para>The mean body temperature of males and
      females in the population are equal.
</para></listitem></itemizedlist><para>For the purposes of the investigation the researcher
decided to use a  p-value of 0.05.
</para>
<para>In addition to the T-test, the <literal>T-TEST</literal> command also performs the
Levene test for equal variances.
If the variances are equal, then a more powerful form of the T-test can be used.
However if it is unsafe to assume equal variances,
then an alternative calculation is necessary.
PSPP performs both calculations.
</para>
<para>For the <emphasis role="bold">height</emphasis> variable, the output shows the significance of the
Levene test to be 0.33 which means there is a
33% probability that the
Levene test produces this outcome when the variances are equal.
Had the significance been less than 0.05, then it would have been unsafe to assume that
the variances were equal.
However, because the value is higher than 0.05 the homogeneity of variances assumption
is safe and the &#8220;Equal Variances&#8221; row (the more powerful test) can be used.
Examining this row, the two tailed significance for the <emphasis role="bold">height</emphasis> t-test
is less than 0.05, so it is safe to reject the null hypothesis and conclude
that the mean heights of males and females are unequal.
</para>
<para>For the <emphasis role="bold">temperature</emphasis> variable, the significance of the Levene test
is 0.58 so again, it is safe to use the row for equal variances.
The equal variances row indicates that the two tailed significance for
<emphasis role="bold">temperature</emphasis> is 0.20.  Since this is greater than 0.05 we must reject
the null hypothesis and conclude that there is insufficient evidence to
suggest that the body temperature of male and female persons are different.
</para>
<para>The syntax for this analysis is:
</para><screen>PSPP&gt; get file='//share/pspp/examples/physiology.sav'.
PSPP&gt; recode height (179 = SYSMIS).
PSPP&gt; t-test group=sex(0,1) /variables = height temperature.
</screen>
<para>PSPP produces the following output for this syntax:
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
</para><screen>                                Group Statistics
+-------------------------------------------+--+-------+-------------+--------+
|                                           |  |       |     Std.    |  S.E.  |
|                                     Group | N|  Mean |  Deviation  |  Mean  |
+-------------------------------------------+--+-------+-------------+--------+
|Height in millimeters                Male  |22|1796.49|        49.71|   10.60|
|                                     Female|17|1610.77|        25.43|    6.17|
+-------------------------------------------+--+-------+-------------+--------+
|Internal body temperature in degrees Male  |22|  36.68|         1.95|     .42|
|Celcius                              Female|18|  37.43|         1.61|     .38|
+-------------------------------------------+--+-------+-------------+--------+

                          Independent Samples Test
+---------------------+----------+------------------------------------------
|                     | Levene's |
|                     | Test for |
|                     | Equality |
|                     |    of    |
|                     | Variances|              T-Test for Equality of Means
|                     +----+-----+-----+-----+-------+----------+----------+
|                     |    |     |     |     |       |          |          |
|                     |    |     |     |     |       |          |          |
|                     |    |     |     |     |       |          |          |
|                     |    |     |     |     |       |          |          |
|                     |    |     |     |     |  Sig. |          |          |
|                     |    |     |     |     |  (2-  |   Mean   |Std. Error|
|                     |  F | Sig.|  t  |  df |tailed)|Difference|Difference|
+---------------------+----+-----+-----+-----+-------+----------+----------+
|Height in   Equal    | .97| .331|14.02|37.00|   .000|    185.72|     13.24|
|millimeters variances|    |     |     |     |       |          |          |
|            assumed  |    |     |     |     |       |          |          |
|            Equal    |    |     |15.15|32.71|   .000|    185.72|     12.26|
|            variances|    |     |     |     |       |          |          |
|            not      |    |     |     |     |       |          |          |
|            assumed  |    |     |     |     |       |          |          |
+---------------------+----+-----+-----+-----+-------+----------+----------+
|Internal    Equal    | .31| .581|-1.31|38.00|   .198|      -.75|       .57|
|body        variances|    |     |     |     |       |          |          |
|temperature assumed  |    |     |     |     |       |          |          |
|in degrees  Equal    |    |     |-1.33|37.99|   .190|      -.75|       .56|
|Celcius     variances|    |     |     |     |       |          |          |
|            not      |    |     |     |     |       |          |          |
|            assumed  |    |     |     |     |       |          |          |
+---------------------+----+-----+-----+-----+-------+----------+----------+

+---------------------+-------------+
|                     |             |
|                     |             |
|                     |             |
|                     |             |
|                     |             |
|                     +-------------+
|                     |     95%     |
|                     |  Confidence |
|                     | Interval of |
|                     |     the     |
|                     |  Difference |
|                     +------+------+
|                     | Lower| Upper|
+---------------------+------+------+
|Height in   Equal    |158.88|212.55|
|millimeters variances|      |      |
|            assumed  |      |      |
|            Equal    |160.76|210.67|
|            variances|      |      |
|            not      |      |      |
|            assumed  |      |      |
+---------------------+------+------+
|Internal    Equal    | -1.91|   .41|
|body        variances|      |      |
|temperature assumed  |      |      |
|in degrees  Equal    | -1.89|   .39|
|Celcius     variances|      |      |
|            not      |      |      |
|            assumed  |      |      |
+---------------------+------+------+
</screen>
<para>The <literal>T-TEST</literal> command tests for differences of means.
Here, the <emphasis role="bold">height</emphasis> variable&#8217;s two tailed significance is less than
0.05, so the null hypothesis can be rejected.
Thus, the evidence suggests there is a difference between the heights of
male and female persons.
However the significance of the test for the <emphasis role="bold">temperature</emphasis>
variable is greater than 0.05 so the null hypothesis cannot be
rejected, and there is insufficient evidence to suggest a difference
in body temperature.
</para>
</sect2>
<sect2 label="5.3.2" id="Linear-Regression">
<title>Linear Regression</title>
<indexterm role="cp"><primary>linear regression</primary></indexterm>
<indexterm role="vr"><primary>REGRESSION</primary></indexterm>

<para>Linear regression is a technique used to investigate if and how a variable
is linearly related to others.
If a variable is found to be linearly related, then this can be used to
predict future values of that variable.
</para>
<para>In the following example, the service department of the company wanted to
be able to predict the time to repair equipment, in order to improve
the accuracy of their quotations.
It was suggested that the time to repair might be related to the time
between failures and the duty cycle of the equipment.
The p-value of 0.1 was chosen for this investigation.
In order to investigate this hypothesis, the <literal>REGRESSION</literal> command
was used.
This command not only tests if the variables are related, but also
identifies the potential linear relationship. See <link linkend="REGRESSION">REGRESSION</link>.
</para>
<para>A first attempt includes <emphasis role="bold">duty_cycle</emphasis>:
</para>
<screen>PSPP&gt; get file='//share/pspp/examples/repairs.sav'.
PSPP&gt; regression /variables = mtbf duty_cycle /dependent = mttr.
</screen>
<para>This attempt yields the following output (in part):
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
</para><screen>                  Coefficients (Mean time to repair (hours) )
+------------------------+---------------------+-------------------+-----+----+
|                        |    Unstandardized   |    Standardized   |     |    |
|                        |     Coefficients    |    Coefficients   |     |    |
|                        +---------+-----------+-------------------+     |    |
|                        |    B    | Std. Error|        Beta       |  t  |Sig.|
+------------------------+---------+-----------+-------------------+-----+----+
|(Constant)              |    10.59|       3.11|                .00| 3.40|.002|
|Mean time between       |     3.02|        .20|                .95|14.88|.000|
|failures (months)       |         |           |                   |     |    |
|Ratio of working to non-|    -1.12|       3.69|               -.02| -.30|.763|
|working time            |         |           |                   |     |    |
+------------------------+---------+-----------+-------------------+-----+----+
</screen>
<para>The coefficients in the above table suggest that the formula
<inlineequation><mathphrase><replaceable>mttr</replaceable> = 9.81 + 3.1 \times <replaceable>mtbf</replaceable> + 1.09 \times <replaceable>duty_cycle</replaceable></mathphrase></inlineequation>
can be used to predict the time to repair.
However, the significance value for the <replaceable>duty_cycle</replaceable> coefficient
is very high, which would make this an unsafe predictor.
For this reason, the test was repeated, but omitting the
<emphasis role="bold">duty_cycle</emphasis> variable:
</para>
<screen>PSPP&gt; regression /variables = mtbf /dependent = mttr.
</screen>
<para>This second try produces the following output (in part):
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
</para><screen>                  Coefficients (Mean time to repair (hours) )
+-----------------------+----------------------+-------------------+-----+----+
|                       |    Unstandardized    |    Standardized   |     |    |
|                       |     Coefficients     |    Coefficients   |     |    |
|                       +---------+------------+-------------------+     |    |
|                       |    B    | Std. Error |        Beta       |  t  |Sig.|
+-----------------------+---------+------------+-------------------+-----+----+
|(Constant)             |     9.90|        2.10|                .00| 4.71|.000|
|Mean time between      |     3.01|         .20|                .94|15.21|.000|
|failures (months)      |         |            |                   |     |    |
+-----------------------+---------+------------+-------------------+-----+----+
</screen>
<para>This time, the significance of all coefficients is no higher than 0.06,
suggesting that at the 0.06 level, the formula
<inlineequation><mathphrase><replaceable>mttr</replaceable> = 10.5 + 3.11 \times <replaceable>mtbf</replaceable></mathphrase></inlineequation> is a reliable
predictor of the time to repair.
</para>

<!--  LocalWords:  PSPP dir itemize noindent var cindex dfn cartouche samp xref -->
<!--  LocalWords:  pxref ie sav Std Dev kilograms SYSMIS sansserif pre pspp emph -->
<!--  LocalWords:  Likert Cronbach's Cronbach mtbf npplot ln myfile cmd NPAR Sig -->
<!--  LocalWords:  vindex Levene Levene's df Diff clicksequence mydata dat ascii -->
<!--  LocalWords:  mttr outfile -->
<!-- PSPP - a program for statistical analysis. -->
<!-- Copyright (C) 2017, 2020 Free Software Foundation, Inc. -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.3 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<!-- A copy of the license is included in the section entitled "GNU -->
<!-- Free Documentation License". -->
<!-- -->
</sect2>
</sect1>
</chapter>
<chapter label="6" id="Language">
<title>The PSPP language</title>
<indexterm role="cp"><primary>language, PSPP</primary></indexterm>
<indexterm role="cp"><primary>PSPP, language</primary></indexterm>

<para>This chapter discusses elements common to many PSPP commands.
Later chapters describe individual commands in detail.
</para>


<sect1 label="6.1" id="Tokens">
<title>Tokens</title>
<indexterm role="cp"><primary>language, lexical analysis</primary></indexterm>
<indexterm role="cp"><primary>language, tokens</primary></indexterm>
<indexterm role="cp"><primary>tokens</primary></indexterm>
<indexterm role="cp"><primary>lexical analysis</primary></indexterm>

<para>PSPP divides most syntax file lines into series of short chunks
called <firstterm>tokens</firstterm>.
Tokens are then grouped to form commands, each of which tells
PSPP to take some action&#8212;read in data, write out data, perform
a statistical procedure, etc.  Each type of token is
described below.
</para>
<variablelist><varlistentry><term><indexterm role="cp"><primary>identifiers</primary></indexterm>
<emphasis role="bold">Identifiers</emphasis>
</term><listitem><para>Identifiers are names that typically specify variables, commands, or
subcommands.  The first character in an identifier must be a letter,
&#8216;<literal>#</literal>&#8217;, or &#8216;<literal>@</literal>&#8217;.  The remaining characters in the identifier
must be letters, digits, or one of the following special characters:
</para>
<simpara role="center">.  _  $  #  @</simpara>

<indexterm role="cp"><primary>case-sensitivity</primary></indexterm>
<para>Identifiers may be any length, but only the first 64 bytes are
significant.  Identifiers are not case-sensitive: <literal>foobar</literal>,
<literal>Foobar</literal>, <literal>FooBar</literal>, <literal>FOOBAR</literal>, and <literal>FoObaR</literal> are
different representations of the same identifier.
</para>
<indexterm role="cp"><primary>identifiers, reserved</primary></indexterm>
<indexterm role="cp"><primary>reserved identifiers</primary></indexterm>
<para>Some identifiers are reserved.  Reserved identifiers may not be used
in any context besides those explicitly described in this manual.  The
reserved identifiers are:
</para>
<simpara role="center">ALL  AND  BY  EQ  GE  GT  LE  LT  NE  NOT  OR  TO  WITH</simpara>

</listitem></varlistentry><varlistentry><term><emphasis role="bold">Keywords</emphasis>
</term><listitem><para>Keywords are a subclass of identifiers that form a fixed part of
command syntax.  For example, command and subcommand names are
keywords.  Keywords may be abbreviated to their first 3 characters if
this abbreviation is unambiguous.  (Unique abbreviations of 3 or more
characters are also accepted: &#8216;<literal>FRE</literal>&#8217;, &#8216;<literal>FREQ</literal>&#8217;, and
&#8216;<literal>FREQUENCIES</literal>&#8217; are equivalent when the last is a keyword.)
</para>
<para>Reserved identifiers are always used as keywords.  Other identifiers
may be used both as keywords and as user-defined identifiers, such as
variable names.
</para>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Numbers</emphasis>
</term><listitem><indexterm role="cp"><primary>numbers</primary></indexterm>
<indexterm role="cp"><primary>integers</primary></indexterm>
<indexterm role="cp"><primary>reals</primary></indexterm>
<para>Numbers are expressed in decimal.  A decimal point is optional.
Numbers may be expressed in scientific notation by adding &#8216;<literal>e</literal>&#8217; and
a base-10 exponent, so that &#8216;<literal>1.234e3</literal>&#8217; has the value 1234.  Here
are some more examples of valid numbers:
</para>
<screen>-5  3.14159265359  1e100  -.707  8945.
</screen>
<para>Negative numbers are expressed with a &#8216;<literal>-</literal>&#8217; prefix.  However, in
situations where a literal &#8216;<literal>-</literal>&#8217; token is expected, what appears to
be a negative number is treated as &#8216;<literal>-</literal>&#8217; followed by a positive
number.
</para>
<para>No white space is allowed within a number token, except for horizontal
white space between &#8216;<literal>-</literal>&#8217; and the rest of the number.
</para>
<para>The last example above, &#8216;<literal>8945.</literal>&#8217; is interpreted as two
tokens, &#8216;<literal>8945</literal>&#8217; and &#8216;<literal>.</literal>&#8217;, if it is the last token on a line.
See <link linkend="Commands">Forming commands of tokens</link>.
</para>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Strings</emphasis>
</term><listitem><indexterm role="cp"><primary>strings</primary></indexterm>
<indexterm role="cp"><primary>&#8216;<literal>'</literal>&#8217;</primary></indexterm>
<indexterm role="cp"><primary>&#8216;<literal>&quot;</literal>&#8217;</primary></indexterm>
<indexterm role="cp"><primary>case-sensitivity</primary></indexterm>
<para>Strings are literal sequences of characters enclosed in pairs of
single quotes (&#8216;<literal>'</literal>&#8217;) or double quotes (&#8216;<literal>&quot;</literal>&#8217;).  To include the
character used for quoting in the string, double it, <emphasis>e.g.</emphasis>
&#8216;<literal>'it''s an apostrophe'</literal>&#8217;.  White space and case of letters are
significant inside strings.
</para>
<para>Strings can be concatenated using &#8216;<literal>+</literal>&#8217;, so that &#8216;<literal>&quot;a&quot; + 'b' +
'c'</literal>&#8217; is equivalent to &#8216;<literal>'abc'</literal>&#8217;.  So that a long string may be
broken across lines, a line break may precede or follow, or both
precede and follow, the &#8216;<literal>+</literal>&#8217;.  (However, an entirely blank line
preceding or following the &#8216;<literal>+</literal>&#8217; is interpreted as ending the
current command.)
</para>
<para>Strings may also be expressed as hexadecimal character values by
prefixing the initial quote character by &#8216;<literal>x</literal>&#8217; or &#8216;<literal>X</literal>&#8217;.
Regardless of the syntax file or active dataset&#8217;s encoding, the
hexadecimal digits in the string are interpreted as Unicode characters
in UTF-8 encoding.
</para>
<para>Individual Unicode code points may also be expressed by specifying the
hexadecimal code point number in single or double quotes preceded by
&#8216;<literal>u</literal>&#8217; or &#8216;<literal>U</literal>&#8217;.  For example, Unicode code point U+1D11E, the
musical G clef character, could be expressed as <literal>U'1D11E'</literal>.
Invalid Unicode code points (above U+10FFFF or in between U+D800 and
U+DFFF) are not allowed.
</para>
<para>When strings are concatenated with &#8216;<literal>+</literal>&#8217;, each segment&#8217;s prefix is
considered individually.  For example, <literal>'The G clef symbol is:' +
u&quot;1d11e&quot; + &quot;.&quot;</literal> inserts a G clef symbol in the middle of an otherwise
plain text string.
</para>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Punctuators and Operators</emphasis>
</term><listitem><indexterm role="cp"><primary>punctuators</primary></indexterm>
<indexterm role="cp"><primary>operators</primary></indexterm>
<para>These tokens are the punctuators and operators:
</para>
<simpara role="center">,  /  =  (  )  +  -  *  /  **  &lt;  &lt;=  &lt;&gt;  &gt;  &gt;=  ~=  &amp;  |  .</simpara>

<para>Most of these appear within the syntax of commands, but the period
(&#8216;<literal>.</literal>&#8217;) punctuator is used only at the end of a command.  It is a
punctuator only as the last character on a line (except white space).
When it is the last non-space character on a line, a period is not
treated as part of another token, even if it would otherwise be part
of, <emphasis>e.g.</emphasis>, an identifier or a floating-point number.
</para></listitem></varlistentry></variablelist>
</sect1>
<sect1 label="6.2" id="Commands">
<title>Forming commands of tokens</title>

<indexterm role="cp"><primary>PSPP, command structure</primary></indexterm>
<indexterm role="cp"><primary>language, command structure</primary></indexterm>
<indexterm role="cp"><primary>commands, structure</primary></indexterm>

<para>Most PSPP commands share a common structure.  A command begins with a
command name, such as <literal>FREQUENCIES</literal>, <literal>DATA LIST</literal>, or <literal>N OF
CASES</literal>.  The command name may be abbreviated to its first word, and
each word in the command name may be abbreviated to its first three
or more characters, where these abbreviations are unambiguous.
</para>
<para>The command name may be followed by one or more <firstterm>subcommands</firstterm>.
Each subcommand begins with a subcommand name, which may be
abbreviated to its first three letters.  Some subcommands accept a
series of one or more specifications, which follow the subcommand
name, optionally separated from it by an equals sign
(&#8216;<literal>=</literal>&#8217;). Specifications may be separated from each other
by commas or spaces.  Each subcommand must be separated from the next (if any)
by a forward slash (&#8216;<literal>/</literal>&#8217;).
</para>
<para>There are multiple ways to mark the end of a command.  The most common
way is to end the last line of the command with a period (&#8216;<literal>.</literal>&#8217;) as
described in the previous section (see <link linkend="Tokens">Tokens</link>).  A blank line, or
one that consists only of white space or comments, also ends a command.
</para>
</sect1>
<sect1 label="6.3" id="Syntax-Variants">
<title>Syntax Variants</title>

<indexterm role="cp"><primary>Batch syntax</primary></indexterm>
<indexterm role="cp"><primary>Interactive syntax</primary></indexterm>

<para>There are three variants of command syntax, which vary only in how
they detect the end of one command and the start of the next.
</para>
<para>In <firstterm>interactive mode</firstterm>, which is the default for syntax typed at a
command prompt, a period as the last non-blank character on a line
ends a command.  A blank line also ends a command.
</para>
<para>In <firstterm>batch mode</firstterm>, an end-of-line period or a blank line also ends a
command.  Additionally, it treats any line that has a non-blank
character in the leftmost column as beginning a new command.  Thus, in
batch mode the second and subsequent lines in a command must be
indented.
</para>
<para>Regardless of the syntax mode, a plus sign, minus sign, or period in
the leftmost column of a line is ignored and causes that line to begin
a new command.  This is most useful in batch mode, in which the first
line of a new command could not otherwise be indented, but it is
accepted regardless of syntax mode.
</para>
<para>The default mode for reading commands from a file is <firstterm>auto mode</firstterm>.
It is the same as batch mode, except that a line with a non-blank in
the leftmost column only starts a new command if that line begins with
the name of a PSPP command.  This correctly interprets most valid PSPP
syntax files regardless of the syntax mode for which they are
intended.
</para>
<para>The <option>--interactive</option> (or <option>-i</option>) or <option>--batch</option> (or
<option>-b</option>) options set the syntax mode for files listed on the PSPP
command line.  See <link linkend="Main-Options">Main Options</link>, for more details.
</para>
</sect1>
<sect1 label="6.4" id="Types-of-Commands">
<title>Types of Commands</title>

<para>Commands in PSPP are divided roughly into six categories:
</para>
<variablelist><varlistentry><term><emphasis role="bold">Utility commands</emphasis>
</term><listitem><indexterm role="cp"><primary>utility commands</primary></indexterm>
<para>Set or display various global options that affect PSPP operations.
May appear anywhere in a syntax file.  See <link linkend="Utilities">Utility
commands</link>.
</para>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">File definition commands</emphasis>
</term><listitem><indexterm role="cp"><primary>file definition commands</primary></indexterm>
<para>Give instructions for reading data from text files or from special
binary &#8220;system files&#8221;.  Most of these commands replace any previous
data or variables with new data or
variables.  At least one file definition command must appear before the first command in any of
the categories below.  See <link linkend="Data-Input-and-Output">Data Input and Output</link>.
</para>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Input program commands</emphasis>
</term><listitem><indexterm role="cp"><primary>input program commands</primary></indexterm>
<para>Though rarely used, these provide tools for reading data files
in arbitrary textual or binary formats.  See <link linkend="INPUT-PROGRAM">INPUT PROGRAM</link>.
</para>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Transformations</emphasis>
</term><listitem><indexterm role="cp"><primary>transformations</primary></indexterm>
<para>Perform operations on data and write data to output files.  Transformations
are not carried out until a procedure is executed.
</para>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Restricted transformations</emphasis>
</term><listitem><indexterm role="cp"><primary>restricted transformations</primary></indexterm>
<para>Transformations that cannot appear in certain contexts.  See <link linkend="Order-of-Commands">Order
of Commands</link>, for details.
</para>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Procedures</emphasis>
</term><listitem><indexterm role="cp"><primary>procedures</primary></indexterm>
<para>Analyze data, writing results of analyses to the listing file.  Cause
transformations specified earlier in the file to be performed.  In a
more general sense, a <firstterm>procedure</firstterm> is any command that causes the
active dataset (the data) to be read.
</para></listitem></varlistentry></variablelist>
</sect1>
<sect1 label="6.5" id="Order-of-Commands">
<title>Order of Commands</title>
<indexterm role="cp"><primary>commands, ordering</primary></indexterm>
<indexterm role="cp"><primary>order of commands</primary></indexterm>

<para>PSPP does not place many restrictions on ordering of commands.  The
main restriction is that variables must be defined before they are otherwise
referenced.  This section describes the details of command ordering,
but most users will have no need to refer to them.
</para>
<para>PSPP possesses five internal states, called <firstterm>initial</firstterm>, <firstterm>input-program</firstterm>
<firstterm>file-type</firstterm>, <firstterm>transformation</firstterm>, and <firstterm>procedure</firstterm> states.  (Please note the
distinction between the <literal>INPUT PROGRAM</literal> and <literal>FILE TYPE</literal>
<emphasis>commands</emphasis> and the <firstterm>input-program</firstterm> and <firstterm>file-type</firstterm> <emphasis>states</emphasis>.)
</para>
<para>PSPP starts in the initial state.  Each successful completion
of a command may cause a state transition.  Each type of command has its
own rules for state transitions:
</para>
<variablelist><varlistentry><term><emphasis role="bold">Utility commands</emphasis>
</term><listitem><itemizedlist><listitem><para>Valid in any state.
</para></listitem><listitem><para>Do not cause state transitions.  Exception: when <literal>N OF CASES</literal>
is executed in the procedure state, it causes a transition to the
transformation state.
</para></listitem></itemizedlist>
</listitem></varlistentry><varlistentry><term><emphasis role="bold"><literal>DATA LIST</literal></emphasis>
</term><listitem><itemizedlist><listitem><para>Valid in any state.
</para></listitem><listitem><para>When executed in the initial or procedure state, causes a transition to
the transformation state.
</para></listitem><listitem><para>Clears the active dataset if executed in the procedure or transformation
state.
</para></listitem></itemizedlist>
</listitem></varlistentry><varlistentry><term><emphasis role="bold"><literal>INPUT PROGRAM</literal></emphasis>
</term><listitem><itemizedlist><listitem><para>Invalid in input-program and file-type states.
</para></listitem><listitem><para>Causes a transition to the intput-program state.
</para></listitem><listitem><para>Clears the active dataset.
</para></listitem></itemizedlist>
</listitem></varlistentry><varlistentry><term><emphasis role="bold"><literal>FILE TYPE</literal></emphasis>
</term><listitem><itemizedlist><listitem><para>Invalid in intput-program and file-type states.
</para></listitem><listitem><para>Causes a transition to the file-type state.
</para></listitem><listitem><para>Clears the active dataset.
</para></listitem></itemizedlist>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Other file definition commands</emphasis>
</term><listitem><itemizedlist><listitem><para>Invalid in input-program and file-type states.
</para></listitem><listitem><para>Cause a transition to the transformation state.
</para></listitem><listitem><para>Clear the active dataset, except for <literal>ADD FILES</literal>, <literal>MATCH FILES</literal>,
and <literal>UPDATE</literal>.
</para></listitem></itemizedlist>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Transformations</emphasis>
</term><listitem><itemizedlist><listitem><para>Invalid in initial and file-type states.
</para></listitem><listitem><para>Cause a transition to the transformation state.
</para></listitem></itemizedlist>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Restricted transformations</emphasis>
</term><listitem><itemizedlist><listitem><para>Invalid in initial, input-program, and file-type states.
</para></listitem><listitem><para>Cause a transition to the transformation state.
</para></listitem></itemizedlist>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Procedures</emphasis>
</term><listitem><itemizedlist><listitem><para>Invalid in initial, input-program, and file-type states.
</para></listitem><listitem><para>Cause a transition to the procedure state.
</para></listitem></itemizedlist></listitem></varlistentry></variablelist>
</sect1>
<sect1 label="6.6" id="Missing-Observations">
<title>Handling missing observations</title>
<indexterm role="cp"><primary>missing values</primary></indexterm>
<indexterm role="cp"><primary>values, missing</primary></indexterm>

<para>PSPP includes special support for unknown numeric data values.
Missing observations are assigned a special value, called the
<firstterm>system-missing value</firstterm>.  This &#8220;value&#8221; actually indicates the
absence of a value; it means that the actual value is unknown.  Procedures
automatically exclude from analyses those observations or cases that
have missing values.  Details of missing value exclusion depend on the
procedure and can often be controlled by the user; refer to
descriptions of individual procedures for details.
</para>
<para>The system-missing value exists only for numeric variables.  String
variables always have a defined value, even if it is only a string of
spaces.
</para>
<para>Variables, whether numeric or string, can have designated
<firstterm>user-missing values</firstterm>.  Every user-missing value is an actual value
for that variable.  However, most of the time user-missing values are
treated in the same way as the system-missing value.
</para>
<para>For more information on missing values, see the following sections:
<link linkend="Datasets">Datasets</link>, <link linkend="MISSING-VALUES">MISSING VALUES</link>, <link linkend="Expressions">Expressions</link>.  See also the
documentation on individual procedures for information on how they
handle missing values.
</para>
</sect1>
<sect1 label="6.7" id="Datasets">
<title>Datasets</title>
<indexterm role="cp"><primary>dataset</primary></indexterm>
<indexterm role="cp"><primary>variable</primary></indexterm>
<indexterm role="cp"><primary>dictionary</primary></indexterm>

<para>PSPP works with data organized into <firstterm>datasets</firstterm>.  A dataset
consists of a set of <firstterm>variables</firstterm>, which taken together are said to
form a <firstterm>dictionary</firstterm>, and one or more <firstterm>cases</firstterm>, each of which
has one value for each variable.
</para>
<para>At any given time PSPP has exactly one distinguished dataset, called
the <firstterm>active dataset</firstterm>.  Most PSPP commands work only with the
active dataset.  In addition to the active dataset, PSPP also supports
any number of additional open datasets.  The <literal>DATASET</literal> commands
can choose a new active dataset from among those that are open, as
well as create and destroy datasets (see <link linkend="DATASET">DATASET</link>).
</para>
<para>The sections below describe variables in more detail.
</para>

<sect2 label="6.7.1" id="Attributes">
<title>Attributes of Variables</title>
<indexterm role="cp"><primary>variables, attributes of</primary></indexterm>
<indexterm role="cp"><primary>attributes of variables</primary></indexterm>
<para>Each variable has a number of attributes, including:
</para>
<variablelist><varlistentry><term><emphasis role="bold">Name</emphasis>
</term><listitem><para>An identifier, up to 64 bytes long.  Each variable must have a different name.
See <link linkend="Tokens">Tokens</link>.
</para>
<para>Some system variable names begin with &#8216;<literal>$</literal>&#8217;, but user-defined
variables&#8217; names may not begin with &#8216;<literal>$</literal>&#8217;.
</para>
<indexterm role="cp"><primary>&#8216;<literal>.</literal>&#8217;</primary></indexterm>
<indexterm role="cp"><primary>period</primary></indexterm>
<indexterm role="cp"><primary>variable names, ending with period</primary></indexterm>
<para>The final character in a variable name should not be &#8216;<literal>.</literal>&#8217;, because
such an identifier will be misinterpreted when it is the final token
on a line: <literal>FOO.</literal> is divided into two separate tokens,
&#8216;<literal>FOO</literal>&#8217; and &#8216;<literal>.</literal>&#8217;, indicating end-of-command.  See <link linkend="Tokens">Tokens</link>.
</para>
<indexterm role="cp"><primary>&#8216;<literal>_</literal>&#8217;</primary></indexterm>
<para>The final character in a variable name should not be &#8216;<literal>_</literal>&#8217;, because
some such identifiers are used for special purposes by PSPP
procedures.
</para>
<para>As with all PSPP identifiers, variable names are not case-sensitive.
PSPP capitalizes variable names on output the same way they were
capitalized at their point of definition in the input.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary>variables, type</primary></indexterm>
<indexterm role="cp"><primary>type of variables</primary></indexterm>
<emphasis role="bold">Type</emphasis>
</term><listitem><para>Numeric or string.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary>variables, width</primary></indexterm>
<indexterm role="cp"><primary>width of variables</primary></indexterm>
<emphasis role="bold">Width</emphasis>
</term><listitem><para>(string variables only) String variables with a width of 8 characters or
fewer are called <firstterm>short string variables</firstterm>.  Short string variables
may be used in a few contexts where <firstterm>long string variables</firstterm> (those
with widths greater than 8) are not allowed.
</para>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Position</emphasis>
</term><listitem><para>Variables in the dictionary are arranged in a specific order.
<literal>DISPLAY</literal> can be used to show this order: see <link linkend="DISPLAY">DISPLAY</link>.
</para>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Initialization</emphasis>
</term><listitem><para>Either reinitialized to 0 or spaces for each case, or left at its
existing value.  See <link linkend="LEAVE">LEAVE</link>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary>missing values</primary></indexterm>
<indexterm role="cp"><primary>values, missing</primary></indexterm>
<emphasis role="bold">Missing values</emphasis>
</term><listitem><para>Optionally, up to three values, or a range of values, or a specific
value plus a range, can be specified as <firstterm>user-missing values</firstterm>.
There is also a <firstterm>system-missing value</firstterm> that is assigned to an
observation when there is no other obvious value for that observation.
Observations with missing values are automatically excluded from
analyses.  User-missing values are actual data values, while the
system-missing value is not a value at all.  See <link linkend="Missing-Observations">Missing Observations</link>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary>variable labels</primary></indexterm>
<indexterm role="cp"><primary>labels, variable</primary></indexterm>
<emphasis role="bold">Variable label</emphasis>
</term><listitem><para>A string that describes the variable.  See <link linkend="VARIABLE-LABELS">VARIABLE LABELS</link>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary>value labels</primary></indexterm>
<indexterm role="cp"><primary>labels, value</primary></indexterm>
<emphasis role="bold">Value label</emphasis>
</term><listitem><para>Optionally, these associate each possible value of the variable with a
string.  See <link linkend="VALUE-LABELS">VALUE LABELS</link>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary>print format</primary></indexterm>
<emphasis role="bold">Print format</emphasis>
</term><listitem><para>Display width, format, and (for numeric variables) number of decimal
places.  This attribute does not affect how data are stored, just how
they are displayed.  Example: a width of 8, with 2 decimal places.
See <link linkend="Input-and-Output-Formats">Input and Output Formats</link>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary>write format</primary></indexterm>
<emphasis role="bold">Write format</emphasis>
</term><listitem><para>Similar to print format, but used by the <literal>WRITE</literal> command
(see <link linkend="WRITE">WRITE</link>).
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary>measurement level</primary></indexterm>
<emphasis role="bold">Measurement level</emphasis>
</term><listitem><anchor id="Measurement-Level"/><para>One of the following:
</para>
<variablelist><varlistentry><term>Nominal
</term><listitem><para>Each value of a nominal variable represents a distinct category.  The
possible categories are finite and often have value labels.  The order
of categories is not significant.  Political parties, US states, and
yes/no choices are nominal.  Numeric and string variables can be
nominal.
</para>
</listitem></varlistentry><varlistentry><term>Ordinal
</term><listitem><para>Ordinal variables also represent distinct categories, but their values
are arranged according to some natural order.  Likert scales, e.g.
from strongly disagree to strongly agree, are ordinal.  Data grouped
into ranges, e.g. age groups or income groups, are ordinal.  Both
numeric and string variables can be ordinal.  String values are
ordered alphabetically, so letter grades from A to F will work as
expected, but <literal>poor</literal>, <literal>satisfactory</literal>, <literal>excellent</literal> will
not.
</para>
</listitem></varlistentry><varlistentry><term>Scale
</term><listitem><para>Scale variables are ones for which differences and ratios are
meaningful.  These are often values which have a natural unit
attached, such as age in years, income in dollars, or distance in
miles.  Only numeric variables are scalar.
</para></listitem></varlistentry></variablelist>
<para>Variables created by <literal>COMPUTE</literal> and similar transformations,
obtained from external sources, etc., initially have an unknown
measurement level.  Any procedure that reads the data will then assign
a default measurement level.  PSPP can assign some defaults without
reading the data:
</para>
<itemizedlist><listitem><para>Nominal, if it&#8217;s a string variable.
</para>
</listitem><listitem><para>Nominal, if the variable has a WKDAY or MONTH print format.
</para>
</listitem><listitem><para>Scale, if the variable has a DOLLAR, CCA through CCE, or time or date
print format.
</para></listitem></itemizedlist>
<para>Otherwise, PSPP reads the data and decides based on its
distribution:
</para>
<itemizedlist><listitem><para>Nominal, if all observations are missing.
</para>
</listitem><listitem><para>Scale, if one or more valid observations are noninteger or negative.
</para>
</listitem><listitem><para>Scale, if no valid observation is less than 10.
</para>
</listitem><listitem><para>Scale, if the variable has 24 or more unique valid values.  The value
24 is the default and can be adjusted (see <link linkend="SET-SCALEMIN">SET SCALEMIN</link>).
</para></listitem></itemizedlist>
<para>Finally, if none of the above is true, PSPP assigns the variable a
nominal measurement level.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary>custom attributes</primary></indexterm>
<emphasis role="bold">Custom attributes</emphasis>
</term><listitem><para>User-defined associations between names and values.  See <link linkend="VARIABLE-ATTRIBUTE">VARIABLE
ATTRIBUTE</link>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary>variable role</primary></indexterm>
<emphasis role="bold">Role</emphasis>
</term><listitem><para>The intended role of a variable for use in dialog boxes in graphical
user interfaces.  See <link linkend="VARIABLE-ROLE">VARIABLE ROLE</link>.
</para></listitem></varlistentry></variablelist>
</sect2>
<sect2 label="6.7.2" id="System-Variables">
<title>Variables Automatically Defined by PSPP</title>
<indexterm role="cp"><primary>system variables</primary></indexterm>
<indexterm role="cp"><primary>variables, system</primary></indexterm>

<para>There are seven system variables.  These are not like ordinary
variables because system variables are not always stored.  They can be used only
in expressions.  These system variables, whose values and output formats
cannot be modified, are described below.
</para>
<variablelist><varlistentry><term><indexterm role="cp"><primary><literal>$CASENUM</literal></primary></indexterm>
<literal>$CASENUM</literal>
</term><listitem><para>Case number of the case at the moment.  This changes as cases are
shuffled around.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary><literal>$DATE</literal></primary></indexterm>
<literal>$DATE</literal>
</term><listitem><para>Date the PSPP process was started, in format A9, following the
pattern <literal>DD-MMM-YY</literal>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary><literal>$DATE11</literal></primary></indexterm>
<literal>$DATE11</literal>
</term><listitem><para>Date the PSPP process was started, in format A11, following the
pattern <literal>DD-MMM-YYYY</literal>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary><literal>$JDATE</literal></primary></indexterm>
<literal>$JDATE</literal>
</term><listitem><para>Number of days between 15 Oct 1582 and the time the PSPP process
was started.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary><literal>$LENGTH</literal></primary></indexterm>
<literal>$LENGTH</literal>
</term><listitem><para>Page length, in lines, in format F11.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary><literal>$SYSMIS</literal></primary></indexterm>
<literal>$SYSMIS</literal>
</term><listitem><para>System missing value, in format F1.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary><literal>$TIME</literal></primary></indexterm>
<literal>$TIME</literal>
</term><listitem><para>Number of seconds between midnight 14 Oct 1582 and the time the active dataset
was read, in format F20.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary><literal>$WIDTH</literal></primary></indexterm>
<literal>$WIDTH</literal>
</term><listitem><para>Page width, in characters, in format F3.
</para></listitem></varlistentry></variablelist>
</sect2>
<sect2 label="6.7.3" id="Sets-of-Variables">
<title>Lists of variable names</title>
<indexterm role="cp"><primary><literal>TO</literal> convention</primary></indexterm>
<indexterm role="cp"><primary>convention, <literal>TO</literal></primary></indexterm>

<para>To refer to a set of variables, list their names one after another.
Optionally, their names may be separated by commas.  To include a
range of variables from the dictionary in the list, write the name of
the first and last variable in the range, separated by <literal>TO</literal>.  For
instance, if the dictionary contains six variables with the names
<literal>ID</literal>, <literal>X1</literal>, <literal>X2</literal>, <literal>GOAL</literal>, <literal>MET</literal>, and
<literal>NEXTGOAL</literal>, in that order, then <literal>X2 TO MET</literal> would include
variables <literal>X2</literal>, <literal>GOAL</literal>, and <literal>MET</literal>.
</para>
<para>Commands that define variables, such as <literal>DATA LIST</literal>, give
<literal>TO</literal> an alternate meaning.  With these commands, <literal>TO</literal> define
sequences of variables whose names end in consecutive integers.  The
syntax is two identifiers that begin with the same root and end with
numbers, separated by <literal>TO</literal>.  The syntax <literal>X1 TO X5</literal> defines 5
variables, named <literal>X1</literal>, <literal>X2</literal>, <literal>X3</literal>, <literal>X4</literal>, and
<literal>X5</literal>.  The syntax <literal>ITEM0008 TO ITEM0013</literal> defines 6
variables, named <literal>ITEM0008</literal>, <literal>ITEM0009</literal>, <literal>ITEM0010</literal>,
<literal>ITEM0011</literal>, <literal>ITEM0012</literal>, and <literal>ITEM00013</literal>.  The syntaxes
<literal>QUES001 TO QUES9</literal> and <literal>QUES6 TO QUES3</literal> are invalid.
</para>
<para>After a set of variables has been defined with <literal>DATA LIST</literal> or
another command with this method, the same set can be referenced on
later commands using the same syntax.
</para>
</sect2>
<sect2 label="6.7.4" id="Input-and-Output-Formats">
<title>Input and Output Formats</title>

<indexterm role="cp"><primary>formats</primary></indexterm>
<para>An <firstterm>input format</firstterm> describes how to interpret the contents of an
input field as a number or a string.  It might specify that the field
contains an ordinary decimal number, a time or date, a number in binary
or hexadecimal notation, or one of several other notations.  Input
formats are used by commands such as <literal>DATA LIST</literal> that read data or
syntax files into the PSPP active dataset.
</para>
<para>Every input format corresponds to a default <firstterm>output format</firstterm> that
specifies the formatting used when the value is output later.  It is
always possible to explicitly specify an output format that resembles
the input format.  Usually, this is the default, but in cases where the
input format is unfriendly to human readability, such as binary or
hexadecimal formats, the default output format is an easier-to-read
decimal format.
</para>
<para>Every variable has two output formats, called its <firstterm>print format</firstterm> and
<firstterm>write format</firstterm>.  Print formats are used in most output contexts;
write formats are used only by <literal>WRITE</literal> (see <link linkend="WRITE">WRITE</link>).  Newly
created variables have identical print and write formats, and
<literal>FORMATS</literal>, the most commonly used command for changing formats
(see <link linkend="FORMATS">FORMATS</link>), sets both of them to the same value as well.  Thus,
most of the time, the distinction between print and write formats is
unimportant.
</para>
<para>Input and output formats are specified to PSPP with
a <firstterm>format specification</firstterm> of the
form <literal><replaceable>TYPE</replaceable><replaceable>w</replaceable></literal> or <literal>TYPE<replaceable>w</replaceable>.<replaceable>d</replaceable></literal>, where
<replaceable>TYPE</replaceable> is one of the format types described later, <replaceable>w</replaceable> is a
field width measured in columns, and <replaceable>d</replaceable> is an optional number of
decimal places.  If <replaceable>d</replaceable> is omitted, a value of 0 is assumed.  Some
formats do not allow a nonzero <replaceable>d</replaceable> to be specified.
</para>
<para>The following sections describe the input and output formats supported
by PSPP.
</para>

<sect3 label="6.7.4.1" id="Basic-Numeric-Formats">
<title>Basic Numeric Formats</title>

<indexterm role="cp"><primary>numeric formats</primary></indexterm>
<para>The basic numeric formats are used for input and output of real numbers
in standard or scientific notation.  The following table shows an
example of how each format displays positive and negative numbers with
the default decimal point setting:
</para>
<informaltable><tgroup cols="3"><colspec colwidth="10*"></colspec><colspec colwidth="10*"></colspec><colspec colwidth="10*"></colspec><thead><row><entry><para>Format </para></entry><entry><para><literal>&#160;3141.59</literal>   </para></entry><entry><para><literal>-3141.59</literal>
</para></entry></row></thead><tbody><row><entry><para>F8.2       </para></entry><entry><para><literal>&#160;3141.59</literal>   </para></entry><entry><para><literal>-3141.59</literal>
</para></entry></row><row><entry><para>COMMA9.2   </para></entry><entry><para><literal>&#160;3,141.59</literal>  </para></entry><entry><para><literal>-3,141.59</literal>
</para></entry></row><row><entry><para>DOT9.2     </para></entry><entry><para><literal>&#160;3.141,59</literal>  </para></entry><entry><para><literal>-3.141,59</literal>
</para></entry></row><row><entry><para>DOLLAR10.2 </para></entry><entry><para><literal>&#160;$3,141.59</literal> </para></entry><entry><para><literal>-$3,141.59</literal>
</para></entry></row><row><entry><para>PCT9.2     </para></entry><entry><para><literal>&#160;3141.59%</literal>  </para></entry><entry><para><literal>-3141.59%</literal>
</para></entry></row><row><entry><para>E8.1       </para></entry><entry><para><literal>&#160;3.1E+003</literal>  </para></entry><entry><para><literal>-3.1E+003</literal>
</para></entry></row></tbody></tgroup></informaltable>
<para>On output, numbers in F format are expressed in standard decimal
notation with the requested number of decimal places.  The other formats
output some variation on this style:
</para>
<itemizedlist><listitem><para>Numbers in COMMA format are additionally grouped every three digits by
inserting a grouping character.  The grouping character is ordinarily a
comma, but it can be changed to a period (see <link linkend="SET-DECIMAL">SET DECIMAL</link>).
</para>
</listitem><listitem><para>DOT format is like COMMA format, but it interchanges the role of the
decimal point and grouping characters.  That is, the current grouping
character is used as a decimal point and vice versa.
</para>
</listitem><listitem><para>DOLLAR format is like COMMA format, but it prefixes the number with
&#8216;<literal>$</literal>&#8217;.
</para>
</listitem><listitem><para>PCT format is like F format, but adds &#8216;<literal>%</literal>&#8217; after the number.
</para>
</listitem><listitem><para>The E format always produces output in scientific notation.
</para></listitem></itemizedlist>
<para>On input, the basic numeric formats accept positive and numbers in
standard decimal notation or scientific notation.  Leading and trailing
spaces are allowed.  An empty or all-spaces field, or one that contains
only a single period, is treated as the system missing value.
</para>
<para>In scientific notation, the exponent may be introduced by a sign
(&#8216;<literal>+</literal>&#8217; or &#8216;<literal>-</literal>&#8217;), or by one of the letters &#8216;<literal>e</literal>&#8217; or &#8216;<literal>d</literal>&#8217;
(in uppercase or lowercase), or by a letter followed by a sign.  A
single space may follow the letter or the sign or both.
</para>
<para>On fixed-format <literal>DATA LIST</literal> (see <link linkend="DATA-LIST-FIXED">DATA LIST FIXED</link>) and in a few
other contexts, decimals are implied when the field does not contain a
decimal point.  In F6.5 format, for example, the field <literal>314159</literal> is
taken as the value 3.14159 with implied decimals.  Decimals are never
implied if an explicit decimal point is present or if scientific
notation is used.
</para>
<para>E and F formats accept the basic syntax already described.  The other
formats allow some additional variations:
</para>
<itemizedlist><listitem><para>COMMA, DOLLAR, and DOT formats ignore grouping characters within the
integer part of the input field.  The identity of the grouping
character depends on the format.
</para>
</listitem><listitem><para>DOLLAR format allows a dollar sign to precede the number.  In a negative
number, the dollar sign may precede or follow the minus sign.
</para>
</listitem><listitem><para>PCT format allows a percent sign to follow the number.
</para></listitem></itemizedlist>
<para>All of the basic number formats have a maximum field width of 40 and
accept no more than 16 decimal places, on both input and output.  Some
additional restrictions apply:
</para>
<itemizedlist><listitem><para>As input formats, the basic numeric formats allow no more decimal places
than the field width.  As output formats, the field width must be
greater than the number of decimal places; that is, large enough to
allow for a decimal point and the number of requested decimal places.
DOLLAR and PCT formats must allow an additional column for &#8216;<literal>$</literal>&#8217; or
&#8216;<literal>%</literal>&#8217;.
</para>
</listitem><listitem><para>The default output format for a given input format increases the field
width enough to make room for optional input characters.  If an input
format calls for decimal places, the width is increased by 1 to make
room for an implied decimal point.  COMMA, DOT, and DOLLAR formats also
increase the output width to make room for grouping characters.  DOLLAR
and PCT further increase the output field width by 1 to make room for
&#8216;<literal>$</literal>&#8217; or &#8216;<literal>%</literal>&#8217;.  The increased output width is capped at 40, the
maximum field width.
</para>
</listitem><listitem><para>The E format is exceptional.  For output, E format has a minimum width
of 7 plus the number of decimal places.  The default output format for
an E input format is an E format with at least 3 decimal places and
thus a minimum width of 10.
</para></listitem></itemizedlist>
<para>More details of basic numeric output formatting are given below:
</para>
<itemizedlist><listitem><para>Output rounds to nearest, with ties rounded away from zero.  Thus, 2.5
is output as <literal>3</literal> in F1.0 format, and -1.125 as <literal>-1.13</literal> in F5.1
format.
</para>
</listitem><listitem><para>The system-missing value is output as a period in a field of spaces,
placed in the decimal point&#8217;s position, or in the rightmost column if no
decimal places are requested.  A period is used even if the decimal
point character is a comma.
</para>
</listitem><listitem><para>A number that does not fill its field is right-justified within the
field.
</para>
</listitem><listitem><para>A number is too large for its field causes decimal places to be dropped
to make room.  If dropping decimals does not make enough room,
scientific notation is used if the field is wide enough.  If a number
does not fit in the field, even in scientific notation, the overflow is
indicated by filling the field with asterisks (&#8216;<literal>*</literal>&#8217;).
</para>
</listitem><listitem><para>COMMA, DOT, and DOLLAR formats insert grouping characters only if space
is available for all of them.  Grouping characters are never inserted
when all decimal places must be dropped.  Thus, 1234.56 in COMMA5.2
format is output as &#8216;<literal>&#160;1235</literal>&#8217; without a comma, even though there
is room for one, because all decimal places were dropped.
</para>
</listitem><listitem><para>DOLLAR or PCT format drop the &#8216;<literal>$</literal>&#8217; or &#8216;<literal>%</literal>&#8217; only if the number
would not fit at all without it.  Scientific notation with &#8216;<literal>$</literal>&#8217; or
&#8216;<literal>%</literal>&#8217; is preferred to ordinary decimal notation without it.
</para>
</listitem><listitem><para>Except in scientific notation, a decimal point is included only when
it is followed by a digit.  If the integer part of the number being
output is 0, and a decimal point is included, then PSPP ordinarily
drops the zero before the decimal point.  However, in <literal>F</literal>,
<literal>COMMA</literal>, or <literal>DOT</literal> formats, PSPP keeps the zero if
<literal>SET LEADZERO</literal> is set to <literal>ON</literal> (see <link linkend="SET-LEADZERO">SET LEADZERO</link>).
</para>
<para>In scientific notation, the number always includes a decimal point,
even if it is not followed by a digit.
</para>
</listitem><listitem><para>A negative number includes a minus sign only in the presence of a
nonzero digit: -0.01 is output as &#8216;<literal>-.01</literal>&#8217; in F4.2 format but as
&#8216;<literal>&#160;&#160;.0</literal>&#8217; in F4.1 format.  Thus, a &#8220;negative zero&#8221; never
includes a minus sign.
</para>
</listitem><listitem><para>In negative numbers output in DOLLAR format, the dollar sign follows the
negative sign.  Thus, -9.99 in DOLLAR6.2 format is output as
<literal>-$9.99</literal>.
</para>
</listitem><listitem><para>In scientific notation, the exponent is output as &#8216;<literal>E</literal>&#8217; followed by
&#8216;<literal>+</literal>&#8217; or &#8216;<literal>-</literal>&#8217; and exactly three digits.  Numbers with magnitude
less than 10**-999 or larger than 10**999 are not supported by most
computers, but if they are supported then their output is considered
to overflow the field and they are output as asterisks.
</para>
</listitem><listitem><para>On most computers, no more than 15 decimal digits are significant in
output, even if more are printed.  In any case, output precision cannot
be any higher than input precision; few data sets are accurate to 15
digits of precision.  Unavoidable loss of precision in intermediate
calculations may also reduce precision of output.
</para>
</listitem><listitem><para>Special values such as infinities and &#8220;not a number&#8221; values are
usually converted to the system-missing value before printing.  In a few
circumstances, these values are output directly.  In fields of width 3
or greater, special values are output as however many characters
fit from <literal>+Infinity</literal> or <literal>-Infinity</literal> for infinities, from
<literal>NaN</literal> for &#8220;not a number,&#8221; or from <literal>Unknown</literal> for other values
(if any are supported by the system).  In fields under 3 columns wide,
special values are output as asterisks.
</para></listitem></itemizedlist>
</sect3>
<sect3 label="6.7.4.2" id="Custom-Currency-Formats">
<title>Custom Currency Formats</title>

<indexterm role="cp"><primary>currency formats</primary></indexterm>
<para>The custom currency formats are closely related to the basic numeric
formats, but they allow users to customize the output format.  The
SET command configures custom currency formats, using the syntax
</para><literallayout>SET CC<replaceable>x</replaceable>=<literal>&quot;</literal><replaceable>string</replaceable><literal>&quot;</literal>.
</literallayout><para>where <replaceable>x</replaceable> is A, B, C, D, or E, and <replaceable>string</replaceable> is no more than 16
characters long.
</para>
<para><replaceable>string</replaceable> must contain exactly three commas or exactly three periods
(but not both), except that a single quote character may be used to
&#8220;escape&#8221; a following comma, period, or single quote.  If three commas
are used, commas are used for grouping in output, and a period
is used as the decimal point.  Uses of periods reverses these roles.
</para>
<para>The commas or periods divide <replaceable>string</replaceable> into four fields, called the
<firstterm>negative prefix</firstterm>, <firstterm>prefix</firstterm>, <firstterm>suffix</firstterm>, and <firstterm>negative
suffix</firstterm>, respectively.  The prefix and suffix are added to output
whenever space is available.  The negative prefix and negative suffix
are always added to a negative number when the output includes a nonzero
digit.
</para>
<para>The following syntax shows how custom currency formats could be used to
reproduce basic numeric formats:
</para>
<screen>SET CCA=&quot;-,,,&quot;.  /* Same as COMMA.
SET CCB=&quot;-...&quot;.  /* Same as DOT.
SET CCC=&quot;-,$,,&quot;. /* Same as DOLLAR.
SET CCD=&quot;-,,%,&quot;. /* Like PCT, but groups with commas.
</screen>
<para>Here are some more examples of custom currency formats.  The final
example shows how to use a single quote to escape a delimiter:
</para>
<screen>SET CCA=&quot;,EUR,,-&quot;.   /* Euro.
SET CCB=&quot;(,USD ,,)&quot;. /* US dollar.
SET CCC=&quot;-.R$..&quot;.    /* Brazilian real.
SET CCD=&quot;-,, NIS,&quot;.  /* Israel shekel.
SET CCE=&quot;-.Rp'. ..&quot;. /* Indonesia Rupiah.
</screen>
<para>These formats would yield the following output:
</para>
<informaltable><tgroup cols="3"><colspec colwidth="7*"></colspec><colspec colwidth="14*"></colspec><colspec colwidth="14*"></colspec><thead><row><entry><para>Format </para></entry><entry><para><literal>&#160;3145.59</literal>         </para></entry><entry><para><literal>-3145.59</literal>
</para></entry></row></thead><tbody><row><entry><para>CCA12.2 </para></entry><entry><para><literal>&#160;EUR3,145.59</literal>        </para></entry><entry><para><literal>EUR3,145.59-</literal>
</para></entry></row><row><entry><para>CCB14.2 </para></entry><entry><para><literal>&#160;&#160;USD 3,145.59</literal> </para></entry><entry><para><literal>(USD 3,145.59)</literal>
</para></entry></row><row><entry><para>CCC11.2 </para></entry><entry><para><literal>&#160;R$3.145,59</literal>         </para></entry><entry><para><literal>-R$3.145,59</literal>
</para></entry></row><row><entry><para>CCD13.2 </para></entry><entry><para><literal>&#160;3,145.59 NIS</literal>       </para></entry><entry><para><literal>-3,145.59 NIS</literal>
</para></entry></row><row><entry><para>CCE10.0 </para></entry><entry><para><literal>&#160;Rp. 3.146</literal>          </para></entry><entry><para><literal>-Rp. 3.146</literal>
</para></entry></row></tbody></tgroup></informaltable>
<para>The default for all the custom currency formats is &#8216;<literal>-,,,</literal>&#8217;,
equivalent to COMMA format.
</para>
</sect3>
<sect3 label="6.7.4.3" id="Legacy-Numeric-Formats">
<title>Legacy Numeric Formats</title>

<para>The N and Z numeric formats provide compatibility with legacy file
formats.  They have much in common:
</para>
<itemizedlist><listitem><para>Output is rounded to the nearest representable value, with ties rounded
away from zero.
</para>
</listitem><listitem><para>Numbers too large to display are output as a field filled with asterisks
(&#8216;<literal>*</literal>&#8217;).
</para>
</listitem><listitem><para>The decimal point is always implicitly the specified number of digits
from the right edge of the field, except that Z format input allows an
explicit decimal point.
</para>
</listitem><listitem><para>Scientific notation may not be used.
</para>
</listitem><listitem><para>The system-missing value is output as a period in a field of spaces.
The period is placed just to the right of the implied decimal point in
Z format, or at the right end in N format or in Z format if no decimal
places are requested.  A period is used even if the decimal point
character is a comma.
</para>
</listitem><listitem><para>Field width may range from 1 to 40.  Decimal places may range from 0 up
to the field width, to a maximum of 16.
</para>
</listitem><listitem><para>When a legacy numeric format used for input is converted to an output
format, it is changed into the equivalent F format.  The field width is
increased by 1 if any decimal places are specified, to make room for a
decimal point.  For Z format, the field width is increased by 1 more
column, to make room for a negative sign.  The output field width is
capped at 40 columns.
</para></listitem></itemizedlist>
<bridgehead renderas="sect3">N Format</bridgehead>

<para>The N format supports input and output of fields that contain only
digits.  On input, leading or trailing spaces, a decimal point, or any
other non-digit character causes the field to be read as the
system-missing value.  As a special exception, an N format used on
<literal>DATA LIST FREE</literal> or <literal>DATA LIST LIST</literal> is treated as the
equivalent F format.
</para>
<para>On output, N pads the field on the left with zeros.  Negative numbers
are output like the system-missing value.
</para>
<bridgehead renderas="sect3">Z Format</bridgehead>

<para>The Z format is a &#8220;zoned decimal&#8221; format used on IBM mainframes.  Z
format encodes the sign as part of the final digit, which must be one of
the following:
</para><screen>0123456789
{ABCDEFGHI
}JKLMNOPQR
</screen><para>where the characters in each row represent digits 0 through 9 in order.
Characters in the first two rows indicate a positive sign; those in the
third indicate a negative sign.
</para>
<para>On output, Z fields are padded on the left with spaces.  On input,
leading and trailing spaces are ignored.  Any character in an input
field other than spaces, the digit characters above, and &#8216;<literal>.</literal>&#8217; causes
the field to be read as system-missing.
</para>
<para>The decimal point character for input and output is always &#8216;<literal>.</literal>&#8217;,
even if the decimal point character is a comma (see <link linkend="SET-DECIMAL">SET DECIMAL</link>).
</para>
<para>Nonzero, negative values output in Z format are marked as negative even
when no nonzero digits are output.  For example, -0.2 is output in Z1.0
format as &#8216;<literal>J</literal>&#8217;.  The &#8220;negative zero&#8221; value supported by most
machines is output as positive.
</para>
</sect3>
<sect3 label="6.7.4.4" id="Binary-and-Hexadecimal-Numeric-Formats">
<title>Binary and Hexadecimal Numeric Formats</title>

<indexterm role="cp"><primary>binary formats</primary></indexterm>
<indexterm role="cp"><primary>hexadecimal formats</primary></indexterm>
<para>The binary and hexadecimal formats are primarily designed for
compatibility with existing machine formats, not for human readability.
All of them therefore have a F format as default output format.  Some of
these formats are only portable between machines with compatible byte
ordering (endianness) or floating-point format.
</para>
<para>Binary formats use byte values that in text files are interpreted as
special control functions, such as carriage return and line feed.  Thus,
data in binary formats should not be included in syntax files or read
from data files with variable-length records, such as ordinary text
files.  They may be read from or written to data files with fixed-length
records.  See <link linkend="FILE-HANDLE">FILE HANDLE</link>, for information on working with
fixed-length records.
</para>
<bridgehead renderas="sect3">P and PK Formats</bridgehead>

<para>These are binary-coded decimal formats, in which every byte (except the
last, in P format) represents two decimal digits.  The most-significant
4 bits of the first byte is the most-significant decimal digit, the
least-significant 4 bits of the first byte is the next decimal digit,
and so on.
</para>
<para>In P format, the most-significant 4 bits of the last byte are the
least-significant decimal digit.  The least-significant 4 bits represent
the sign: decimal 15 indicates a negative value, decimal 13 indicates a
positive value.
</para>
<para>Numbers are rounded downward on output.  The system-missing value and
numbers outside representable range are output as zero.
</para>
<para>The maximum field width is 16.  Decimal places may range from 0 up to
the number of decimal digits represented by the field.
</para>
<para>The default output format is an F format with twice the input field
width, plus one column for a decimal point (if decimal places were
requested).
</para>
<bridgehead renderas="sect3">IB and PIB Formats</bridgehead>

<para>These are integer binary formats.  IB reads and writes 2&#8217;s complement
binary integers, and PIB reads and writes unsigned binary integers.  The
byte ordering is by default the host machine&#8217;s, but SET RIB may be used
to select a specific byte ordering for reading (see <link linkend="SET-RIB">SET RIB</link>) and
SET WIB, similarly, for writing (see <link linkend="SET-WIB">SET WIB</link>).
</para>
<para>The maximum field width is 8.  Decimal places may range from 0 up to the
number of decimal digits in the largest value representable in the field
width.
</para>
<para>The default output format is an F format whose width is the number of
decimal digits in the largest value representable in the field width,
plus 1 if the format has decimal places.
</para>
<bridgehead renderas="sect3">RB Format</bridgehead>

<para>This is a binary format for real numbers.  By default it reads and
writes the host machine&#8217;s floating-point format, but SET RRB may be
used to select an alternate floating-point format for reading
(see <link linkend="SET-RRB">SET RRB</link>) and SET WRB, similarly, for writing (see <link linkend="SET-WRB">SET
WRB</link>).
</para>
<para>The recommended field width depends on the floating-point format.
NATIVE (the default format), IDL, IDB, VD, VG, and ZL formats should use
a field width of 8.  ISL, ISB, VF, and ZS formats should use a field
width of 4.  Other field widths do not produce useful results.  The
maximum field width is 8.  No decimal places may be specified.
</para>
<para>The default output format is F8.2.
</para>
<bridgehead renderas="sect3">PIBHEX and RBHEX Formats</bridgehead>

<para>These are hexadecimal formats, for reading and writing binary formats
where each byte has been recoded as a pair of hexadecimal digits.
</para>
<para>A hexadecimal field consists solely of hexadecimal digits
&#8216;<literal>0</literal>&#8217;&#8230;&#8216;<literal>9</literal>&#8217; and &#8216;<literal>A</literal>&#8217;&#8230;&#8216;<literal>F</literal>&#8217;.  Uppercase and
lowercase are accepted on input; output is in uppercase.
</para>
<para>Other than the hexadecimal representation, these formats are equivalent
to PIB and RB formats, respectively.  However, bytes in PIBHEX format
are always ordered with the most-significant byte first (big-endian
order), regardless of the host machine&#8217;s native byte order or PSPP
settings.
</para>
<para>Field widths must be even and between 2 and 16.  RBHEX format allows no
decimal places; PIBHEX allows as many decimal places as a PIB format
with half the given width.
</para>
</sect3>
<sect3 label="6.7.4.5" id="Time-and-Date-Formats">
<title>Time and Date Formats</title>

<indexterm role="cp"><primary>time formats</primary></indexterm>
<indexterm role="cp"><primary>date formats</primary></indexterm>
<para>In PSPP, a <firstterm>time</firstterm> is an interval.  The time formats translate
between human-friendly descriptions of time intervals and PSPP&#8217;s
internal representation of time intervals, which is simply the number of
seconds in the interval.  PSPP has three time formats:
</para>
<informaltable><tgroup cols="3"><colspec colwidth="11*"></colspec><colspec colwidth="23*"></colspec><colspec colwidth="23*"></colspec><thead><row><entry><para>Time Format </para></entry><entry><para>Template                  </para></entry><entry><para>Example
</para></entry></row></thead><tbody><row><entry><para>MTIME    </para></entry><entry><para><literal>MM:SS.ss</literal>             </para></entry><entry><para><literal>91:17.01</literal>
</para></entry></row><row><entry><para>TIME     </para></entry><entry><para><literal>hh:MM:SS.ss</literal>          </para></entry><entry><para><literal>01:31:17.01</literal>
</para></entry></row><row><entry><para>DTIME    </para></entry><entry><para><literal>DD HH:MM:SS.ss</literal>       </para></entry><entry><para><literal>00 04:31:17.01</literal>
</para></entry></row></tbody></tgroup></informaltable>
<para>A <firstterm>date</firstterm> is a moment in the past or the future.  Internally, PSPP
represents a date as the number of seconds since the <firstterm>epoch</firstterm>,
midnight, Oct. 14, 1582.  The date formats translate between
human-readable dates and PSPP&#8217;s numeric representation of dates and
times.  PSPP has several date formats:
</para>
<informaltable><tgroup cols="3"><colspec colwidth="11*"></colspec><colspec colwidth="23*"></colspec><colspec colwidth="23*"></colspec><thead><row><entry><para>Date Format </para></entry><entry><para>Template                  </para></entry><entry><para>Example
</para></entry></row></thead><tbody><row><entry><para>DATE     </para></entry><entry><para><literal>dd-mmm-yyyy</literal>          </para></entry><entry><para><literal>01-OCT-1978</literal>
</para></entry></row><row><entry><para>ADATE    </para></entry><entry><para><literal>mm/dd/yyyy</literal>           </para></entry><entry><para><literal>10/01/1978</literal>
</para></entry></row><row><entry><para>EDATE    </para></entry><entry><para><literal>dd.mm.yyyy</literal>           </para></entry><entry><para><literal>01.10.1978</literal>
</para></entry></row><row><entry><para>JDATE    </para></entry><entry><para><literal>yyyyjjj</literal>              </para></entry><entry><para><literal>1978274</literal>
</para></entry></row><row><entry><para>SDATE    </para></entry><entry><para><literal>yyyy/mm/dd</literal>           </para></entry><entry><para><literal>1978/10/01</literal>
</para></entry></row><row><entry><para>QYR      </para></entry><entry><para><literal>q Q yyyy</literal>             </para></entry><entry><para><literal>3 Q 1978</literal>
</para></entry></row><row><entry><para>MOYR     </para></entry><entry><para><literal>mmm yyyy</literal>             </para></entry><entry><para><literal>OCT 1978</literal>
</para></entry></row><row><entry><para>WKYR     </para></entry><entry><para><literal>ww WK yyyy</literal>           </para></entry><entry><para><literal>40 WK 1978</literal>
</para></entry></row><row><entry><para>DATETIME </para></entry><entry><para><literal>dd-mmm-yyyy HH:MM:SS.ss</literal> </para></entry><entry><para><literal>01-OCT-1978 04:31:17.01</literal>
</para></entry></row><row><entry><para>YMDHMS   </para></entry><entry><para><literal>yyyy-mm-dd HH:MM:SS.ss</literal> </para></entry><entry><para><literal>1978-01-OCT 04:31:17.01</literal>
</para></entry></row></tbody></tgroup></informaltable>
<para>The templates in the preceding tables describe how the time and date
formats are input and output:
</para>
<variablelist><varlistentry><term><literal>dd</literal>
</term><listitem><para>Day of month, from 1 to 31.  Always output as two digits.
</para>
</listitem></varlistentry><varlistentry><term><literal>mm</literal>
</term><term><literal>mmm</literal>
</term><listitem><para>Month.  In output, <literal>mm</literal> is output as two digits, <literal>mmm</literal> as the
first three letters of an English month name (January, February,
&#8230;).  In input, both of these formats, plus Roman numerals, are
accepted.
</para>
</listitem></varlistentry><varlistentry><term><literal>yyyy</literal>
</term><listitem><para>Year.  In output, DATETIME and YMDHMS always produce 4-digit years;
other formats can produce a 2- or 4-digit year.  The century assumed
for 2-digit years depends on the EPOCH setting (see <link linkend="SET-EPOCH">SET EPOCH</link>).
In output, a year outside the epoch causes the whole field to be
filled with asterisks (&#8216;<literal>*</literal>&#8217;).
</para>
</listitem></varlistentry><varlistentry><term><literal>jjj</literal>
</term><listitem><para>Day of year (Julian day), from 1 to 366.  This is exactly three digits
giving the count of days from the start of the year.  January 1 is
considered day 1.
</para>
</listitem></varlistentry><varlistentry><term><literal>q</literal>
</term><listitem><para>Quarter of year, from 1 to 4.  Quarters start on January 1, April 1,
July 1, and October 1.
</para>
</listitem></varlistentry><varlistentry><term><literal>ww</literal>
</term><listitem><para>Week of year, from 1 to 53.  Output as exactly two digits.  January 1 is
the first day of week 1.
</para>
</listitem></varlistentry><varlistentry><term><literal>DD</literal>
</term><listitem><para>Count of days, which may be positive or negative.  Output as at least
two digits.
</para>
</listitem></varlistentry><varlistentry><term><literal>hh</literal>
</term><listitem><para>Count of hours, which may be positive or negative.  Output as at least
two digits.
</para>
</listitem></varlistentry><varlistentry><term><literal>HH</literal>
</term><listitem><para>Hour of day, from 0 to 23.  Output as exactly two digits.
</para>
</listitem></varlistentry><varlistentry><term><literal>MM</literal>
</term><listitem><para>In MTIME, count of minutes, which may be positive or negative.  Output
as at least two digits.
</para>
<para>In other formats, minute of hour, from 0 to 59.  Output as exactly two
digits.
</para>
</listitem></varlistentry><varlistentry><term><literal>SS.ss</literal>
</term><listitem><para>Seconds within minute, from 0 to 59.  The integer part is output as
exactly two digits.  On output, seconds and fractional seconds may or
may not be included, depending on field width and decimal places.  On
input, seconds and fractional seconds are optional.  The DECIMAL setting
controls the character accepted and displayed as the decimal point
(see <link linkend="SET-DECIMAL">SET DECIMAL</link>).
</para></listitem></varlistentry></variablelist>
<para>For output, the date and time formats use the delimiters indicated in
the table.  For input, date components may be separated by spaces or by
one of the characters &#8216;<literal>-</literal>&#8217;, &#8216;<literal>/</literal>&#8217;, &#8216;<literal>.</literal>&#8217;, or &#8216;<literal>,</literal>&#8217;, and
time components may be separated by spaces or &#8216;<literal>:</literal>&#8217;.  On
input, the &#8216;<literal>Q</literal>&#8217; separating quarter from year and the &#8216;<literal>WK</literal>&#8217;
separating week from year may be uppercase or lowercase, and the spaces
around them are optional.
</para>
<para>On input, all time and date formats accept any amount of leading and
trailing white space.
</para>
<para>The maximum width for time and date formats is 40 columns.  Minimum
input and output width for each of the time and date formats is shown
below:
</para>
<informaltable><tgroup cols="4"><colspec colwidth="8*"></colspec><colspec colwidth="16*"></colspec><colspec colwidth="17*"></colspec><colspec colwidth="12*"></colspec><thead><row><entry><para>Format </para></entry><entry><para>Min. Input Width </para></entry><entry><para>Min. Output Width </para></entry><entry><para>Option
</para></entry></row></thead><tbody><row><entry><para>DATE </para></entry><entry><para>8 </para></entry><entry><para>9 </para></entry><entry><para>4-digit year
</para></entry></row><row><entry><para>ADATE </para></entry><entry><para>8 </para></entry><entry><para>8 </para></entry><entry><para>4-digit year
</para></entry></row><row><entry><para>EDATE </para></entry><entry><para>8 </para></entry><entry><para>8 </para></entry><entry><para>4-digit year
</para></entry></row><row><entry><para>JDATE </para></entry><entry><para>5 </para></entry><entry><para>5 </para></entry><entry><para>4-digit year
</para></entry></row><row><entry><para>SDATE </para></entry><entry><para>8 </para></entry><entry><para>8 </para></entry><entry><para>4-digit year
</para></entry></row><row><entry><para>QYR </para></entry><entry><para>4 </para></entry><entry><para>6 </para></entry><entry><para>4-digit year
</para></entry></row><row><entry><para>MOYR </para></entry><entry><para>6 </para></entry><entry><para>6 </para></entry><entry><para>4-digit year
</para></entry></row><row><entry><para>WKYR </para></entry><entry><para>6 </para></entry><entry><para>8 </para></entry><entry><para>4-digit year
</para></entry></row><row><entry><para>DATETIME </para></entry><entry><para>17 </para></entry><entry><para>17 </para></entry><entry><para>seconds
</para></entry></row><row><entry><para>YMDHMS </para></entry><entry><para>12 </para></entry><entry><para>16 </para></entry><entry><para>seconds
</para></entry></row><row><entry><para>MTIME </para></entry><entry><para>4 </para></entry><entry><para>5
</para></entry></row><row><entry><para>TIME </para></entry><entry><para>5 </para></entry><entry><para>5 </para></entry><entry><para>seconds
</para></entry></row><row><entry><para>DTIME </para></entry><entry><para>8 </para></entry><entry><para>8 </para></entry><entry><para>seconds
</para></entry></row></tbody></tgroup></informaltable><para>In the table, &#8220;Option&#8221; describes what increased output width enables:
</para>
<variablelist><varlistentry><term>4-digit year
</term><listitem><para>A field 2 columns wider than the minimum includes a 4-digit year.
(DATETIME and YMDHMS formats always include a 4-digit year.)
</para>
</listitem></varlistentry><varlistentry><term>seconds
</term><listitem><para>A field 3 columns wider than the minimum includes seconds as well as
minutes.  A field 5 columns wider than minimum, or more, can also
include a decimal point and fractional seconds (but no more than allowed
by the format&#8217;s decimal places).
</para></listitem></varlistentry></variablelist>
<para>For the time and date formats, the default output format is the same as
the input format, except that PSPP increases the field width, if
necessary, to the minimum allowed for output.
</para>
<para>Time or dates narrower than the field width are right-justified within
the field.
</para>
<para>When a time or date exceeds the field width, characters are trimmed from
the end until it fits.  This can occur in an unusual situation, <emphasis>e.g.</emphasis>
with a year greater than 9999 (which adds an extra digit), or for a
negative value on MTIME, TIME, or DTIME (which adds a leading minus sign).
</para>
<!-- What about out-of-range values? -->

<para>The system-missing value is output as a period at the right end of the
field.
</para>
</sect3>
<sect3 label="6.7.4.6" id="Date-Component-Formats">
<title>Date Component Formats</title>

<para>The WKDAY and MONTH formats provide input and output for the names of
weekdays and months, respectively.
</para>
<para>On output, these formats convert a number between 1 and 7, for WKDAY, or
between 1 and 12, for MONTH, into the English name of a day or month,
respectively.  If the name is longer than the field, it is trimmed to
fit.  If the name is shorter than the field, it is padded on the right
with spaces.  Values outside the valid range, and the system-missing
value, are output as all spaces.
</para>
<para>On input, English weekday or month names (in uppercase or lowercase) are
converted back to their corresponding numbers.  Weekday and month names
may be abbreviated to their first 2 or 3 letters, respectively.
</para>
<para>The field width may range from 2 to 40, for WKDAY, or from 3 to 40, for
MONTH.  No decimal places are allowed.
</para>
<para>The default output format is the same as the input format.
</para>
</sect3>
<sect3 label="6.7.4.7" id="String-Formats">
<title>String Formats</title>

<indexterm role="cp"><primary>string formats</primary></indexterm>
<para>The A and AHEX formats are the only ones that may be assigned to string
variables.  Neither format allows any decimal places.
</para>
<para>In A format, the entire field is treated as a string value.  The field
width may range from 1 to 32,767, the maximum string width.  The default
output format is the same as the input format.
</para>
<para>In AHEX format, the field is composed of characters in a string encoded
as hex digit pairs.  On output, hex digits are output in uppercase; on
input, uppercase and lowercase are both accepted.  The default output
format is A format with half the input width.
</para>
</sect3>
</sect2>
<sect2 label="6.7.5" id="Scratch-Variables">
<title>Scratch Variables</title>

<indexterm role="cp"><primary>scratch variables</primary></indexterm>
<para>Most of the time, variables don&#8217;t retain their values between cases.
Instead, either they&#8217;re being read from a data file or the active dataset,
in which case they assume the value read, or, if created with
<literal>COMPUTE</literal> or
another transformation, they&#8217;re initialized to the system-missing value
or to blanks, depending on type.
</para>
<para>However, sometimes it&#8217;s useful to have a variable that keeps its value
between cases.  You can do this with <literal>LEAVE</literal> (see <link linkend="LEAVE">LEAVE</link>), or you can
use a <firstterm>scratch variable</firstterm>.  Scratch variables are variables whose
names begin with an octothorpe (&#8216;<literal>#</literal>&#8217;).
</para>
<para>Scratch variables have the same properties as variables left with
<literal>LEAVE</literal>: they retain their values between cases, and for the first
case they are initialized to 0 or blanks.  They have the additional
property that they are deleted before the execution of any procedure.
For this reason, scratch variables can&#8217;t be used for analysis.  To use
a scratch variable in an analysis, use <literal>COMPUTE</literal> (see <link linkend="COMPUTE">COMPUTE</link>)
to copy its value into an ordinary variable, then use that ordinary
variable in the analysis.
</para>
</sect2>
</sect1>
<sect1 label="6.8" id="Files">
<title>Files Used by PSPP</title>

<para>PSPP makes use of many files each time it runs.  Some of these it
reads, some it writes, some it creates.  Here is a table listing the
most important of these files:
</para>
<variablelist><varlistentry><term><indexterm role="cp"><primary>file, command</primary></indexterm>
<indexterm role="cp"><primary>file, syntax file</primary></indexterm>
<indexterm role="cp"><primary>command file</primary></indexterm>
<indexterm role="cp"><primary>syntax file</primary></indexterm>
<emphasis role="bold">command file</emphasis>
</term><term><emphasis role="bold">syntax file</emphasis>
</term><listitem><para>These names (synonyms) refer to the file that contains instructions
that tell PSPP what to do.  The syntax file&#8217;s name is specified on
the PSPP command line.  Syntax files can also be read with
<literal>INCLUDE</literal> (see <link linkend="INCLUDE">INCLUDE</link>).
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary>file, data</primary></indexterm>
<indexterm role="cp"><primary>data file</primary></indexterm>
<emphasis role="bold">data file</emphasis>
</term><listitem><para>Data files contain raw data in text or binary format.  Data can also
be embedded in a syntax file with <literal>BEGIN DATA</literal> and <literal>END DATA</literal>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary>file, output</primary></indexterm>
<indexterm role="cp"><primary>output file</primary></indexterm>
<emphasis role="bold">listing file</emphasis>
</term><listitem><para>One or more output files are created by PSPP each time it is
run.  The output files receive the tables and charts produced by
statistical procedures.  The output files may be in any number of formats,
depending on how PSPP is configured.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary>system file</primary></indexterm>
<indexterm role="cp"><primary>file, system</primary></indexterm>
<emphasis role="bold">system file</emphasis>
</term><listitem><para>System files are binary files that store a dictionary and a set of
cases.  <literal>GET</literal> and <literal>SAVE</literal> read and write system files.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary>portable file</primary></indexterm>
<indexterm role="cp"><primary>file, portable</primary></indexterm>
<emphasis role="bold">portable file</emphasis>
</term><listitem><para>Portable files are files in a text-based format that store a dictionary
and a set of cases.  <literal>IMPORT</literal> and <literal>EXPORT</literal> read and write
portable files.
</para></listitem></varlistentry></variablelist>
</sect1>
<sect1 label="6.9" id="File-Handles">
<title>File Handles</title>
<indexterm role="cp"><primary>file handles</primary></indexterm>

<para>A <firstterm>file handle</firstterm> is a reference to a data file, system file, or
portable file.  Most often, a file handle is specified as the
name of a file as a string, that is, enclosed within &#8216;<literal>'</literal>&#8217; or
&#8216;<literal>&quot;</literal>&#8217;.
</para>
<para>A file name string that begins or ends with &#8216;<literal>|</literal>&#8217; is treated as the
name of a command to pipe data to or from.  You can use this feature
to read data over the network using a program such as &#8216;<literal>curl</literal>&#8217;
(<emphasis>e.g.</emphasis> <literal>GET '|curl -s -S http://example.com/mydata.sav'</literal>), to
read compressed data from a file using a program such as &#8216;<literal>zcat</literal>&#8217;
(<emphasis>e.g.</emphasis> <literal>GET '|zcat mydata.sav.gz'</literal>), and for many other
purposes.
</para>
<para>PSPP also supports declaring named file handles with the <literal>FILE
HANDLE</literal> command.  This command associates an identifier of your choice
(the file handle&#8217;s name) with a file.  Later, the file handle name can
be substituted for the name of the file.  When PSPP syntax accesses a
file multiple times, declaring a named file handle simplifies updating
the syntax later to use a different file.  Use of <literal>FILE HANDLE</literal> is
also required to read data files in binary formats.  See <link linkend="FILE-HANDLE">FILE HANDLE</link>,
for more information.
</para>
<para>In some circumstances, PSPP must distinguish whether a file handle
refers to a system file or a portable file.  When this is necessary to
read a file, <emphasis>e.g.</emphasis> as an input file for <literal>GET</literal> or <literal>MATCH FILES</literal>,
PSPP uses the file&#8217;s contents to decide.  In the context of writing a
file, <emphasis>e.g.</emphasis> as an output file for <literal>SAVE</literal> or <literal>AGGREGATE</literal>, PSPP
decides based on the file&#8217;s name: if it ends in &#8216;<literal>.por</literal>&#8217; (with any
capitalization), then PSPP writes a portable file; otherwise, PSPP
writes a system file.
</para>
<para>INLINE is reserved as a file handle name.  It refers to the &#8220;data
file&#8221; embedded into the syntax file between <literal>BEGIN DATA</literal> and
<literal>END DATA</literal>.  See <link linkend="BEGIN-DATA">BEGIN DATA</link>, for more information.
</para>
<para>The file to which a file handle refers may be reassigned on a later
<literal>FILE HANDLE</literal> command if it is first closed using <literal>CLOSE FILE
HANDLE</literal>.  See <link linkend="CLOSE-FILE-HANDLE">CLOSE FILE HANDLE</link>, for
more information.
</para>
</sect1>
<sect1 label="6.10" id="BNF">
<title>Backus-Naur Form</title>
<indexterm role="cp"><primary>BNF</primary></indexterm>
<indexterm role="cp"><primary>Backus-Naur Form</primary></indexterm>
<indexterm role="cp"><primary>command syntax, description of</primary></indexterm>
<indexterm role="cp"><primary>description of command syntax</primary></indexterm>

<para>The syntax of some parts of the PSPP language is presented in this
manual using the formalism known as <firstterm>Backus-Naur Form</firstterm>, or BNF. The
following table describes BNF:
</para>
<itemizedlist><listitem><indexterm role="cp"><primary>keywords</primary></indexterm>
<indexterm role="cp"><primary>terminals</primary></indexterm>
<para>Words in all-uppercase are PSPP keyword tokens.  In BNF, these are
often called <firstterm>terminals</firstterm>.  There are some special terminals, which
are written in lowercase for clarity:
</para>
<variablelist><varlistentry><term><indexterm role="cp"><primary><literal>number</literal></primary></indexterm>
<literal>number</literal>
</term><listitem><para>A real number.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary><literal>integer</literal></primary></indexterm>
<literal>integer</literal>
</term><listitem><para>An integer number.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary><literal>string</literal></primary></indexterm>
<literal>string</literal>
</term><listitem><para>A string.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary><literal>var-name</literal></primary></indexterm>
<literal>var-name</literal>
</term><listitem><para>A single variable name.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary>operators</primary></indexterm>
<indexterm role="cp"><primary>punctuators</primary></indexterm>
<literal>=</literal>, <literal>/</literal>, <literal>+</literal>, <literal>-</literal>, etc.
</term><listitem><para>Operators and punctuators.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary><literal>.</literal></primary></indexterm>
<literal>.</literal>
</term><listitem><para>The end of the command.  This is not necessarily an actual dot in the
syntax file (see <link linkend="Commands">Commands</link>).
</para></listitem></varlistentry></variablelist>
</listitem><listitem><indexterm role="cp"><primary>productions</primary></indexterm>
<indexterm role="cp"><primary>nonterminals</primary></indexterm>
<para>Other words in all lowercase refer to BNF definitions, called
<firstterm>productions</firstterm>.  These productions are also known as
<firstterm>nonterminals</firstterm>.  Some nonterminals are very common, so they are
defined here in English for clarity:
</para>
<variablelist><varlistentry><term><indexterm role="cp"><primary><literal>var-list</literal></primary></indexterm>
<literal>var-list</literal>
</term><listitem><para>A list of one or more variable names or the keyword <literal>ALL</literal>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary><literal>expression</literal></primary></indexterm>
<literal>expression</literal>
</term><listitem><para>An expression.  See <link linkend="Expressions">Expressions</link>, for details.
</para></listitem></varlistentry></variablelist>
</listitem><listitem><indexterm role="cp"><primary>&#8220;is defined as&#8221;</primary></indexterm>
<indexterm role="cp"><primary>productions</primary></indexterm>
<para>&#8216;<literal>::=</literal>&#8217; means &#8220;is defined as&#8221;.  The left side of &#8216;<literal>::=</literal>&#8217; gives
the name of the nonterminal being defined.  The right side of &#8216;<literal>::=</literal>&#8217;
gives the definition of that nonterminal.  If the right side is empty,
then one possible expansion of that nonterminal is nothing.  A BNF
definition is called a <firstterm>production</firstterm>.
</para>
</listitem><listitem><indexterm role="cp"><primary>terminals and nonterminals, differences</primary></indexterm>
<para>So, the key difference between a terminal and a nonterminal is that a
terminal cannot be broken into smaller parts&#8212;in fact, every terminal
is a single token (see <link linkend="Tokens">Tokens</link>).  On the other hand, nonterminals are
composed of a (possibly empty) sequence of terminals and nonterminals.
Thus, terminals indicate the deepest level of syntax description.  (In
parsing theory, terminals are the leaves of the parse tree; nonterminals
form the branches.)
</para>
</listitem><listitem><indexterm role="cp"><primary>start symbol</primary></indexterm>
<indexterm role="cp"><primary>symbol, start</primary></indexterm>
<para>The first nonterminal defined in a set of productions is called the
<firstterm>start symbol</firstterm>.  The start symbol defines the entire syntax for
that command.
</para></listitem></itemizedlist><!-- PSPP - a program for statistical analysis. -->
<!-- Copyright (C) 2017, 2020 Free Software Foundation, Inc. -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.3 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<!-- A copy of the license is included in the section entitled "GNU -->
<!-- Free Documentation License". -->
<!-- -->
<!-- Use @func when referring to a function. -->
<!-- Use @deftypefn for their definitions -->

</sect1>
</chapter>
<chapter label="7" id="Expressions">
<title>Mathematical Expressions</title>
<indexterm role="cp"><primary>expressions, mathematical</primary></indexterm>
<indexterm role="cp"><primary>mathematical expressions</primary></indexterm>

<para>Expressions share a common syntax each place they appear in PSPP
commands.  Expressions are made up of <firstterm>operands</firstterm>, which can be
numbers, strings, or variable names, separated by <firstterm>operators</firstterm>.
There are five types of operators: grouping, arithmetic, logical,
relational, and functions.
</para>
<para>Every operator takes one or more operands as input and yields exactly
one result as output.  Depending on the operator, operands accept
strings or numbers as operands.  With few exceptions, operands may be
full-fledged expressions in themselves.
</para>

<sect1 label="7.1" id="Boolean-Values">
<title>Boolean Values</title>
<indexterm role="cp"><primary>Boolean</primary></indexterm>
<indexterm role="cp"><primary>values, Boolean</primary></indexterm>

<para>Some PSPP operators and expressions work with Boolean values, which
represent true/false conditions.  Booleans have only three possible
values: 0 (false), 1 (true), and system-missing (unknown).
System-missing is neither true nor false and indicates that the true
value is unknown.
</para>
<para>Boolean-typed operands or function arguments must take on one of these
three values.  Other values are considered false, but provoke a warning
when the expression is evaluated.
</para>
<para>Strings and Booleans are not compatible, and neither may be used in
place of the other.
</para>
</sect1>
<sect1 label="7.2" id="Missing-Values-in-Expressions">
<title>Missing Values in Expressions</title>

<para>Most numeric operators yield system-missing when given any
system-missing operand.  A string operator given any system-missing
operand typically results in the empty string.  Exceptions are listed
under particular operator descriptions.
</para>
<para>String user-missing values are not treated specially in expressions.
</para>
<para>User-missing values for numeric variables are always transformed into
the system-missing value, except inside the arguments to the
<literal>VALUE</literal> and <literal>SYSMIS</literal> functions.
</para>
<para>The missing-value functions can be used to precisely control how missing
values are treated in expressions.  See <link linkend="Missing-Value-Functions">Missing Value Functions</link>, for
more details.
</para>
</sect1>
<sect1 label="7.3" id="Grouping-Operators">
<title>Grouping Operators</title>
<indexterm role="cp"><primary>parentheses</primary></indexterm>
<indexterm role="cp"><primary>&#8216;<literal>(  )</literal>&#8217;</primary></indexterm>
<indexterm role="cp"><primary>grouping operators</primary></indexterm>
<indexterm role="cp"><primary>operators, grouping</primary></indexterm>

<para>Parentheses (&#8216;<literal>()</literal>&#8217;) are the grouping operators.  Surround an
expression with parentheses to force early evaluation.
</para>
<para>Parentheses also surround the arguments to functions, but in that
situation they act as punctuators, not as operators.
</para>
</sect1>
<sect1 label="7.4" id="Arithmetic-Operators">
<title>Arithmetic Operators</title>
<indexterm role="cp"><primary>operators, arithmetic</primary></indexterm>
<indexterm role="cp"><primary>arithmetic operators</primary></indexterm>

<para>The arithmetic operators take numeric operands and produce numeric
results.
</para>
<variablelist><varlistentry><term><indexterm role="cp"><primary>&#8216;<literal>+</literal>&#8217;</primary></indexterm>
<indexterm role="cp"><primary>addition</primary></indexterm>
<literal><replaceable>a</replaceable> + <replaceable>b</replaceable></literal>
</term><listitem><para>Yields the sum of <replaceable>a</replaceable> and <replaceable>b</replaceable>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary>&#8216;<literal>-</literal>&#8217;</primary></indexterm>
<indexterm role="cp"><primary>subtraction</primary></indexterm>
<literal><replaceable>a</replaceable> - <replaceable>b</replaceable></literal>
</term><listitem><para>Subtracts <replaceable>b</replaceable> from <replaceable>a</replaceable> and yields the difference.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary>&#8216;<literal>*</literal>&#8217;</primary></indexterm>
<indexterm role="cp"><primary>multiplication</primary></indexterm>
<literal><replaceable>a</replaceable> * <replaceable>b</replaceable></literal>
</term><listitem><para>Yields the product of <replaceable>a</replaceable> and <replaceable>b</replaceable>.  If either <replaceable>a</replaceable> or
<replaceable>b</replaceable> is 0, then the result is 0, even if the other operand is
missing.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary>&#8216;<literal>/</literal>&#8217;</primary></indexterm>
<indexterm role="cp"><primary>division</primary></indexterm>
<literal><replaceable>a</replaceable> / <replaceable>b</replaceable></literal>
</term><listitem><para>Divides <replaceable>a</replaceable> by <replaceable>b</replaceable> and yields the quotient.  If <replaceable>a</replaceable> is 0,
then the result is 0, even if <replaceable>b</replaceable> is missing.  If <replaceable>b</replaceable> is zero,
the result is system-missing.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary>&#8216;<literal>**</literal>&#8217;</primary></indexterm>
<indexterm role="cp"><primary>exponentiation</primary></indexterm>
<literal><replaceable>a</replaceable> ** <replaceable>b</replaceable></literal>
</term><listitem><para>Yields the result of raising <replaceable>a</replaceable> to the power <replaceable>b</replaceable>.  If
<replaceable>a</replaceable> is negative and <replaceable>b</replaceable> is not an integer, the result is
system-missing.  The result of <literal>0**0</literal> is system-missing as well.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary>&#8216;<literal>-</literal>&#8217;</primary></indexterm>
<indexterm role="cp"><primary>negation</primary></indexterm>
<literal>- <replaceable>a</replaceable></literal>
</term><listitem><para>Reverses the sign of <replaceable>a</replaceable>.
</para></listitem></varlistentry></variablelist>
</sect1>
<sect1 label="7.5" id="Logical-Operators">
<title>Logical Operators</title>
<indexterm role="cp"><primary>logical operators</primary></indexterm>
<indexterm role="cp"><primary>operators, logical</primary></indexterm>

<indexterm role="cp"><primary>true</primary></indexterm>
<indexterm role="cp"><primary>false</primary></indexterm>
<indexterm role="cp"><primary>Boolean</primary></indexterm>
<indexterm role="cp"><primary>values, system-missing</primary></indexterm>
<indexterm role="cp"><primary>system-missing</primary></indexterm>
<para>The logical operators take logical operands and produce logical
results, meaning &#8220;true or false.&#8221;  Logical operators are
not true Boolean operators because they may also result in a
system-missing value.  See <link linkend="Boolean-Values">Boolean Values</link>, for more information.
</para>
<variablelist><varlistentry><term><indexterm role="cp"><primary><literal>AND</literal></primary></indexterm>
<indexterm role="cp"><primary>&#8216;<literal>&amp;</literal>&#8217;</primary></indexterm>
<indexterm role="cp"><primary>intersection, logical</primary></indexterm>
<indexterm role="cp"><primary>logical intersection</primary></indexterm>
<literal><replaceable>a</replaceable> AND <replaceable>b</replaceable></literal>
</term><term><literal><replaceable>a</replaceable> &amp; <replaceable>b</replaceable></literal>
</term><listitem><para>True if both <replaceable>a</replaceable> and <replaceable>b</replaceable> are true, false otherwise.  If one
operand is false, the result is false even if the other is missing.  If
both operands are missing, the result is missing.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary><literal>OR</literal></primary></indexterm>
<indexterm role="cp"><primary>&#8216;<literal>|</literal>&#8217;</primary></indexterm>
<indexterm role="cp"><primary>union, logical</primary></indexterm>
<indexterm role="cp"><primary>logical union</primary></indexterm>
<literal><replaceable>a</replaceable> OR <replaceable>b</replaceable></literal>
</term><term><literal><replaceable>a</replaceable> | <replaceable>b</replaceable></literal>
</term><listitem><para>True if at least one of <replaceable>a</replaceable> and <replaceable>b</replaceable> is true.  If one operand is
true, the result is true even if the other operand is missing.  If both
operands are missing, the result is missing.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary><literal>NOT</literal></primary></indexterm>
<indexterm role="cp"><primary>&#8216;<literal>~</literal>&#8217;</primary></indexterm>
<indexterm role="cp"><primary>inversion, logical</primary></indexterm>
<indexterm role="cp"><primary>logical inversion</primary></indexterm>
<literal>NOT <replaceable>a</replaceable></literal>
</term><term><literal>~ <replaceable>a</replaceable></literal>
</term><listitem><para>True if <replaceable>a</replaceable> is false.  If the operand is missing, then the result
is missing.
</para></listitem></varlistentry></variablelist>
</sect1>
<sect1 label="7.6" id="Relational-Operators">
<title>Relational Operators</title>

<para>The relational operators take numeric or string operands and produce Boolean
results.
</para>
<para>Strings cannot be compared to numbers.  When strings of different
lengths are compared, the shorter string is right-padded with spaces
to match the length of the longer string.
</para>
<para>The results of string comparisons, other than tests for equality or
inequality, depend on the character set in use.  String comparisons
are case-sensitive.
</para>
<variablelist><varlistentry><term><indexterm role="cp"><primary>equality, testing</primary></indexterm>
<indexterm role="cp"><primary>testing for equality</primary></indexterm>
<indexterm role="cp"><primary><literal>EQ</literal></primary></indexterm>
<indexterm role="cp"><primary>&#8216;<literal>=</literal>&#8217;</primary></indexterm>
<literal><replaceable>a</replaceable> EQ <replaceable>b</replaceable></literal>
</term><term><literal><replaceable>a</replaceable> = <replaceable>b</replaceable></literal>
</term><listitem><para>True if <replaceable>a</replaceable> is equal to <replaceable>b</replaceable>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary>less than or equal to</primary></indexterm>
<indexterm role="cp"><primary><literal>LE</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>&lt;=</literal></primary></indexterm>
<literal><replaceable>a</replaceable> LE <replaceable>b</replaceable></literal>
</term><term><literal><replaceable>a</replaceable> &lt;= <replaceable>b</replaceable></literal>
</term><listitem><para>True if <replaceable>a</replaceable> is less than or equal to <replaceable>b</replaceable>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary>less than</primary></indexterm>
<indexterm role="cp"><primary><literal>LT</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>&lt;</literal></primary></indexterm>
<literal><replaceable>a</replaceable> LT <replaceable>b</replaceable></literal>
</term><term><literal><replaceable>a</replaceable> &lt; <replaceable>b</replaceable></literal>
</term><listitem><para>True if <replaceable>a</replaceable> is less than <replaceable>b</replaceable>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary>greater than or equal to</primary></indexterm>
<indexterm role="cp"><primary><literal>GE</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>&gt;=</literal></primary></indexterm>
<literal><replaceable>a</replaceable> GE <replaceable>b</replaceable></literal>
</term><term><literal><replaceable>a</replaceable> &gt;= <replaceable>b</replaceable></literal>
</term><listitem><para>True if <replaceable>a</replaceable> is greater than or equal to <replaceable>b</replaceable>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary>greater than</primary></indexterm>
<indexterm role="cp"><primary><literal>GT</literal></primary></indexterm>
<indexterm role="cp"><primary>&#8216;<literal>&gt;</literal>&#8217;</primary></indexterm>
<literal><replaceable>a</replaceable> GT <replaceable>b</replaceable></literal>
</term><term><literal><replaceable>a</replaceable> &gt; <replaceable>b</replaceable></literal>
</term><listitem><para>True if <replaceable>a</replaceable> is greater than <replaceable>b</replaceable>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="cp"><primary>inequality, testing</primary></indexterm>
<indexterm role="cp"><primary>testing for inequality</primary></indexterm>
<indexterm role="cp"><primary><literal>NE</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>~=</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>&lt;&gt;</literal></primary></indexterm>
<literal><replaceable>a</replaceable> NE <replaceable>b</replaceable></literal>
</term><term><literal><replaceable>a</replaceable> ~= <replaceable>b</replaceable></literal>
</term><term><literal><replaceable>a</replaceable> &lt;&gt; <replaceable>b</replaceable></literal>
</term><listitem><para>True if <replaceable>a</replaceable> is not equal to <replaceable>b</replaceable>.
</para></listitem></varlistentry></variablelist>
</sect1>
<sect1 label="7.7" id="Functions">
<title>Functions</title>
<indexterm role="cp"><primary>functions</primary></indexterm>

<indexterm role="cp"><primary>mathematics</primary></indexterm>
<indexterm role="cp"><primary>operators</primary></indexterm>
<indexterm role="cp"><primary>parentheses</primary></indexterm>
<indexterm role="cp"><primary><literal>(</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>)</literal></primary></indexterm>
<indexterm role="cp"><primary>names, of functions</primary></indexterm>
<para>PSPP functions provide mathematical abilities above and beyond
those possible using simple operators.  Functions have a common
syntax: each is composed of a function name followed by a left
parenthesis, one or more arguments, and a right parenthesis.
</para>
<para>Function names are not reserved.  Their names are specially treated
only when followed by a left parenthesis, so that &#8216;<literal>EXP(10)</literal>&#8217;
refers to the constant value <inlineequation><mathphrase>e</mathphrase></inlineequation> raised to the 10th power, but
&#8216;<literal>EXP</literal>&#8217; by itself refers to the value of a variable called <literal>EXP</literal>.
</para>
<para>The sections below describe each function in detail.
</para>

<sect2 label="7.7.1" id="Mathematics">
<title>Mathematical Functions</title>
<indexterm role="cp"><primary>mathematics, advanced</primary></indexterm>

<para>Advanced mathematical functions take numeric arguments and produce
numeric results.
</para>
<synopsis><indexterm role="fn"><primary>EXP</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>EXP</function> (<emphasis role="arg"><replaceable>exponent</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns <inlineequation><mathphrase>e</mathphrase></inlineequation> (approximately 2.71828) raised to power <replaceable>exponent</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>logarithms</primary></indexterm>
<synopsis><indexterm role="fn"><primary>LG10</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>LG10</function> (<emphasis role="arg"><replaceable>number</replaceable></emphasis>)</synopsis>
<blockquote><para>Takes the base-10 logarithm of <replaceable>number</replaceable>.  If <replaceable>number</replaceable> is
not positive, the result is system-missing.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>LN</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>LN</function> (<emphasis role="arg"><replaceable>number</replaceable></emphasis>)</synopsis>
<blockquote><para>Takes the base-<inlineequation><mathphrase>e</mathphrase></inlineequation> logarithm of <replaceable>number</replaceable>.  If <replaceable>number</replaceable> is
not positive, the result is system-missing.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>LNGAMMA</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>LNGAMMA</function> (<emphasis role="arg"><replaceable>number</replaceable></emphasis>)</synopsis>
<blockquote><para>Yields the base-<inlineequation><mathphrase>e</mathphrase></inlineequation> logarithm of the complete gamma of <replaceable>number</replaceable>.
If <replaceable>number</replaceable> is a negative integer, the result is system-missing.
</para></blockquote>
<indexterm role="cp"><primary>square roots</primary></indexterm>
<synopsis><indexterm role="fn"><primary>SQRT</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>SQRT</function> (<emphasis role="arg"><replaceable>number</replaceable></emphasis>)</synopsis>
<blockquote><para>Takes the square root of <replaceable>number</replaceable>.  If <replaceable>number</replaceable> is negative,
the result is system-missing.
</para></blockquote>
</sect2>
<sect2 label="7.7.2" id="Miscellaneous-Mathematics">
<title>Miscellaneous Mathematical Functions</title>
<indexterm role="cp"><primary>mathematics, miscellaneous</primary></indexterm>

<para>Miscellaneous mathematical functions take numeric arguments and produce
numeric results.
</para>
<indexterm role="cp"><primary>absolute value</primary></indexterm>
<synopsis><indexterm role="fn"><primary>ABS</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>ABS</function> (<emphasis role="arg"><replaceable>number</replaceable></emphasis>)</synopsis>
<blockquote><para>Results in the absolute value of <replaceable>number</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>modulus</primary></indexterm>
<synopsis><indexterm role="fn"><primary>MOD</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>MOD</function> (<emphasis role="arg"><replaceable>numerator</replaceable></emphasis>, <emphasis role="arg"><replaceable>denominator</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns the remainder (modulus) of <replaceable>numerator</replaceable> divided by
<replaceable>denominator</replaceable>.  If <replaceable>numerator</replaceable> is 0, then the result is 0,
even if <replaceable>denominator</replaceable> is missing.  If <replaceable>denominator</replaceable> is 0, the
result is system-missing.
</para></blockquote>
<indexterm role="cp"><primary>modulus, by 10</primary></indexterm>
<synopsis><indexterm role="fn"><primary>MOD10</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>MOD10</function> (<emphasis role="arg"><replaceable>number</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns the remainder when <replaceable>number</replaceable> is divided by 10.  If
<replaceable>number</replaceable> is negative, MOD10(<replaceable>number</replaceable>) is negative or zero.
</para></blockquote>
<indexterm role="cp"><primary>rounding</primary></indexterm>
<synopsis><indexterm role="fn"><primary>RND</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RND</function> (<emphasis role="arg"><replaceable>number</replaceable></emphasis> [, <emphasis role="arg"><replaceable>mult</replaceable></emphasis>[, <emphasis role="arg"><replaceable>fuzzbits</replaceable></emphasis>]])</synopsis>
<blockquote><para>Rounds <replaceable>number</replaceable> and rounds it to a multiple of <replaceable>mult</replaceable> (by
default 1).  Halves are rounded away from zero, as are values that
fall short of halves by less than <replaceable>fuzzbits</replaceable> of errors in the
least-significant bits of <replaceable>number</replaceable>.  If <replaceable>fuzzbits</replaceable> is not
specified then the default is taken from SET FUZZBITS (see <link linkend="SET-FUZZBITS">SET
FUZZBITS</link>), which is 6 unless overridden.
</para></blockquote>
<indexterm role="cp"><primary>truncation</primary></indexterm>
<synopsis><indexterm role="fn"><primary>TRUNC</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>TRUNC</function> (<emphasis role="arg"><replaceable>number</replaceable></emphasis> [, <emphasis role="arg"><replaceable>mult</replaceable></emphasis>[, <emphasis role="arg"><replaceable>fuzzbits</replaceable></emphasis>]])</synopsis>
<blockquote><para>Rounds <replaceable>number</replaceable> to a multiple of <replaceable>mult</replaceable>, toward zero.  For the
default <replaceable>mult</replaceable> of 1, this is equivalent to discarding the
fractional part of <replaceable>number</replaceable>.  Values that fall short of a multiple
of <replaceable>mult</replaceable> by less than <replaceable>fuzzbits</replaceable> of errors in the
least-significant bits of <replaceable>number</replaceable> are rounded away from zero.  If
<replaceable>fuzzbits</replaceable> is not specified then the default is taken from SET
FUZZBITS (see <link linkend="SET-FUZZBITS">SET FUZZBITS</link>), which is 6 unless overridden.
</para></blockquote>
</sect2>
<sect2 label="7.7.3" id="Trigonometry">
<title>Trigonometric Functions</title>
<indexterm role="cp"><primary>trigonometry</primary></indexterm>

<para>Trigonometric functions take numeric arguments and produce numeric
results.
</para>
<indexterm role="cp"><primary>arccosine</primary></indexterm>
<indexterm role="cp"><primary>inverse cosine</primary></indexterm>
<synopsis><indexterm role="fn"><primary>ARCOS</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>ARCOS</function> (<emphasis role="arg"><replaceable>number</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>ACOS</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>ACOS</function> (<emphasis role="arg"><replaceable>number</replaceable></emphasis>)</synopsis>
<blockquote><para>Takes the arccosine, in radians, of <replaceable>number</replaceable>.  Results in
system-missing if <replaceable>number</replaceable> is not between -1 and 1 inclusive.
This function is a PSPP extension.
</para></blockquote>
<indexterm role="cp"><primary>arcsine</primary></indexterm>
<indexterm role="cp"><primary>inverse sine</primary></indexterm>
<synopsis><indexterm role="fn"><primary>ARSIN</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>ARSIN</function> (<emphasis role="arg"><replaceable>number</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>ASIN</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>ASIN</function> (<emphasis role="arg"><replaceable>number</replaceable></emphasis>)</synopsis>
<blockquote><para>Takes the arcsine, in radians, of <replaceable>number</replaceable>.  Results in
system-missing if <replaceable>number</replaceable> is not between -1 and 1 inclusive.
</para></blockquote>
<indexterm role="cp"><primary>arctangent</primary></indexterm>
<indexterm role="cp"><primary>inverse tangent</primary></indexterm>
<synopsis><indexterm role="fn"><primary>ARTAN</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>ARTAN</function> (<emphasis role="arg"><replaceable>number</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>ATAN</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>ATAN</function> (<emphasis role="arg"><replaceable>number</replaceable></emphasis>)</synopsis>
<blockquote><para>Takes the arctangent, in radians, of <replaceable>number</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>cosine</primary></indexterm>
<synopsis><indexterm role="fn"><primary>COS</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>COS</function> (<emphasis role="arg"><replaceable>angle</replaceable></emphasis>)</synopsis>
<blockquote><para>Takes the cosine of <replaceable>angle</replaceable> which should be in radians.
</para></blockquote>
<indexterm role="cp"><primary>sine</primary></indexterm>
<synopsis><indexterm role="fn"><primary>SIN</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>SIN</function> (<emphasis role="arg"><replaceable>angle</replaceable></emphasis>)</synopsis>
<blockquote><para>Takes the sine of <replaceable>angle</replaceable> which should be in radians.
</para></blockquote>
<indexterm role="cp"><primary>tangent</primary></indexterm>
<synopsis><indexterm role="fn"><primary>TAN</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>TAN</function> (<emphasis role="arg"><replaceable>angle</replaceable></emphasis>)</synopsis>
<blockquote><para>Takes the tangent of <replaceable>angle</replaceable> which should be in radians.
Results in system-missing at values
of <replaceable>angle</replaceable> that are too close to odd multiples of <inlineequation><mathphrase>\pi/2</mathphrase></inlineequation>.
Portability: none.
</para></blockquote>
</sect2>
<sect2 label="7.7.4" id="Missing-Value-Functions">
<title>Missing-Value Functions</title>
<indexterm role="cp"><primary>missing values</primary></indexterm>
<indexterm role="cp"><primary>values, missing</primary></indexterm>
<indexterm role="cp"><primary>functions, missing-value</primary></indexterm>

<para>Missing-value functions take various numeric arguments and yield
various types of results.  Except where otherwise stated below, the
normal rules of evaluation apply within expression arguments to these
functions.  In particular, user-missing values for numeric variables
are converted to system-missing values.
</para>
<synopsis><indexterm role="fn"><primary>MISSING</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>MISSING</function> (<emphasis role="arg"><replaceable>expr</replaceable></emphasis>)</synopsis>
<blockquote><para>When <replaceable>expr</replaceable> is simply the name of a numeric variable, returns 1 if
the variable has the system-missing value or if it is user-missing.
For any other value 0 is returned.
If <replaceable>expr</replaceable> takes another form, the function returns 1 if the value is
system-missing, 0 otherwise.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>NMISS</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>NMISS</function> (<emphasis role="arg"><replaceable>expr</replaceable></emphasis> [, <emphasis role="arg"><replaceable>expr</replaceable></emphasis>]<emphasis role="arg">&#8230;</emphasis>)</synopsis>
<blockquote><para>Each argument must be a numeric expression.  Returns the number of
system-missing values in the list, which may include variable ranges
using the <literal><replaceable>var1</replaceable> TO <replaceable>var2</replaceable></literal> syntax.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>NVALID</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>NVALID</function> (<emphasis role="arg"><replaceable>expr</replaceable></emphasis> [, <emphasis role="arg"><replaceable>expr</replaceable></emphasis>]<emphasis role="arg">&#8230;</emphasis>)</synopsis>
<blockquote><para>Each argument must be a numeric expression.  Returns the number of
values in the list that are not system-missing.  The list may include
variable ranges using the <literal><replaceable>var1</replaceable> TO <replaceable>var2</replaceable></literal> syntax.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>SYSMIS</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>SYSMIS</function> (<emphasis role="arg"><replaceable>expr</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns 1 if <replaceable>expr</replaceable> has the system-missing value, 0 otherwise.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>VALUE</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>VALUE</function> (<emphasis role="arg"><replaceable>variable</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>VALUE</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>VALUE</function> (<emphasis role="arg"><replaceable>vector</replaceable></emphasis>(<emphasis role="arg"><replaceable>index</replaceable></emphasis>))</synopsis>
<blockquote><para>Prevents the user-missing values of the variable or vector element
from being transformed into system-missing values, and always results
in its actual value, whether it is valid, user-missing, or
system-missing.
</para></blockquote>
</sect2>
<sect2 label="7.7.5" id="Set-Membership">
<title>Set-Membership Functions</title>
<indexterm role="cp"><primary>set membership</primary></indexterm>
<indexterm role="cp"><primary>membership, of set</primary></indexterm>

<para>Set membership functions determine whether a value is a member of a set.
They take a set of numeric arguments or a set of string arguments, and
produce Boolean results.
</para>
<para>String comparisons are performed according to the rules given in
<link linkend="Relational-Operators">Relational Operators</link>.  User-missing string values are treated as
valid values.
</para>
<synopsis><indexterm role="fn"><primary>ANY</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>ANY</function> (<emphasis role="arg"><replaceable>value</replaceable></emphasis>, <emphasis role="arg"><replaceable>set</replaceable></emphasis> [, <emphasis role="arg"><replaceable>set</replaceable></emphasis>]<emphasis role="arg">&#8230;</emphasis>)</synopsis>
<blockquote><para>Returns true if <replaceable>value</replaceable> is equal to any of the <replaceable>set</replaceable> values,
and false otherwise.  For numeric arguments, returns system-missing if
<replaceable>value</replaceable> is system-missing or if all the values in <replaceable>set</replaceable> are
system-missing.  If <replaceable>value</replaceable>
</para></blockquote>
<synopsis><indexterm role="fn"><primary>RANGE</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RANGE</function> (<emphasis role="arg"><replaceable>value</replaceable></emphasis>, <emphasis role="arg"><replaceable>low</replaceable></emphasis>, <emphasis role="arg"><replaceable>high</replaceable></emphasis> [, <emphasis role="arg"><replaceable>low</replaceable></emphasis>, <emphasis role="arg"><replaceable>high</replaceable></emphasis>]<emphasis role="arg">&#8230;</emphasis>)</synopsis>
<blockquote><para>Returns true if <replaceable>value</replaceable> is in any of the intervals bounded by
<replaceable>low</replaceable> and <replaceable>high</replaceable> inclusive, and false otherwise.  <replaceable>low</replaceable>
and <replaceable>high</replaceable> must be given in pairs.  Returns system-missing if any
<replaceable>high</replaceable> is less than its <replaceable>low</replaceable> or, for numeric arguments, if
<replaceable>value</replaceable> is system-missing or if all the <replaceable>low</replaceable>-<replaceable>high</replaceable> pairs
contain one (or two) system-missing values.  A pair does not match
<replaceable>value</replaceable> if either <replaceable>low</replaceable> or <replaceable>high</replaceable> is missing, even if
<replaceable>value</replaceable> equals the non-missing endpoint.
</para></blockquote>
</sect2>
<sect2 label="7.7.6" id="Statistical-Functions">
<title>Statistical Functions</title>
<indexterm role="cp"><primary>functions, statistical</primary></indexterm>
<indexterm role="cp"><primary>statistics</primary></indexterm>

<para>Statistical functions compute descriptive statistics on a list of
values.  Some statistics can be computed on numeric or string values;
other can only be computed on numeric values.  Their results have the
same type as their arguments.  The current case&#8217;s weighting factor
(see <link linkend="WEIGHT">WEIGHT</link>) has no effect on statistical functions.
</para>
<para>These functions&#8217; argument lists may include entire ranges of variables
using the <literal><replaceable>var1</replaceable> TO <replaceable>var2</replaceable></literal> syntax.
</para>
<indexterm role="cp"><primary>arguments, minimum valid</primary></indexterm>
<indexterm role="cp"><primary>minimum valid number of arguments</primary></indexterm>
<para>Unlike most functions, statistical functions can return non-missing
values even when some of their arguments are missing.  Most
statistical functions, by default, require only 1 non-missing value to
have a non-missing return, but <literal>CFVAR</literal>, <literal>SD</literal>, and <literal>VARIANCE</literal> require 2.
These defaults can be increased (but not decreased) by appending a dot
and the minimum number of valid arguments to the function name.  For
example, <literal>MEAN.3(X, Y, Z)</literal> would only return non-missing if all
of &#8216;<literal>X</literal>&#8217;, &#8216;<literal>Y</literal>&#8217;, and &#8216;<literal>Z</literal>&#8217; were valid.
</para>
<indexterm role="cp"><primary>coefficient of variation</primary></indexterm>
<indexterm role="cp"><primary>variation, coefficient of</primary></indexterm>
<synopsis><indexterm role="fn"><primary>CFVAR</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CFVAR</function> (<emphasis role="arg"><replaceable>number</replaceable></emphasis>, <emphasis role="arg"><replaceable>number</replaceable></emphasis>[, <emphasis role="arg">&#8230;</emphasis>])</synopsis>
<blockquote><para>Results in the coefficient of variation of the values of <replaceable>number</replaceable>.
(The coefficient of variation is the standard deviation divided by the
mean.)
</para></blockquote>
<indexterm role="cp"><primary>maximum</primary></indexterm>
<synopsis><indexterm role="fn"><primary>MAX</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>MAX</function> (<emphasis role="arg"><replaceable>value</replaceable></emphasis>, <emphasis role="arg"><replaceable>value</replaceable></emphasis>[, <emphasis role="arg">&#8230;</emphasis>])</synopsis>
<blockquote><para>Results in the value of the greatest <replaceable>value</replaceable>.  The <replaceable>value</replaceable>s may
be numeric or string.
</para></blockquote>
<indexterm role="cp"><primary>mean</primary></indexterm>
<synopsis><indexterm role="fn"><primary>MEAN</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>MEAN</function> (<emphasis role="arg"><replaceable>number</replaceable></emphasis>, <emphasis role="arg"><replaceable>number</replaceable></emphasis>[, <emphasis role="arg">&#8230;</emphasis>])</synopsis>
<blockquote><para>Results in the mean of the values of <replaceable>number</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>median</primary></indexterm>
<synopsis><indexterm role="fn"><primary>MEDIAN</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>MEDIAN</function> (<emphasis role="arg"><replaceable>number</replaceable></emphasis>, <emphasis role="arg"><replaceable>number</replaceable></emphasis>[, <emphasis role="arg">&#8230;</emphasis>])</synopsis>
<blockquote><para>Results in the median of the values of <replaceable>number</replaceable>.  Given an even
number of nonmissing arguments, yields the mean of the two middle
values.
</para></blockquote>
<indexterm role="cp"><primary>minimum</primary></indexterm>
<synopsis><indexterm role="fn"><primary>MIN</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>MIN</function> (<emphasis role="arg"><replaceable>number</replaceable></emphasis>, <emphasis role="arg"><replaceable>number</replaceable></emphasis>[, <emphasis role="arg">&#8230;</emphasis>])</synopsis>
<blockquote><para>Results in the value of the least <replaceable>value</replaceable>.  The <replaceable>value</replaceable>s may
be numeric or string.
</para></blockquote>
<indexterm role="cp"><primary>standard deviation</primary></indexterm>
<indexterm role="cp"><primary>deviation, standard</primary></indexterm>
<synopsis><indexterm role="fn"><primary>SD</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>SD</function> (<emphasis role="arg"><replaceable>number</replaceable></emphasis>, <emphasis role="arg"><replaceable>number</replaceable></emphasis>[, <emphasis role="arg">&#8230;</emphasis>])</synopsis>
<blockquote><para>Results in the standard deviation of the values of <replaceable>number</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>sum</primary></indexterm>
<synopsis><indexterm role="fn"><primary>SUM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>SUM</function> (<emphasis role="arg"><replaceable>number</replaceable></emphasis>, <emphasis role="arg"><replaceable>number</replaceable></emphasis>[, <emphasis role="arg">&#8230;</emphasis>])</synopsis>
<blockquote><para>Results in the sum of the values of <replaceable>number</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>variance</primary></indexterm>
<synopsis><indexterm role="fn"><primary>VARIANCE</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>VARIANCE</function> (<emphasis role="arg"><replaceable>number</replaceable></emphasis>, <emphasis role="arg"><replaceable>number</replaceable></emphasis>[, <emphasis role="arg">&#8230;</emphasis>])</synopsis>
<blockquote><para>Results in the variance of the values of <replaceable>number</replaceable>.
</para></blockquote>
</sect2>
<sect2 label="7.7.7" id="String-Functions">
<title>String Functions</title>
<indexterm role="cp"><primary>functions, string</primary></indexterm>
<indexterm role="cp"><primary>string functions</primary></indexterm>

<para>String functions take various arguments and return various results.
</para>
<indexterm role="cp"><primary>concatenation</primary></indexterm>
<indexterm role="cp"><primary>strings, concatenation of</primary></indexterm>
<synopsis><indexterm role="fn"><primary>CONCAT</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CONCAT</function> (<emphasis role="arg"><replaceable>string</replaceable></emphasis>, <emphasis role="arg"><replaceable>string</replaceable></emphasis>[, <emphasis role="arg">&#8230;</emphasis>])</synopsis>
<blockquote><para>Returns a string consisting of each <replaceable>string</replaceable> in sequence.
<literal>CONCAT(&quot;abc&quot;, &quot;def&quot;, &quot;ghi&quot;)</literal> has a value of <literal>&quot;abcdefghi&quot;</literal>.
The resultant string is truncated to a maximum of 32767 bytes.
</para></blockquote>
<indexterm role="cp"><primary>searching strings</primary></indexterm>
<synopsis><indexterm role="fn"><primary>INDEX</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>INDEX</function> (<emphasis role="arg"><replaceable>haystack</replaceable></emphasis>, <emphasis role="arg"><replaceable>needle</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RINDEX</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RINDEX</function> (<emphasis role="arg"><replaceable>haystack</replaceable></emphasis>, <emphasis role="arg"><replaceable>needle</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns a positive integer indicating the position of the first (for
<literal>INDEX</literal>) or last (for <literal>RINDEX</literal>) occurrence of <replaceable>needle</replaceable>
in <replaceable>haystack</replaceable>.  Returns 0 if <replaceable>haystack</replaceable> does not contain
<replaceable>needle</replaceable>.  Returns 1 if <replaceable>needle</replaceable> is the empty string.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>INDEX</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>INDEX</function> (<emphasis role="arg"><replaceable>haystack</replaceable></emphasis>, <emphasis role="arg"><replaceable>needles</replaceable></emphasis>, <emphasis role="arg"><replaceable>needle_len</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RINDEX</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RINDEX</function> (<emphasis role="arg"><replaceable>haystack</replaceable></emphasis>, <emphasis role="arg"><replaceable>needle</replaceable></emphasis>, <emphasis role="arg"><replaceable>needle_len</replaceable></emphasis>)</synopsis>
<blockquote><para>Divides <replaceable>needles</replaceable> into multiple needles, each with length
<replaceable>needle_len</replaceable>, which must be a positive integer that evenly divides
the length of <replaceable>needles</replaceable>.  Searches <replaceable>haystack</replaceable> for the
occurrences of each needle and returns a positive integer indicating
the byte index of the beginning of the first (for <literal>INDEX</literal>) or
last (for <literal>RINDEX</literal>) needle it finds.  Returns 0 if <replaceable>haystack</replaceable>
does not contain any of the needles, or if <replaceable>needles</replaceable> is the empty
string.
</para></blockquote>
<indexterm role="cp"><primary>strings, finding length of</primary></indexterm>
<synopsis><indexterm role="fn"><primary>LENGTH</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>LENGTH</function> (<emphasis role="arg"><replaceable>string</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns the number of bytes in <replaceable>string</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>strings, case of</primary></indexterm>
<synopsis><indexterm role="fn"><primary>LOWER</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>LOWER</function> (<emphasis role="arg"><replaceable>string</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns a string identical to <replaceable>string</replaceable> except that all uppercase
letters are changed to lowercase letters.  The definitions of
&#8220;uppercase&#8221; and &#8220;lowercase&#8221; are system-dependent.
</para></blockquote>
<indexterm role="cp"><primary>strings, padding</primary></indexterm>
<synopsis><indexterm role="fn"><primary>LPAD</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>LPAD</function> (<emphasis role="arg"><replaceable>string</replaceable></emphasis>, <emphasis role="arg"><replaceable>length</replaceable></emphasis>[, <emphasis role="arg"><replaceable>padding</replaceable></emphasis>])</synopsis>
<synopsis><indexterm role="fn"><primary>RPAD</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RPAD</function> (<emphasis role="arg"><replaceable>string</replaceable></emphasis>, <emphasis role="arg"><replaceable>length</replaceable></emphasis>[, <emphasis role="arg"><replaceable>padding</replaceable></emphasis>])</synopsis>
<blockquote><para>If <replaceable>string</replaceable> is at least <replaceable>length</replaceable> bytes long, these functions
return <replaceable>string</replaceable> unchanged.  Otherwise, they return <replaceable>string</replaceable>
padded with <replaceable>padding</replaceable> on the left side (for <literal>LPAD</literal>) or right
side (for <literal>RPAD</literal>) to <replaceable>length</replaceable> bytes.  These functions report
an error and return <replaceable>string</replaceable> unchanged if <replaceable>length</replaceable> is missing
or bigger than 32767.
</para>
<para>The <replaceable>padding</replaceable> argument must not be an empty string and defaults to
a space if not specified.  If its length does not evenly fit the
amount of space needed for padding, the returned string will be
shorter than <replaceable>length</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>strings, trimming</primary></indexterm>
<indexterm role="cp"><primary>white space, trimming</primary></indexterm>
<synopsis><indexterm role="fn"><primary>LTRIM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>LTRIM</function> (<emphasis role="arg"><replaceable>string</replaceable></emphasis>[, <emphasis role="arg"><replaceable>padding</replaceable></emphasis>])</synopsis>
<synopsis><indexterm role="fn"><primary>RTRIM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RTRIM</function> (<emphasis role="arg"><replaceable>string</replaceable></emphasis>[, <emphasis role="arg"><replaceable>padding</replaceable></emphasis>])</synopsis>
<blockquote><para>These functions return <replaceable>string</replaceable>, after removing leading (for
<literal>LTRIM</literal>) or trailing (for <literal>RTRIM</literal>) copies of <replaceable>padding</replaceable>.
If <replaceable>padding</replaceable> is omitted, these functions remove spaces (but not
tabs or other white space).  These functions return <replaceable>string</replaceable>
unchanged if <replaceable>padding</replaceable> is the empty string.
</para></blockquote>
<indexterm role="cp"><primary>numbers, converting from strings</primary></indexterm>
<indexterm role="cp"><primary>strings, converting to numbers</primary></indexterm>
<synopsis><indexterm role="fn"><primary>NUMBER</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>NUMBER</function> (<emphasis role="arg"><replaceable>string</replaceable></emphasis>, <emphasis role="arg"><replaceable>format</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns the number produced when <replaceable>string</replaceable> is interpreted according
to format specifier <replaceable>format</replaceable>.  If the format width <replaceable>w</replaceable> is less
than the length of <replaceable>string</replaceable>, then only the first <replaceable>w</replaceable> bytes in
<replaceable>string</replaceable> are used, <emphasis>e.g.</emphasis> <literal>NUMBER(&quot;123&quot;, F3.0)</literal> and
<literal>NUMBER(&quot;1234&quot;, F3.0)</literal> both have value 123.  If <replaceable>w</replaceable> is
greater than <replaceable>string</replaceable>&#8217;s length, then it is treated as if it were
right-padded with spaces.  If <replaceable>string</replaceable> is not in the correct
format for <replaceable>format</replaceable>, system-missing is returned.
</para></blockquote>
<indexterm role="cp"><primary>strings, replacing substrings</primary></indexterm>
<indexterm role="cp"><primary>replacing substrings</primary></indexterm>
<synopsis><indexterm role="fn"><primary>REPLACE</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>REPLACE</function> (<emphasis role="arg"><replaceable>haystack</replaceable></emphasis>, <emphasis role="arg"><replaceable>needle</replaceable></emphasis>, <emphasis role="arg"><replaceable>replacement</replaceable></emphasis>[, <emphasis role="arg"><replaceable>n</replaceable></emphasis>])</synopsis>
<blockquote><para>Returns string <replaceable>haystack</replaceable> with instances of <replaceable>needle</replaceable> replaced
by <replaceable>replacement</replaceable>.  If nonnegative integer <replaceable>n</replaceable> is specified, it
limits the maximum number of replacements; otherwise, all instances of
<replaceable>needle</replaceable> are replaced.
</para></blockquote>
<indexterm role="cp"><primary>strings, converting from numbers</primary></indexterm>
<indexterm role="cp"><primary>numbers, converting to strings</primary></indexterm>
<synopsis><indexterm role="fn"><primary>STRING</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>STRING</function> (<emphasis role="arg"><replaceable>number</replaceable></emphasis>, <emphasis role="arg"><replaceable>format</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns a string corresponding to <replaceable>number</replaceable> in the format given by
format specifier <replaceable>format</replaceable>.  For example, <literal>STRING(123.56, F5.1)</literal>
has the value <literal>&quot;123.6&quot;</literal>.
</para></blockquote>
<indexterm role="cp"><primary>strings, trimming</primary></indexterm>
<indexterm role="cp"><primary>strings, truncating</primary></indexterm>
<indexterm role="cp"><primary>white space, trimming</primary></indexterm>
<synopsis><indexterm role="fn"><primary>STRUNC</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>STRUNC</function> (<emphasis role="arg"><replaceable>string</replaceable></emphasis>, <emphasis role="arg"><replaceable>n</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns <replaceable>string</replaceable>, first trimming it to at most <replaceable>n</replaceable> bytes, then
removing trailing spaces (but not tabs or other white space).  Returns
an empty string if <replaceable>n</replaceable> is zero or negative, or <replaceable>string</replaceable>
unchanged if <replaceable>n</replaceable> is missing.
</para></blockquote>
<indexterm role="cp"><primary>substrings</primary></indexterm>
<indexterm role="cp"><primary>strings, taking substrings of</primary></indexterm>
<synopsis><indexterm role="fn"><primary>SUBSTR</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>SUBSTR</function> (<emphasis role="arg"><replaceable>string</replaceable></emphasis>, <emphasis role="arg"><replaceable>start</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns a string consisting of the value of <replaceable>string</replaceable> from position
<replaceable>start</replaceable> onward.  Returns an empty string if <replaceable>start</replaceable> is system-missing,
less than 1, or greater than the length of <replaceable>string</replaceable>.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>SUBSTR</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>SUBSTR</function> (<emphasis role="arg"><replaceable>string</replaceable></emphasis>, <emphasis role="arg"><replaceable>start</replaceable></emphasis>, <emphasis role="arg"><replaceable>count</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns a string consisting of the first <replaceable>count</replaceable> bytes from
<replaceable>string</replaceable> beginning at position <replaceable>start</replaceable>.  Returns an empty
string if <replaceable>start</replaceable> or <replaceable>count</replaceable> is system-missing, if <replaceable>start</replaceable>
is less than 1 or greater than the number of bytes in <replaceable>string</replaceable>, or
if <replaceable>count</replaceable> is less than 1.  Returns a string shorter than
<replaceable>count</replaceable> bytes if <replaceable>start</replaceable> + <replaceable>count</replaceable> - 1 is greater than the
number of bytes in <replaceable>string</replaceable>.  Examples: <literal>SUBSTR(&quot;abcdefg&quot;, 3,
2)</literal> has value <literal>&quot;cd&quot;</literal>; <literal>SUBSTR(&quot;nonsense&quot;, 4, 10)</literal> has the
value <literal>&quot;sense&quot;</literal>.
</para></blockquote>
<indexterm role="cp"><primary>case conversion</primary></indexterm>
<indexterm role="cp"><primary>strings, case of</primary></indexterm>
<synopsis><indexterm role="fn"><primary>UPCASE</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>UPCASE</function> (<emphasis role="arg"><replaceable>string</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns <replaceable>string</replaceable>, changing lowercase letters to uppercase letters.
</para></blockquote>
</sect2>
<sect2 label="7.7.8" id="Time-and-Date">
<title>Time &amp; Date Functions</title>
<indexterm role="cp"><primary>functions, time &amp; date</primary></indexterm>
<indexterm role="cp"><primary>times</primary></indexterm>
<indexterm role="cp"><primary>dates</primary></indexterm>

<indexterm role="cp"><primary>dates, valid</primary></indexterm>
<para>For compatibility, PSPP considers dates before 15 Oct 1582 invalid.
Most time and date functions will not accept earlier dates.
</para>

<sect3 label="7.7.8.1" id="Time-and-Date-Concepts">
<title>How times &amp; dates are defined and represented</title>

<indexterm role="cp"><primary>time, concepts</primary></indexterm>
<indexterm role="cp"><primary>time, intervals</primary></indexterm>
<para>Times and dates are handled by PSPP as single numbers.  A
<firstterm>time</firstterm> is an interval.  PSPP measures times in seconds.
Thus, the following intervals correspond with the numeric values given:
</para>
<screen>          10 minutes                        600
          1 hour                          3,600
          1 day, 3 hours, 10 seconds     97,210
          40 days                     3,456,000
</screen>
<indexterm role="cp"><primary>dates, concepts</primary></indexterm>
<indexterm role="cp"><primary>time, instants of</primary></indexterm>
<para>A <firstterm>date</firstterm>, on the other hand, is a particular instant in the past
or the future.  PSPP represents a date as a number of seconds since
midnight preceding 14 Oct 1582.  Because midnight preceding the dates
given below correspond with the numeric PSPP dates given:
</para>
<screen>              15 Oct 1582                86,400
               4 Jul 1776         6,113,318,400
               1 Jan 1900        10,010,390,400
               1 Oct 1978        12,495,427,200
              24 Aug 1995        13,028,601,600
</screen>
</sect3>
<sect3 label="7.7.8.2" id="Time-Construction">
<title>Functions that Produce Times</title>
<indexterm role="cp"><primary>times, constructing</primary></indexterm>
<indexterm role="cp"><primary>constructing times</primary></indexterm>

<para>These functions take numeric arguments and return numeric values that
represent times.
</para>
<indexterm role="cp"><primary>days</primary></indexterm>
<indexterm role="cp"><primary>time, in days</primary></indexterm>
<synopsis><indexterm role="fn"><primary>TIME.DAYS</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>TIME.DAYS</function> (<emphasis role="arg"><replaceable>ndays</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns a time corresponding to <replaceable>ndays</replaceable> days.
</para></blockquote>
<indexterm role="cp"><primary>hours-minutes-seconds</primary></indexterm>
<indexterm role="cp"><primary>time, in hours-minutes-seconds</primary></indexterm>
<synopsis><indexterm role="fn"><primary>TIME.HMS</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>TIME.HMS</function> (<emphasis role="arg"><replaceable>nhours</replaceable></emphasis>, <emphasis role="arg"><replaceable>nmins</replaceable></emphasis>, <emphasis role="arg"><replaceable>nsecs</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns a time corresponding to <replaceable>nhours</replaceable> hours, <replaceable>nmins</replaceable>
minutes, and <replaceable>nsecs</replaceable> seconds.  The arguments may not have mixed
signs: if any of them are positive, then none may be negative, and
vice versa.
</para></blockquote>
</sect3>
<sect3 label="7.7.8.3" id="Time-Extraction">
<title>Functions that Examine Times</title>
<indexterm role="cp"><primary>extraction, of time</primary></indexterm>
<indexterm role="cp"><primary>time examination</primary></indexterm>
<indexterm role="cp"><primary>examination, of times</primary></indexterm>
<indexterm role="cp"><primary>time, lengths of</primary></indexterm>

<para>These functions take numeric arguments in PSPP time format and
give numeric results.
</para>
<indexterm role="cp"><primary>days</primary></indexterm>
<indexterm role="cp"><primary>time, in days</primary></indexterm>
<synopsis><indexterm role="fn"><primary>CTIME.DAYS</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CTIME.DAYS</function> (<emphasis role="arg"><replaceable>time</replaceable></emphasis>)</synopsis>
<blockquote><para>Results in the number of days and fractional days in <replaceable>time</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>hours</primary></indexterm>
<indexterm role="cp"><primary>time, in hours</primary></indexterm>
<synopsis><indexterm role="fn"><primary>CTIME.HOURS</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CTIME.HOURS</function> (<emphasis role="arg"><replaceable>time</replaceable></emphasis>)</synopsis>
<blockquote><para>Results in the number of hours and fractional hours in <replaceable>time</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>minutes</primary></indexterm>
<indexterm role="cp"><primary>time, in minutes</primary></indexterm>
<synopsis><indexterm role="fn"><primary>CTIME.MINUTES</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CTIME.MINUTES</function> (<emphasis role="arg"><replaceable>time</replaceable></emphasis>)</synopsis>
<blockquote><para>Results in the number of minutes and fractional minutes in <replaceable>time</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>seconds</primary></indexterm>
<indexterm role="cp"><primary>time, in seconds</primary></indexterm>
<synopsis><indexterm role="fn"><primary>CTIME.SECONDS</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CTIME.SECONDS</function> (<emphasis role="arg"><replaceable>time</replaceable></emphasis>)</synopsis>
<blockquote><para>Results in the number of seconds and fractional seconds in <replaceable>time</replaceable>.
(<literal>CTIME.SECONDS</literal> does nothing; <literal>CTIME.SECONDS(<replaceable>x</replaceable>)</literal> is
equivalent to <literal><replaceable>x</replaceable></literal>.)
</para></blockquote>
</sect3>
<sect3 label="7.7.8.4" id="Date-Construction">
<title>Functions that Produce Dates</title>
<indexterm role="cp"><primary>dates, constructing</primary></indexterm>
<indexterm role="cp"><primary>constructing dates</primary></indexterm>

<indexterm role="cp"><primary>arguments, of date construction functions</primary></indexterm>
<para>These functions take numeric arguments and give numeric results that
represent dates.  Arguments taken by these functions are:
</para>
<variablelist><varlistentry><term><replaceable>day</replaceable>
</term><listitem><para>Refers to a day of the month between 1 and 31.  Day 0 is also accepted
and refers to the final day of the previous month.  Days 29, 30, and
31 are accepted even in months that have fewer days and refer to a day
near the beginning of the following month.
</para>
</listitem></varlistentry><varlistentry><term><replaceable>month</replaceable>
</term><listitem><para>Refers to a month of the year between 1 and 12.  Months 0 and 13 are
also accepted and refer to the last month of the preceding year and
the first month of the following year, respectively.
</para>
</listitem></varlistentry><varlistentry><term><replaceable>quarter</replaceable>
</term><listitem><para>Refers to a quarter of the year between 1 and 4.  The quarters of the
year begin on the first day of months 1, 4, 7, and 10.
</para>
</listitem></varlistentry><varlistentry><term><replaceable>week</replaceable>
</term><listitem><para>Refers to a week of the year between 1 and 53.
</para>
</listitem></varlistentry><varlistentry><term><replaceable>yday</replaceable>
</term><listitem><para>Refers to a day of the year between 1 and 366.
</para>
</listitem></varlistentry><varlistentry><term><replaceable>year</replaceable>
</term><listitem><para>Refers to a year, 1582 or greater.  Years between 0 and 99 are treated
according to the epoch set on SET EPOCH, by default beginning 69 years
before the current date (see <link linkend="SET-EPOCH">SET EPOCH</link>).
</para></listitem></varlistentry></variablelist>
<indexterm role="cp"><primary>arguments, invalid</primary></indexterm>
<para>If these functions&#8217; arguments are out-of-range, they are correctly
normalized before conversion to date format.  Non-integers are rounded
toward zero.
</para>
<indexterm role="cp"><primary>day-month-year</primary></indexterm>
<indexterm role="cp"><primary>dates, day-month-year</primary></indexterm>
<synopsis><indexterm role="fn"><primary>DATE.DMY</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>DATE.DMY</function> (<emphasis role="arg"><replaceable>day</replaceable></emphasis>, <emphasis role="arg"><replaceable>month</replaceable></emphasis>, <emphasis role="arg"><replaceable>year</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>DATE.MDY</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>DATE.MDY</function> (<emphasis role="arg"><replaceable>month</replaceable></emphasis>, <emphasis role="arg"><replaceable>day</replaceable></emphasis>, <emphasis role="arg"><replaceable>year</replaceable></emphasis>)</synopsis>
<blockquote><para>Results in a date value corresponding to the midnight before day
<replaceable>day</replaceable> of month <replaceable>month</replaceable> of year <replaceable>year</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>month-year</primary></indexterm>
<indexterm role="cp"><primary>dates, month-year</primary></indexterm>
<synopsis><indexterm role="fn"><primary>DATE.MOYR</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>DATE.MOYR</function> (<emphasis role="arg"><replaceable>month</replaceable></emphasis>, <emphasis role="arg"><replaceable>year</replaceable></emphasis>)</synopsis>
<blockquote><para>Results in a date value corresponding to the midnight before the first
day of month <replaceable>month</replaceable> of year <replaceable>year</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>quarter-year</primary></indexterm>
<indexterm role="cp"><primary>dates, quarter-year</primary></indexterm>
<synopsis><indexterm role="fn"><primary>DATE.QYR</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>DATE.QYR</function> (<emphasis role="arg"><replaceable>quarter</replaceable></emphasis>, <emphasis role="arg"><replaceable>year</replaceable></emphasis>)</synopsis>
<blockquote><para>Results in a date value corresponding to the midnight before the first
day of quarter <replaceable>quarter</replaceable> of year <replaceable>year</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>week-year</primary></indexterm>
<indexterm role="cp"><primary>dates, week-year</primary></indexterm>
<synopsis><indexterm role="fn"><primary>DATE.WKYR</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>DATE.WKYR</function> (<emphasis role="arg"><replaceable>week</replaceable></emphasis>, <emphasis role="arg"><replaceable>year</replaceable></emphasis>)</synopsis>
<blockquote><para>Results in a date value corresponding to the midnight before the first
day of week <replaceable>week</replaceable> of year <replaceable>year</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>year-day</primary></indexterm>
<indexterm role="cp"><primary>dates, year-day</primary></indexterm>
<synopsis><indexterm role="fn"><primary>DATE.YRDAY</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>DATE.YRDAY</function> (<emphasis role="arg"><replaceable>year</replaceable></emphasis>, <emphasis role="arg"><replaceable>yday</replaceable></emphasis>)</synopsis>
<blockquote><para>Results in a date value corresponding to the day
<replaceable>yday</replaceable> of year <replaceable>year</replaceable>.
</para></blockquote>
</sect3>
<sect3 label="7.7.8.5" id="Date-Extraction">
<title>Functions that Examine Dates</title>
<indexterm role="cp"><primary>extraction, of dates</primary></indexterm>
<indexterm role="cp"><primary>date examination</primary></indexterm>

<indexterm role="cp"><primary>arguments, of date extraction functions</primary></indexterm>
<para>These functions take numeric arguments in PSPP date or time
format and give numeric results.  These names are used for arguments:
</para>
<variablelist><varlistentry><term><replaceable>date</replaceable>
</term><listitem><para>A numeric value in PSPP date format.
</para>
</listitem></varlistentry><varlistentry><term><replaceable>time</replaceable>
</term><listitem><para>A numeric value in PSPP time format.
</para>
</listitem></varlistentry><varlistentry><term><replaceable>time-or-date</replaceable>
</term><listitem><para>A numeric value in PSPP time or date format.
</para></listitem></varlistentry></variablelist>
<indexterm role="cp"><primary>days</primary></indexterm>
<indexterm role="cp"><primary>dates, in days</primary></indexterm>
<indexterm role="cp"><primary>time, in days</primary></indexterm>
<synopsis><indexterm role="fn"><primary>XDATE.DATE</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>XDATE.DATE</function> (<emphasis role="arg"><replaceable>time-or-date</replaceable></emphasis>)</synopsis>
<blockquote><para>For a time, results in the time corresponding to the number of whole
days <replaceable>date-or-time</replaceable> includes.  For a date, results in the date
corresponding to the latest midnight at or before <replaceable>date-or-time</replaceable>;
that is, gives the date that <replaceable>date-or-time</replaceable> is in.
</para></blockquote>
<indexterm role="cp"><primary>hours</primary></indexterm>
<indexterm role="cp"><primary>dates, in hours</primary></indexterm>
<indexterm role="cp"><primary>time, in hours</primary></indexterm>
<synopsis><indexterm role="fn"><primary>XDATE.HOUR</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>XDATE.HOUR</function> (<emphasis role="arg"><replaceable>time-or-date</replaceable></emphasis>)</synopsis>
<blockquote><para>For a time, results in the number of whole hours beyond the number of
whole days represented by <replaceable>date-or-time</replaceable>.  For a date, results in
the hour (as an integer between 0 and 23) corresponding to
<replaceable>date-or-time</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>day of the year</primary></indexterm>
<indexterm role="cp"><primary>dates, day of the year</primary></indexterm>
<synopsis><indexterm role="fn"><primary>XDATE.JDAY</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>XDATE.JDAY</function> (<emphasis role="arg"><replaceable>date</replaceable></emphasis>)</synopsis>
<blockquote><para>Results in the day of the year (as an integer between 1 and 366)
corresponding to <replaceable>date</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>day of the month</primary></indexterm>
<indexterm role="cp"><primary>dates, day of the month</primary></indexterm>
<synopsis><indexterm role="fn"><primary>XDATE.MDAY</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>XDATE.MDAY</function> (<emphasis role="arg"><replaceable>date</replaceable></emphasis>)</synopsis>
<blockquote><para>Results in the day of the month (as an integer between 1 and 31)
corresponding to <replaceable>date</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>minutes</primary></indexterm>
<indexterm role="cp"><primary>dates, in minutes</primary></indexterm>
<indexterm role="cp"><primary>time, in minutes</primary></indexterm>
<synopsis><indexterm role="fn"><primary>XDATE.MINUTE</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>XDATE.MINUTE</function> (<emphasis role="arg"><replaceable>time-or-date</replaceable></emphasis>)</synopsis>
<blockquote><para>Results in the number of minutes (as an integer between 0 and 59) after
the last hour in <replaceable>time-or-date</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>months</primary></indexterm>
<indexterm role="cp"><primary>dates, in months</primary></indexterm>
<synopsis><indexterm role="fn"><primary>XDATE.MONTH</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>XDATE.MONTH</function> (<emphasis role="arg"><replaceable>date</replaceable></emphasis>)</synopsis>
<blockquote><para>Results in the month of the year (as an integer between 1 and 12)
corresponding to <replaceable>date</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>quarters</primary></indexterm>
<indexterm role="cp"><primary>dates, in quarters</primary></indexterm>
<synopsis><indexterm role="fn"><primary>XDATE.QUARTER</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>XDATE.QUARTER</function> (<emphasis role="arg"><replaceable>date</replaceable></emphasis>)</synopsis>
<blockquote><para>Results in the quarter of the year (as an integer between 1 and 4)
corresponding to <replaceable>date</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>seconds</primary></indexterm>
<indexterm role="cp"><primary>dates, in seconds</primary></indexterm>
<indexterm role="cp"><primary>time, in seconds</primary></indexterm>
<synopsis><indexterm role="fn"><primary>XDATE.SECOND</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>XDATE.SECOND</function> (<emphasis role="arg"><replaceable>time-or-date</replaceable></emphasis>)</synopsis>
<blockquote><para>Results in the number of whole seconds after the last whole minute (as
an integer between 0 and 59) in <replaceable>time-or-date</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>days</primary></indexterm>
<indexterm role="cp"><primary>times, in days</primary></indexterm>
<synopsis><indexterm role="fn"><primary>XDATE.TDAY</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>XDATE.TDAY</function> (<emphasis role="arg"><replaceable>date</replaceable></emphasis>)</synopsis>
<blockquote><para>Results in the number of whole days from 14 Oct 1582 to <replaceable>date</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>time</primary></indexterm>
<indexterm role="cp"><primary>dates, time of day</primary></indexterm>
<synopsis><indexterm role="fn"><primary>XDATE.TIME</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>XDATE.TIME</function> (<emphasis role="arg"><replaceable>date</replaceable></emphasis>)</synopsis>
<blockquote><para>Results in the time of day at the instant corresponding to <replaceable>date</replaceable>,
as a time value.  This is the number of seconds since
midnight on the day corresponding to <replaceable>date</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>week</primary></indexterm>
<indexterm role="cp"><primary>dates, in weeks</primary></indexterm>
<synopsis><indexterm role="fn"><primary>XDATE.WEEK</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>XDATE.WEEK</function> (<emphasis role="arg"><replaceable>date</replaceable></emphasis>)</synopsis>
<blockquote><para>Results in the week of the year (as an integer between 1 and 53)
corresponding to <replaceable>date</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>day of the week</primary></indexterm>
<indexterm role="cp"><primary>weekday</primary></indexterm>
<indexterm role="cp"><primary>dates, day of the week</primary></indexterm>
<indexterm role="cp"><primary>dates, in weekdays</primary></indexterm>
<synopsis><indexterm role="fn"><primary>XDATE.WKDAY</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>XDATE.WKDAY</function> (<emphasis role="arg"><replaceable>date</replaceable></emphasis>)</synopsis>
<blockquote><para>Results in the day of week (as an integer between 1 and 7) corresponding
to <replaceable>date</replaceable>, where 1 represents Sunday.
</para></blockquote>
<indexterm role="cp"><primary>years</primary></indexterm>
<indexterm role="cp"><primary>dates, in years</primary></indexterm>
<synopsis><indexterm role="fn"><primary>XDATE.YEAR</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>XDATE.YEAR</function> (<emphasis role="arg"><replaceable>date</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns the year (as an integer 1582 or greater) corresponding to
<replaceable>date</replaceable>.
</para></blockquote>
</sect3>
<sect3 label="7.7.8.6" id="Time-and-Date-Arithmetic">
<title>Time and Date Arithmetic</title>

<indexterm role="cp"><primary>time, mathematical properties of</primary></indexterm>
<indexterm role="cp"><primary>mathematics, applied to times &amp; dates</primary></indexterm>
<indexterm role="cp"><primary>dates, mathematical properties of</primary></indexterm>
<para>Ordinary arithmetic operations on dates and times often produce
sensible results.  Adding a time to, or subtracting one from, a date
produces a new date that much earlier or later.  The difference of two
dates yields the time between those dates.  Adding two times produces
the combined time.  Multiplying a time by a scalar produces a time
that many times longer.  Since times and dates are just numbers, the
ordinary addition and subtraction operators are employed for these
purposes.
</para>
<para>Adding two dates does not produce a useful result.
</para>
<para>Dates and times may have very large values.  Thus,
it is not a good idea to take powers of these values; also, the
accuracy of some procedures may be affected.  If necessary, convert
times or dates in seconds to some other unit, like days or years,
before performing analysis.
</para>
<para>PSPP supplies a few functions for date arithmetic:
</para>
<synopsis><indexterm role="fn"><primary>DATEDIFF</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>DATEDIFF</function> (<emphasis role="arg"><replaceable>date2</replaceable></emphasis>, <emphasis role="arg"><replaceable>date1</replaceable></emphasis>, <emphasis role="arg"><replaceable>unit</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns the span of time from <replaceable>date1</replaceable> to <replaceable>date2</replaceable> in terms of
<replaceable>unit</replaceable>, which must be a quoted string, one of &#8216;<literal>years</literal>&#8217;,
&#8216;<literal>quarters</literal>&#8217;, &#8216;<literal>months</literal>&#8217;, &#8216;<literal>weeks</literal>&#8217;, &#8216;<literal>days</literal>&#8217;,
&#8216;<literal>hours</literal>&#8217;, &#8216;<literal>minutes</literal>&#8217;, and &#8216;<literal>seconds</literal>&#8217;.  The result is an
integer, truncated toward zero.
</para>
<para>One year is considered to span from a given date to the same month,
day, and time of day the next year.  Thus, from Jan.&#160;1 of one
year to Jan.&#160;1 the next year is considered to be a full year, but
Feb.&#160;29 of a leap year to the following Feb.&#160;28 is not.
Similarly, one month spans from a given day of the month to the same
day of the following month.  Thus, there is never a full month from
Jan.&#160;31 of a given year to any day in the following February.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>DATESUM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>DATESUM</function> (<emphasis role="arg"><replaceable>date</replaceable></emphasis>, <emphasis role="arg"><replaceable>quantity</replaceable></emphasis>, <emphasis role="arg"><replaceable>unit</replaceable></emphasis>[, <emphasis role="arg"><replaceable>method</replaceable></emphasis>])</synopsis>
<blockquote><para>Returns <replaceable>date</replaceable> advanced by the given <replaceable>quantity</replaceable> of the
specified <replaceable>unit</replaceable>, which must be one of the strings &#8216;<literal>years</literal>&#8217;,
&#8216;<literal>quarters</literal>&#8217;, &#8216;<literal>months</literal>&#8217;, &#8216;<literal>weeks</literal>&#8217;, &#8216;<literal>days</literal>&#8217;,
&#8216;<literal>hours</literal>&#8217;, &#8216;<literal>minutes</literal>&#8217;, and &#8216;<literal>seconds</literal>&#8217;.
</para>
<para>When <replaceable>unit</replaceable> is &#8216;<literal>years</literal>&#8217;, &#8216;<literal>quarters</literal>&#8217;, or &#8216;<literal>months</literal>&#8217;,
only the integer part of <replaceable>quantity</replaceable> is considered.  Adding one of
these units can cause the day of the month to exceed the number of
days in the month.  In this case, the <replaceable>method</replaceable> comes into
play: if it is omitted or specified as &#8216;<literal>closest</literal>&#8217; (as a quoted
string), then the resulting day is the last day of the month;
otherwise, if it is specified as &#8216;<literal>rollover</literal>&#8217;, then the extra days
roll over into the following month.
</para>
<para>When <replaceable>unit</replaceable> is &#8216;<literal>weeks</literal>&#8217;, &#8216;<literal>days</literal>&#8217;, &#8216;<literal>hours</literal>&#8217;,
&#8216;<literal>minutes</literal>&#8217;, or &#8216;<literal>seconds</literal>&#8217;, the <replaceable>quantity</replaceable> is not rounded
to an integer and <replaceable>method</replaceable>, if specified, is ignored.
</para></blockquote>
</sect3>
</sect2>
<sect2 label="7.7.9" id="Miscellaneous-Functions">
<title>Miscellaneous Functions</title>
<indexterm role="cp"><primary>functions, miscellaneous</primary></indexterm>

<indexterm role="cp"><primary>cross-case function</primary></indexterm>
<indexterm role="cp"><primary>function, cross-case</primary></indexterm>
<synopsis><indexterm role="fn"><primary>LAG</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>LAG</function> (<emphasis role="arg"><replaceable>variable</replaceable></emphasis>[, <emphasis role="arg"><replaceable>n</replaceable></emphasis>])</synopsis>
<blockquote><anchor id="LAG"/>
<para><replaceable>variable</replaceable> must be a numeric or string variable name.  <literal>LAG</literal>
yields the value of that variable for the case <replaceable>n</replaceable> before the
current one.  Results in system-missing (for numeric variables) or
blanks (for string variables) for the first <replaceable>n</replaceable> cases.
</para>
<para><literal>LAG</literal> obtains values from the cases that become the new active
dataset
after a procedure executes.  Thus, <literal>LAG</literal> will not return values
from cases dropped by transformations such as <literal>SELECT IF</literal>, and
transformations like <literal>COMPUTE</literal> that modify data will change the
values returned by <literal>LAG</literal>.  These are both the case whether these
transformations precede or follow the use of <literal>LAG</literal>.
</para>
<para>If <literal>LAG</literal> is used before <literal>TEMPORARY</literal>, then the values it returns
are those in cases just before <literal>TEMPORARY</literal>.  <literal>LAG</literal> may not be
used after <literal>TEMPORARY</literal>.
</para>
<para>If omitted, <replaceable>ncases</replaceable> defaults to 1.  Otherwise, <replaceable>ncases</replaceable> must
be a small positive constant integer.  There is no explicit limit, but
use of a large value will increase memory consumption.
</para></blockquote>
<indexterm role="cp"><primary>date, Julian</primary></indexterm>
<indexterm role="cp"><primary>Julian date</primary></indexterm>
<synopsis><indexterm role="fn"><primary>YRMODA</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>YRMODA</function> (<emphasis role="arg"><replaceable>year</replaceable></emphasis>, <emphasis role="arg"><replaceable>month</replaceable></emphasis>, <emphasis role="arg"><replaceable>day</replaceable></emphasis>)</synopsis>
<blockquote><para><replaceable>year</replaceable> is a year, either between 0 and 99 or at least 1582.
Unlike other PSPP date functions, years between 0 and 99 always
correspond to 1900 through 1999.  <replaceable>month</replaceable> is a month between 1 and
13.  <replaceable>day</replaceable> is a day between 0 and 31.  A <replaceable>day</replaceable> of 0 refers to
the last day of the previous month, and a <replaceable>month</replaceable> of 13 refers to
the first month of the next year.  <replaceable>year</replaceable> must be in range.
<replaceable>year</replaceable>, <replaceable>month</replaceable>, and <replaceable>day</replaceable> must all be integers.
</para>
<para><literal>YRMODA</literal> results in the number of days between 15 Oct 1582 and
the date specified, plus one.  The date passed to <literal>YRMODA</literal> must be
on or after 15 Oct 1582.  15 Oct 1582 has a value of 1.
</para></blockquote>
<indexterm role="cp"><primary>value label</primary></indexterm>
<synopsis><indexterm role="fn"><primary>(<replaceable>variable</replaceable>)</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue>VALUELABEL</returnvalue> <function>(<replaceable>variable</replaceable>)</function></synopsis>
<blockquote><para>Returns a string matching the label associated with the current value
of <replaceable>variable</replaceable>.  If the current value of <replaceable>variable</replaceable> has no
associated label, then this function returns the empty string.
<replaceable>variable</replaceable> may be a numeric or string variable.
</para></blockquote>
</sect2>
<sect2 label="7.7.10" id="Statistical-Distribution-Functions">
<title>Statistical Distribution Functions</title>

<para>PSPP can calculate several functions of standard statistical
distributions.  These functions are named systematically based on the
function and the distribution.  The table below describes the
statistical distribution functions in general:
</para>
<variablelist><varlistentry><term>PDF.<replaceable>dist</replaceable> (<replaceable>x</replaceable>[, <replaceable>param</replaceable>&#8230;])
</term><listitem><para>Probability density function for <replaceable>dist</replaceable>.  The domain of <replaceable>x</replaceable>
depends on <replaceable>dist</replaceable>.  For continuous distributions, the result is
the density of the probability function at <replaceable>x</replaceable>, and the range is
nonnegative real numbers.  For discrete distributions, the result is
the probability of <replaceable>x</replaceable>.
</para>
</listitem></varlistentry><varlistentry><term>CDF.<replaceable>dist</replaceable> (<replaceable>x</replaceable>[, <replaceable>param</replaceable>&#8230;])
</term><listitem><para>Cumulative distribution function for <replaceable>dist</replaceable>, that is, the
probability that a random variate drawn from the distribution is less
than <replaceable>x</replaceable>.  The domain of <replaceable>x</replaceable> depends <replaceable>dist</replaceable>.  The result is
a probability.
</para>
</listitem></varlistentry><varlistentry><term>SIG.<replaceable>dist</replaceable> (<replaceable>x</replaceable>[, <replaceable>param</replaceable>&#8230;)
</term><listitem><para>Tail probability function for <replaceable>dist</replaceable>, that is, the probability
that a random variate drawn from the distribution is greater than
<replaceable>x</replaceable>.  The domain of <replaceable>x</replaceable> depends <replaceable>dist</replaceable>.  The result is a
probability.  Only a few distributions include an <literal>SIG</literal> function.
</para>
</listitem></varlistentry><varlistentry><term>IDF.<replaceable>dist</replaceable> (<replaceable>p</replaceable>[, <replaceable>param</replaceable>&#8230;])
</term><listitem><para>Inverse distribution function for <replaceable>dist</replaceable>, the value of <replaceable>x</replaceable> for
which the CDF would yield <replaceable>p</replaceable>.  The value of <replaceable>p</replaceable> is a
probability.  The range depends on <replaceable>dist</replaceable> and is identical to the
domain for the corresponding CDF.
</para>
</listitem></varlistentry><varlistentry><term>RV.<replaceable>dist</replaceable> ([<replaceable>param</replaceable>&#8230;])
</term><listitem><para>Random variate function for <replaceable>dist</replaceable>.  The range depends on the
distribution.
</para>
</listitem></varlistentry><varlistentry><term>NPDF.<replaceable>dist</replaceable> (<replaceable>x</replaceable>[, <replaceable>param</replaceable>&#8230;])
</term><listitem><para>Noncentral probability density function.  The result is the density of
the given noncentral distribution at <replaceable>x</replaceable>.  The domain of <replaceable>x</replaceable>
depends on <replaceable>dist</replaceable>.  The range is nonnegative real numbers.  Only a
few distributions include an <literal>NPDF</literal> function.
</para>
</listitem></varlistentry><varlistentry><term>NCDF.<replaceable>dist</replaceable> (<replaceable>x</replaceable>[, <replaceable>param</replaceable>&#8230;])
</term><listitem><para>Noncentral cumulative distribution function for <replaceable>dist</replaceable>, that is,
the probability that a random variate drawn from the given noncentral
distribution is less than <replaceable>x</replaceable>.  The domain of <replaceable>x</replaceable> depends
<replaceable>dist</replaceable>.  The result is a probability.  Only a few distributions
include an NCDF function.
</para></listitem></varlistentry></variablelist>
<para>The individual distributions are described individually below.
</para>

<sect3 label="7.7.10.1" id="Continuous-Distributions">
<title>Continuous Distributions</title>

<para>The following continuous distributions are available:
</para>
<synopsis><indexterm role="fn"><primary>PDF.BETA</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.BETA</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.BETA</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.BETA</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.BETA</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.BETA</function> (<emphasis role="arg"><replaceable>p</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.BETA</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.BETA</function> (<emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>NPDF.BETA</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>NPDF.BETA</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>, <emphasis role="arg"><replaceable>lambda</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>NCDF.BETA</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>NCDF.BETA</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>, <emphasis role="arg"><replaceable>lambda</replaceable></emphasis>)</synopsis>
<blockquote><para>Beta distribution with shape parameters <replaceable>a</replaceable> and <replaceable>b</replaceable>.  The
noncentral distribution takes an additional parameter <replaceable>lambda</replaceable>.
Constraints: <replaceable>a</replaceable> &gt; 0, <replaceable>b</replaceable> &gt; 0, <replaceable>lambda</replaceable> &gt;= 0, 0 &lt;= <replaceable>x</replaceable>
&lt;= 1, 0 &lt;= <replaceable>p</replaceable> &lt;= 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.BVNOR</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.BVNOR</function> (<emphasis role="arg"><replaceable>x0</replaceable></emphasis>, <emphasis role="arg"><replaceable>x1</replaceable></emphasis>, <emphasis role="arg"><replaceable>rho</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.BVNOR</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.BVNOR</function> (<emphasis role="arg"><replaceable>x0</replaceable></emphasis>, <emphasis role="arg"><replaceable>x1</replaceable></emphasis>, <emphasis role="arg"><replaceable>rho</replaceable></emphasis>)</synopsis>
<blockquote><para>Bivariate normal distribution of two standard normal variables with
correlation coefficient <replaceable>rho</replaceable>.  Two variates <replaceable>x0</replaceable> and <replaceable>x1</replaceable>
must be provided.  Constraints: 0 &lt;= <replaceable>rho</replaceable> &lt;= 1, 0 &lt;= <replaceable>p</replaceable> &lt;= 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.CAUCHY</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.CAUCHY</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.CAUCHY</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.CAUCHY</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.CAUCHY</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.CAUCHY</function> (<emphasis role="arg"><replaceable>p</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.CAUCHY</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.CAUCHY</function> (<emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<blockquote><para>Cauchy distribution with location parameter <replaceable>a</replaceable> and scale
parameter <replaceable>b</replaceable>.  Constraints: <replaceable>b</replaceable> &gt; 0, 0 &lt; <replaceable>p</replaceable> &lt; 1.
</para></blockquote>
<!-- @deftypefn {Function} {} PDF.CHISQ (@var{x}, @var{df}) -->
<synopsis><indexterm role="fn"><primary>CDF.CHISQ</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.CHISQ</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>df</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>SIG.CHISQ</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>SIG.CHISQ</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>df</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.CHISQ</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.CHISQ</function> (<emphasis role="arg"><replaceable>p</replaceable></emphasis>, <emphasis role="arg"><replaceable>df</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.CHISQ</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.CHISQ</function> (<emphasis role="arg"><replaceable>df</replaceable></emphasis>)</synopsis>
<!-- @deftypefnx {Function} {} NPDF.CHISQ (@var{x}, @var{df}, @var{lambda}) -->
<synopsis><indexterm role="fn"><primary>NCDF.CHISQ</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>NCDF.CHISQ</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>df</replaceable></emphasis>, <emphasis role="arg"><replaceable>lambda</replaceable></emphasis>)</synopsis>
<blockquote><para>Chi-squared distribution with <replaceable>df</replaceable> degrees of freedom.  The
noncentral distribution takes an additional parameter <replaceable>lambda</replaceable>.
Constraints: <replaceable>df</replaceable> &gt; 0, <replaceable>lambda</replaceable> &gt; 0, <replaceable>x</replaceable> &gt;= 0, 0 &lt;=
<replaceable>p</replaceable> &lt; 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.EXP</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.EXP</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.EXP</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.EXP</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.EXP</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.EXP</function> (<emphasis role="arg"><replaceable>p</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.EXP</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.EXP</function> (<emphasis role="arg"><replaceable>a</replaceable></emphasis>)</synopsis>
<blockquote><para>Exponential distribution with scale parameter <replaceable>a</replaceable>.  The inverse of
<replaceable>a</replaceable> represents the rate of decay.  Constraints: <replaceable>a</replaceable> &gt; 0,
<replaceable>x</replaceable> &gt;= 0, 0 &lt;= <replaceable>p</replaceable> &lt; 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.XPOWER</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.XPOWER</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.XPOWER</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.XPOWER</function> (<emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<blockquote><para>Exponential power distribution with positive scale parameter <replaceable>a</replaceable>
and nonnegative power parameter <replaceable>b</replaceable>.  Constraints: <replaceable>a</replaceable> &gt; 0,
<replaceable>b</replaceable> &gt;= 0, <replaceable>x</replaceable> &gt;= 0, 0 &lt;= <replaceable>p</replaceable> &lt;= 1.  This distribution is a
PSPP extension.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.F</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.F</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>df1</replaceable></emphasis>, <emphasis role="arg"><replaceable>df2</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.F</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.F</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>df1</replaceable></emphasis>, <emphasis role="arg"><replaceable>df2</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>SIG.F</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>SIG.F</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>df1</replaceable></emphasis>, <emphasis role="arg"><replaceable>df2</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.F</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.F</function> (<emphasis role="arg"><replaceable>p</replaceable></emphasis>, <emphasis role="arg"><replaceable>df1</replaceable></emphasis>, <emphasis role="arg"><replaceable>df2</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.F</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.F</function> (<emphasis role="arg"><replaceable>df1</replaceable></emphasis>, <emphasis role="arg"><replaceable>df2</replaceable></emphasis>)</synopsis>
<blockquote><!-- @deftypefnx {Function} {} NPDF.F (@var{x}, @var{df1}, @var{df2}, @var{lambda}) -->
<!-- @deftypefnx {Function} {} NCDF.F (@var{x}, @var{df1}, @var{df2}, @var{lambda}) -->
<para>F-distribution of two chi-squared deviates with <replaceable>df1</replaceable> and
<replaceable>df2</replaceable> degrees of freedom.  The noncentral distribution takes an
additional parameter <replaceable>lambda</replaceable>.  Constraints: <replaceable>df1</replaceable> &gt; 0,
<replaceable>df2</replaceable> &gt; 0, <replaceable>lambda</replaceable> &gt;= 0, <replaceable>x</replaceable> &gt;= 0, 0 &lt;= <replaceable>p</replaceable> &lt; 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.GAMMA</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.GAMMA</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.GAMMA</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.GAMMA</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.GAMMA</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.GAMMA</function> (<emphasis role="arg"><replaceable>p</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.GAMMA</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.GAMMA</function> (<emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<blockquote><para>Gamma distribution with shape parameter <replaceable>a</replaceable> and scale parameter
<replaceable>b</replaceable>.  Constraints: <replaceable>a</replaceable> &gt; 0, <replaceable>b</replaceable> &gt; 0, <replaceable>x</replaceable> &gt;= 0, 0 &lt;=
<replaceable>p</replaceable> &lt; 1.
</para></blockquote>
<!-- @deftypefn {Function} {} PDF.HALFNRM (@var{x}, @var{a}, @var{b}) -->
<!-- @deftypefnx {Function} {} CDF.HALFNRM (@var{x}, @var{a}, @var{b}) -->
<!-- @deftypefnx {Function} {} IDF.HALFNRM (@var{p}, @var{a}, @var{b}) -->
<!-- @deftypefnx {Function} {} RV.HALFNRM (@var{a}, @var{b}) -->
<!-- Half-normal distribution with location parameter @var{a} and shape -->
<!-- parameter @var{b}.  Constraints: @var{b} > 0, 0 < @var{p} < 1. -->
<!-- @end deftypefn -->

<!-- @deftypefn {Function} {} PDF.IGAUSS (@var{x}, @var{a}, @var{b}) -->
<!-- @deftypefnx {Function} {} CDF.IGAUSS (@var{x}, @var{a}, @var{b}) -->
<!-- @deftypefnx {Function} {} IDF.IGAUSS (@var{p}, @var{a}, @var{b}) -->
<!-- @deftypefnx {Function} {} RV.IGAUSS (@var{a}, @var{b}) -->
<!-- Inverse Gaussian distribution with parameters @var{a} and @var{b}. -->
<!-- Constraints: @var{a} > 0, @var{b} > 0, @var{x} > 0, 0 <= @var{p} < 1. -->
<!-- @end deftypefn -->

<synopsis><indexterm role="fn"><primary>PDF.LANDAU</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.LANDAU</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.LANDAU</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.LANDAU</function> ()</synopsis>
<blockquote><para>Landau distribution.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.LAPLACE</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.LAPLACE</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.LAPLACE</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.LAPLACE</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.LAPLACE</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.LAPLACE</function> (<emphasis role="arg"><replaceable>p</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.LAPLACE</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.LAPLACE</function> (<emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<blockquote><para>Laplace distribution with location parameter <replaceable>a</replaceable> and scale
parameter <replaceable>b</replaceable>.  Constraints: <replaceable>b</replaceable> &gt; 0, 0 &lt; <replaceable>p</replaceable> &lt; 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>RV.LEVY</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.LEVY</function> (<emphasis role="arg"><replaceable>c</replaceable></emphasis>, <emphasis role="arg"><replaceable>alpha</replaceable></emphasis>)</synopsis>
<blockquote><para>Levy symmetric alpha-stable distribution with scale <replaceable>c</replaceable> and
exponent <replaceable>alpha</replaceable>.  Constraints: 0 &lt; <replaceable>alpha</replaceable> &lt;= 2.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>RV.LVSKEW</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.LVSKEW</function> (<emphasis role="arg"><replaceable>c</replaceable></emphasis>, <emphasis role="arg"><replaceable>alpha</replaceable></emphasis>, <emphasis role="arg"><replaceable>beta</replaceable></emphasis>)</synopsis>
<blockquote><para>Levy skew alpha-stable distribution with scale <replaceable>c</replaceable>, exponent
<replaceable>alpha</replaceable>, and skewness parameter <replaceable>beta</replaceable>.  Constraints: 0 &lt;
<replaceable>alpha</replaceable> &lt;= 2, -1 &lt;= <replaceable>beta</replaceable> &lt;= 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.LOGISTIC</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.LOGISTIC</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.LOGISTIC</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.LOGISTIC</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.LOGISTIC</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.LOGISTIC</function> (<emphasis role="arg"><replaceable>p</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.LOGISTIC</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.LOGISTIC</function> (<emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<blockquote><para>Logistic distribution with location parameter <replaceable>a</replaceable> and scale
parameter <replaceable>b</replaceable>.  Constraints: <replaceable>b</replaceable> &gt; 0, 0 &lt; <replaceable>p</replaceable> &lt; 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.LNORMAL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.LNORMAL</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.LNORMAL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.LNORMAL</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.LNORMAL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.LNORMAL</function> (<emphasis role="arg"><replaceable>p</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.LNORMAL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.LNORMAL</function> (<emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<blockquote><para>Lognormal distribution with parameters <replaceable>a</replaceable> and <replaceable>b</replaceable>.
Constraints: <replaceable>a</replaceable> &gt; 0, <replaceable>b</replaceable> &gt; 0, <replaceable>x</replaceable> &gt;= 0, 0 &lt;= <replaceable>p</replaceable> &lt; 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.NORMAL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.NORMAL</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>mu</replaceable></emphasis>, <emphasis role="arg"><replaceable>sigma</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.NORMAL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.NORMAL</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>mu</replaceable></emphasis>, <emphasis role="arg"><replaceable>sigma</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.NORMAL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.NORMAL</function> (<emphasis role="arg"><replaceable>p</replaceable></emphasis>, <emphasis role="arg"><replaceable>mu</replaceable></emphasis>, <emphasis role="arg"><replaceable>sigma</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.NORMAL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.NORMAL</function> (<emphasis role="arg"><replaceable>mu</replaceable></emphasis>, <emphasis role="arg"><replaceable>sigma</replaceable></emphasis>)</synopsis>
<blockquote><para>Normal distribution with mean <replaceable>mu</replaceable> and standard deviation
<replaceable>sigma</replaceable>.  Constraints: <replaceable>b</replaceable> &gt; 0, 0 &lt; <replaceable>p</replaceable> &lt; 1.  Three
additional functions are available as shorthand:
</para>
<synopsis><indexterm role="fn"><primary>CDFNORM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDFNORM</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>)</synopsis>
<blockquote><para>Equivalent to CDF.NORMAL(<replaceable>x</replaceable>, 0, 1).
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PROBIT</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PROBIT</function> (<emphasis role="arg"><replaceable>p</replaceable></emphasis>)</synopsis>
<blockquote><para>Equivalent to IDF.NORMAL(<replaceable>p</replaceable>, 0, 1).
</para></blockquote>
<synopsis><indexterm role="fn"><primary>NORMAL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>NORMAL</function> (<emphasis role="arg"><replaceable>sigma</replaceable></emphasis>)</synopsis>
<blockquote><para>Equivalent to RV.NORMAL(0, <replaceable>sigma</replaceable>).
</para></blockquote></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.NTAIL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.NTAIL</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>sigma</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.NTAIL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.NTAIL</function> (<emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>sigma</replaceable></emphasis>)</synopsis>
<blockquote><para>Normal tail distribution with lower limit <replaceable>a</replaceable> and standard
deviation <replaceable>sigma</replaceable>.  This distribution is a PSPP extension.
Constraints: <replaceable>a</replaceable> &gt; 0, <replaceable>x</replaceable> &gt; <replaceable>a</replaceable>, 0 &lt; <replaceable>p</replaceable> &lt; 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.PARETO</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.PARETO</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.PARETO</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.PARETO</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.PARETO</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.PARETO</function> (<emphasis role="arg"><replaceable>p</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.PARETO</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.PARETO</function> (<emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<blockquote><para>Pareto distribution with threshold parameter <replaceable>a</replaceable> and shape
parameter <replaceable>b</replaceable>.  Constraints: <replaceable>a</replaceable> &gt; 0, <replaceable>b</replaceable> &gt; 0, <replaceable>x</replaceable> &gt;=
<replaceable>a</replaceable>, 0 &lt;= <replaceable>p</replaceable> &lt; 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.RAYLEIGH</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.RAYLEIGH</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>sigma</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.RAYLEIGH</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.RAYLEIGH</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>sigma</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.RAYLEIGH</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.RAYLEIGH</function> (<emphasis role="arg"><replaceable>p</replaceable></emphasis>, <emphasis role="arg"><replaceable>sigma</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.RAYLEIGH</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.RAYLEIGH</function> (<emphasis role="arg"><replaceable>sigma</replaceable></emphasis>)</synopsis>
<blockquote><para>Rayleigh distribution with scale parameter <replaceable>sigma</replaceable>.  This
distribution is a PSPP extension.  Constraints: <replaceable>sigma</replaceable> &gt; 0,
<replaceable>x</replaceable> &gt; 0.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.RTAIL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.RTAIL</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>sigma</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.RTAIL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.RTAIL</function> (<emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>sigma</replaceable></emphasis>)</synopsis>
<blockquote><para>Rayleigh tail distribution with lower limit <replaceable>a</replaceable> and scale
parameter <replaceable>sigma</replaceable>.  This distribution is a PSPP extension.
Constraints: <replaceable>a</replaceable> &gt; 0, <replaceable>sigma</replaceable> &gt; 0, <replaceable>x</replaceable> &gt; <replaceable>a</replaceable>.
</para></blockquote>
<!-- @deftypefn {Function} {} CDF.SMOD (@var{x}, @var{a}, @var{b}) -->
<!-- @deftypefnx {Function} {} IDF.SMOD (@var{p}, @var{a}, @var{b}) -->
<!-- Studentized maximum modulus distribution with parameters @var{a} and -->
<!-- @var{b}.  Constraints: @var{a} > 0, @var{b} > 0, @var{x} > 0, 0 <= -->
<!-- @var{p} < 1. -->
<!-- @end deftypefn -->

<!-- @deftypefn {Function} {} CDF.SRANGE (@var{x}, @var{a}, @var{b}) -->
<!-- @deftypefnx {Function} {} IDF.SRANGE (@var{p}, @var{a}, @var{b}) -->
<!-- Studentized range distribution with parameters @var{a} and @var{b}. -->
<!-- Constraints:  @var{a} >= 1, @var{b} >= 1, @var{x} > 0, 0 <= @var{p} < -->
<!-- 1. -->
<!-- @end deftypefn -->

<synopsis><indexterm role="fn"><primary>PDF.T</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.T</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>df</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.T</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.T</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>df</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.T</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.T</function> (<emphasis role="arg"><replaceable>p</replaceable></emphasis>, <emphasis role="arg"><replaceable>df</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.T</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.T</function> (<emphasis role="arg"><replaceable>df</replaceable></emphasis>)</synopsis>
<blockquote><!-- @deftypefnx {Function} {} NPDF.T (@var{x}, @var{df}, @var{lambda}) -->
<!-- @deftypefnx {Function} {} NCDF.T (@var{x}, @var{df}, @var{lambda}) -->
<para>T-distribution with <replaceable>df</replaceable> degrees of freedom.  The noncentral
distribution takes an additional parameter <replaceable>lambda</replaceable>.  Constraints:
<replaceable>df</replaceable> &gt; 0, 0 &lt; <replaceable>p</replaceable> &lt; 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.T1G</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.T1G</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.T1G</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.T1G</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.T1G</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.T1G</function> (<emphasis role="arg"><replaceable>p</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<blockquote><para>Type-1 Gumbel distribution with parameters <replaceable>a</replaceable> and <replaceable>b</replaceable>.  This
distribution is a PSPP extension.  Constraints: 0 &lt; <replaceable>p</replaceable> &lt; 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.T2G</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.T2G</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.T2G</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.T2G</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.T2G</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.T2G</function> (<emphasis role="arg"><replaceable>p</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<blockquote><para>Type-2 Gumbel distribution with parameters <replaceable>a</replaceable> and <replaceable>b</replaceable>.  This
distribution is a PSPP extension.  Constraints: <replaceable>x</replaceable> &gt; 0, 0 &lt;
<replaceable>p</replaceable> &lt; 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.UNIFORM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.UNIFORM</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.UNIFORM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.UNIFORM</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.UNIFORM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.UNIFORM</function> (<emphasis role="arg"><replaceable>p</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.UNIFORM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.UNIFORM</function> (<emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<blockquote><para>Uniform distribution with parameters <replaceable>a</replaceable> and <replaceable>b</replaceable>.
Constraints: <replaceable>a</replaceable> &lt;= <replaceable>x</replaceable> &lt;= <replaceable>b</replaceable>, 0 &lt;= <replaceable>p</replaceable> &lt;= 1.  An
additional function is available as shorthand:
</para>
<synopsis><indexterm role="fn"><primary>UNIFORM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>UNIFORM</function> (<emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<blockquote><para>Equivalent to RV.UNIFORM(0, <replaceable>b</replaceable>).
</para></blockquote></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.WEIBULL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.WEIBULL</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.WEIBULL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.WEIBULL</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.WEIBULL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.WEIBULL</function> (<emphasis role="arg"><replaceable>p</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.WEIBULL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.WEIBULL</function> (<emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>)</synopsis>
<blockquote><para>Weibull distribution with parameters <replaceable>a</replaceable> and <replaceable>b</replaceable>.
Constraints: <replaceable>a</replaceable> &gt; 0, <replaceable>b</replaceable> &gt; 0, <replaceable>x</replaceable> &gt;= 0, 0 &lt;= <replaceable>p</replaceable> &lt; 1.
</para></blockquote>
</sect3>
<sect3 label="7.7.10.2" id="Discrete-Distributions">
<title>Discrete Distributions</title>

<para>The following discrete distributions are available:
</para>
<synopsis><indexterm role="fn"><primary>PDF.BERNOULLI</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.BERNOULLI</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.BERNOULLI</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.BERNOULLI</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>p</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.BERNOULLI</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.BERNOULLI</function> (<emphasis role="arg"><replaceable>p</replaceable></emphasis>)</synopsis>
<blockquote><para>Bernoulli distribution with probability of success <replaceable>p</replaceable>.
Constraints: <replaceable>x</replaceable> = 0 or 1, 0 &lt;= <replaceable>p</replaceable> &lt;= 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.BINOM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.BINOM</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>n</replaceable></emphasis>, <emphasis role="arg"><replaceable>p</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.BINOM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.BINOM</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>n</replaceable></emphasis>, <emphasis role="arg"><replaceable>p</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.BINOM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.BINOM</function> (<emphasis role="arg"><replaceable>n</replaceable></emphasis>, <emphasis role="arg"><replaceable>p</replaceable></emphasis>)</synopsis>
<blockquote><para>Binomial distribution with <replaceable>n</replaceable> trials and probability of success
<replaceable>p</replaceable>.  Constraints: integer <replaceable>n</replaceable> &gt; 0, 0 &lt;= <replaceable>p</replaceable> &lt;= 1, integer
<replaceable>x</replaceable> &lt;= <replaceable>n</replaceable>.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.GEOM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.GEOM</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>n</replaceable></emphasis>, <emphasis role="arg"><replaceable>p</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.GEOM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.GEOM</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>n</replaceable></emphasis>, <emphasis role="arg"><replaceable>p</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.GEOM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.GEOM</function> (<emphasis role="arg"><replaceable>n</replaceable></emphasis>, <emphasis role="arg"><replaceable>p</replaceable></emphasis>)</synopsis>
<blockquote><para>Geometric distribution with probability of success <replaceable>p</replaceable>.
Constraints: 0 &lt;= <replaceable>p</replaceable> &lt;= 1, integer <replaceable>x</replaceable> &gt; 0.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.HYPER</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.HYPER</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>, <emphasis role="arg"><replaceable>c</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.HYPER</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.HYPER</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>, <emphasis role="arg"><replaceable>c</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.HYPER</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.HYPER</function> (<emphasis role="arg"><replaceable>a</replaceable></emphasis>, <emphasis role="arg"><replaceable>b</replaceable></emphasis>, <emphasis role="arg"><replaceable>c</replaceable></emphasis>)</synopsis>
<blockquote><para>Hypergeometric distribution when <replaceable>b</replaceable> objects out of <replaceable>a</replaceable> are
drawn and <replaceable>c</replaceable> of the available objects are distinctive.
Constraints: integer <replaceable>a</replaceable> &gt; 0, integer <replaceable>b</replaceable> &lt;= <replaceable>a</replaceable>, integer
<replaceable>c</replaceable> &lt;= <replaceable>a</replaceable>, integer <replaceable>x</replaceable> &gt;= 0.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.LOG</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.LOG</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>p</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.LOG</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.LOG</function> (<emphasis role="arg"><replaceable>p</replaceable></emphasis>)</synopsis>
<blockquote><para>Logarithmic distribution with probability parameter <replaceable>p</replaceable>.
Constraints: 0 &lt;= <replaceable>p</replaceable> &lt; 1, <replaceable>x</replaceable> &gt;= 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.NEGBIN</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.NEGBIN</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>n</replaceable></emphasis>, <emphasis role="arg"><replaceable>p</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.NEGBIN</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.NEGBIN</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>n</replaceable></emphasis>, <emphasis role="arg"><replaceable>p</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.NEGBIN</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.NEGBIN</function> (<emphasis role="arg"><replaceable>n</replaceable></emphasis>, <emphasis role="arg"><replaceable>p</replaceable></emphasis>)</synopsis>
<blockquote><para>Negative binomial distribution with number of successes parameter
<replaceable>n</replaceable> and probability of success parameter <replaceable>p</replaceable>.  Constraints:
integer <replaceable>n</replaceable> &gt;= 0, 0 &lt; <replaceable>p</replaceable> &lt;= 1, integer <replaceable>x</replaceable> &gt;= 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.POISSON</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.POISSON</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>mu</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.POISSON</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.POISSON</function> (<emphasis role="arg"><replaceable>x</replaceable></emphasis>, <emphasis role="arg"><replaceable>mu</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.POISSON</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.POISSON</function> (<emphasis role="arg"><replaceable>mu</replaceable></emphasis>)</synopsis>
<blockquote><para>Poisson distribution with mean <replaceable>mu</replaceable>.  Constraints: <replaceable>mu</replaceable> &gt; 0,
integer <replaceable>x</replaceable> &gt;= 0.
</para></blockquote>
</sect3>
</sect2>
</sect1>
<sect1 label="7.8" id="Order-of-Operations">
<title>Operator Precedence</title>
<indexterm role="cp"><primary>operator precedence</primary></indexterm>
<indexterm role="cp"><primary>precedence, operator</primary></indexterm>
<indexterm role="cp"><primary>order of operations</primary></indexterm>
<indexterm role="cp"><primary>operations, order of</primary></indexterm>

<para>The following table describes operator precedence.  Smaller-numbered
levels in the table have higher precedence.  Within a level,
operations are always performed from left to right.  The first
occurrence of &#8216;<literal>-</literal>&#8217; represents unary negation, the second binary
subtraction.
</para>
<orderedlist numeration="arabic"><listitem><para><literal>()</literal>
</para></listitem><listitem><para><literal>**</literal>
</para></listitem><listitem><para><literal>-</literal>
</para></listitem><listitem><para><literal>*  /</literal>
</para></listitem><listitem><para><literal>+  -</literal>
</para></listitem><listitem><para><literal>=  &gt;=  &gt;  &lt;=  &lt;  &lt;&gt;</literal>
</para></listitem><listitem><para><literal>NOT</literal>
</para></listitem><listitem><para><literal>AND</literal>
</para></listitem><listitem><para><literal>OR</literal>
</para></listitem></orderedlist><!-- PSPP - a program for statistical analysis. -->
<!-- Copyright (C) 2017, 2020 Free Software Foundation, Inc. -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.3 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<!-- A copy of the license is included in the section entitled "GNU -->
<!-- Free Documentation License". -->
<!-- -->
<!-- (modify-syntax-entry ?_ "w") -->
<!-- (modify-syntax-entry ?' "'") -->
<!-- (modify-syntax-entry ?@ "'") -->


</sect1>
</chapter>
<chapter label="8" id="Data-Input-and-Output">
<title>Data Input and Output</title>
<indexterm role="cp"><primary>input</primary></indexterm>
<indexterm role="cp"><primary>output</primary></indexterm>
<indexterm role="cp"><primary>data</primary></indexterm>
<indexterm role="cp"><primary>cases</primary></indexterm>
<indexterm role="cp"><primary>observations</primary></indexterm>

<para>Data are the focus of the PSPP language.
Each datum  belongs to a <firstterm>case</firstterm> (also called an <firstterm>observation</firstterm>).
Each case represents an individual or &#8220;experimental unit&#8221;.
For example, in the results of a survey, the names of the respondents,
their sex, age, etc. and their responses are all data and the data
pertaining to single respondent is a case.
This chapter examines
the PSPP commands for defining variables and reading and writing data.
There are alternative commands to  read data from predefined sources
such as system files or databases (See <link linkend="GET">GET DATA</link>.)
</para>
<note><para>These commands tell PSPP how to read data, but the data will not
actually be read until a procedure is executed.
</para></note>

<sect1 label="8.1" id="BEGIN-DATA">
<title>BEGIN DATA</title>
<indexterm role="vr"><primary>BEGIN DATA</primary></indexterm>
<indexterm role="vr"><primary>END DATA</primary></indexterm>
<indexterm role="cp"><primary>Embedding data in syntax files</primary></indexterm>
<indexterm role="cp"><primary>Data, embedding in syntax files</primary></indexterm>

<literallayout>BEGIN DATA.
&#8230;
END DATA.
</literallayout>
<para><literal>BEGIN DATA</literal> and <literal>END DATA</literal> can be used to embed raw ASCII
data in a PSPP syntax file.  <literal>DATA LIST</literal> or another input
procedure must be used before <literal>BEGIN DATA</literal> (see <link linkend="DATA-LIST">DATA LIST</link>).
<literal>BEGIN DATA</literal> and <literal>END DATA</literal> must be used together.  <literal>END
DATA</literal> must appear by itself on a single line, with no leading
white space and exactly one space between the words <literal>END</literal> and
<literal>DATA</literal>, like this:
</para>
<screen>END DATA.
</screen>
</sect1>
<sect1 label="8.2" id="CLOSE-FILE-HANDLE">
<title>CLOSE FILE HANDLE</title>

<literallayout>CLOSE FILE HANDLE <replaceable>handle_name</replaceable>.
</literallayout>
<para><literal>CLOSE FILE HANDLE</literal> disassociates the name of a file handle with a
given file.  The only specification is the name of the handle to close.
Afterward
<literal>FILE HANDLE</literal>.
</para>
<para>The file named INLINE, which represents data entered between <literal>BEGIN
DATA</literal> and <literal>END DATA</literal>, cannot be closed.  Attempts to close it with
<literal>CLOSE FILE HANDLE</literal> have no effect.
</para>
<para><literal>CLOSE FILE HANDLE</literal> is a PSPP extension.
</para>
</sect1>
<sect1 label="8.3" id="DATAFILE-ATTRIBUTE">
<title>DATAFILE ATTRIBUTE</title>
<indexterm role="vr"><primary>DATAFILE ATTRIBUTE</primary></indexterm>

<literallayout>DATAFILE ATTRIBUTE
         ATTRIBUTE=<replaceable>name</replaceable>(&#8217;<replaceable>value</replaceable>&#8217;) [<replaceable>name</replaceable>(&#8217;<replaceable>value</replaceable>&#8217;)]&#8230;
         ATTRIBUTE=<replaceable>name</replaceable><emphasis role="bold">[</emphasis><replaceable>index</replaceable><emphasis role="bold">]</emphasis>(&#8217;<replaceable>value</replaceable>&#8217;) [<replaceable>name</replaceable><emphasis role="bold">[</emphasis><replaceable>index</replaceable><emphasis role="bold">]</emphasis>(&#8217;<replaceable>value</replaceable>&#8217;)]&#8230;
         DELETE=<replaceable>name</replaceable> [<replaceable>name</replaceable>]&#8230;
         DELETE=<replaceable>name</replaceable><emphasis role="bold">[</emphasis><replaceable>index</replaceable><emphasis role="bold">]</emphasis> [<replaceable>name</replaceable><emphasis role="bold">[</emphasis><replaceable>index</replaceable><emphasis role="bold">]</emphasis>]&#8230;
</literallayout>
<para><literal>DATAFILE ATTRIBUTE</literal> adds, modifies, or removes user-defined
attributes associated with the active dataset.  Custom data file
attributes are not interpreted by PSPP, but they are saved as part of
system files and may be used by other software that reads them.
</para>
<para>Use the <literal>ATTRIBUTE</literal> subcommand to add or modify a custom data file
attribute.  Specify the name of the attribute as an identifier
(see <link linkend="Tokens">Tokens</link>), followed by the desired value, in parentheses, as a
quoted string.  Attribute names that begin with <literal>$</literal> are reserved
for PSPP&#8217;s internal use, and attribute names that begin with <literal>@</literal>
or <literal>$@</literal> are not displayed by most PSPP commands that display
other attributes.  Other attribute names are not treated specially.
</para>
<para>Attributes may also be organized into arrays.  To assign to an array
element, add an integer array index enclosed in square brackets
(<literal>[</literal> and <literal>]</literal>) between the attribute name and value.  Array
indexes start at 1, not 0.  An attribute array that has a single
element (number 1) is not distinguished from a non-array attribute.
</para>
<para>Use the <literal>DELETE</literal> subcommand to delete an attribute.  Specify an
attribute name by itself to delete an entire attribute, including all
array elements for attribute arrays.  Specify an attribute name
followed by an array index in square brackets to delete a single
element of an attribute array.  In the latter case, all the array
elements numbered higher than the deleted element are shifted down,
filling the vacated position.
</para>
<para>To associate custom attributes with particular variables, instead of
with the entire active dataset, use <literal>VARIABLE ATTRIBUTE</literal>
(see <link linkend="VARIABLE-ATTRIBUTE">VARIABLE ATTRIBUTE</link>) instead.
</para>
<para><literal>DATAFILE ATTRIBUTE</literal> takes effect immediately.  It is not affected
by conditional and looping structures such as <literal>DO IF</literal> or
<literal>LOOP</literal>.
</para>
</sect1>
<sect1 label="8.4" id="DATASET">
<title>DATASET commands</title>
<indexterm role="vr"><primary>DATASET</primary></indexterm>

<literallayout>DATASET NAME <replaceable>name</replaceable> [WINDOW={ASIS,FRONT}].
DATASET ACTIVATE <replaceable>name</replaceable> [WINDOW={ASIS,FRONT}].
DATASET COPY <replaceable>name</replaceable> [WINDOW={MINIMIZED,HIDDEN,FRONT}].
DATASET DECLARE <replaceable>name</replaceable> [WINDOW={MINIMIZED,HIDDEN,FRONT}].
DATASET CLOSE {<replaceable>name</replaceable>,*,ALL}.
DATASET DISPLAY.
</literallayout>
<para>The <literal>DATASET</literal> commands simplify use of multiple datasets within a
PSPP session.  They allow datasets to be created and destroyed.  At
any given time, most PSPP commands work with a single dataset, called
the active dataset.
</para>
<indexterm role="vr"><primary>DATASET NAME</primary></indexterm>
<para>The DATASET NAME command gives the active dataset the specified name, or
if it already had a name, it renames it.  If another dataset already
had the given name, that dataset is deleted.
</para>
<indexterm role="vr"><primary>DATASET ACTIVATE</primary></indexterm>
<para>The DATASET ACTIVATE command selects the named dataset, which must
already exist, as the active dataset.  Before switching the active
dataset, any pending transformations are executed, as if <literal>EXECUTE</literal>
had been specified.  If the active dataset is unnamed before
switching, then it is deleted and becomes unavailable after switching.
</para>
<indexterm role="vr"><primary>DATASET COPY</primary></indexterm>
<para>The DATASET COPY command creates a new dataset with the specified
name, whose contents are a copy of the active dataset.  Any pending
transformations are executed, as if <literal>EXECUTE</literal> had been specified,
before making the copy.  If a dataset with the given name already
exists, it is replaced.  If the name is the name of the active
dataset, then the active dataset becomes unnamed.
</para>
<indexterm role="vr"><primary>DATASET DECLARE</primary></indexterm>
<para>The DATASET DECLARE command creates a new dataset that is initially
&#8220;empty,&#8221; that is, it has no dictionary or data.  If a dataset with
the given name already exists, this has no effect.  The new dataset
can be used with commands that support output to a dataset,
<emphasis>e.g.</emphasis> AGGREGATE (see <link linkend="AGGREGATE">AGGREGATE</link>).
</para>
<indexterm role="vr"><primary>DATASET CLOSE</primary></indexterm>
<para>The DATASET CLOSE command deletes a dataset.  If the active dataset is
specified by name, or if &#8216;<literal>*</literal>&#8217; is specified, then the active
dataset becomes unnamed.  If a different dataset is specified by name,
then it is deleted and becomes unavailable.  Specifying ALL deletes
all datasets except for the active dataset, which becomes unnamed.
</para>
<indexterm role="vr"><primary>DATASET DISPLAY</primary></indexterm>
<para>The DATASET DISPLAY command lists all the currently defined datasets.
</para>
<para>Many DATASET commands accept an optional <literal>WINDOW</literal> subcommand.  In the
PSPPIRE GUI, the value given for this subcommand influences how the
dataset&#8217;s window is displayed.  Outside the GUI, the <literal>WINDOW</literal> subcommand
has no effect.  The valid values are:
</para>
<variablelist><varlistentry><term>ASIS
</term><listitem><para>Do not change how the window is displayed.  This is the default for
DATASET NAME and DATASET ACTIVATE.
</para>
</listitem></varlistentry><varlistentry><term>FRONT
</term><listitem><para>Raise the dataset&#8217;s window to the top.  Make it the default dataset
for running syntax.
</para>
</listitem></varlistentry><varlistentry><term>MINIMIZED
</term><listitem><para>Display the window &#8220;minimized&#8221; to an icon.  Prefer other datasets
for running syntax.  This is the default for DATASET COPY and DATASET
DECLARE.
</para>
</listitem></varlistentry><varlistentry><term>HIDDEN
</term><listitem><para>Hide the dataset&#8217;s window.  Prefer other datasets for running syntax.
</para></listitem></varlistentry></variablelist>
</sect1>
<sect1 label="8.5" id="DATA-LIST">
<title>DATA LIST</title>
<indexterm role="vr"><primary>DATA LIST</primary></indexterm>
<indexterm role="cp"><primary>reading data from a file</primary></indexterm>
<indexterm role="cp"><primary>data, reading from a file</primary></indexterm>
<indexterm role="cp"><primary>data, embedding in syntax files</primary></indexterm>
<indexterm role="cp"><primary>embedding data in syntax files</primary></indexterm>

<para>Used to read text or binary data, <literal>DATA LIST</literal> is the most
fundamental data-reading command.  Even the more sophisticated input
methods use <literal>DATA LIST</literal> commands as a building block.
Understanding <literal>DATA LIST</literal> is important to understanding how to use
PSPP to read your data files.
</para>
<para>There are two major variants of <literal>DATA LIST</literal>, which are fixed
format and free format.  In addition, free format has a minor variant,
list format, which is discussed in terms of its differences from vanilla
free format.
</para>
<para>Each form of <literal>DATA LIST</literal> is described in detail below.
</para>
<para>See <link linkend="GET-DATA">GET DATA</link>, for a command that offers a few enhancements over
DATA LIST and that may be substituted for DATA LIST in many
situations.
</para>

<sect2 label="8.5.1" id="DATA-LIST-FIXED">
<title>DATA LIST FIXED</title>
<indexterm role="vr"><primary>DATA LIST FIXED</primary></indexterm>
<indexterm role="cp"><primary>reading fixed-format data</primary></indexterm>
<indexterm role="cp"><primary>fixed-format data, reading</primary></indexterm>
<indexterm role="cp"><primary>data, fixed-format, reading</primary></indexterm>
<indexterm role="cp"><primary>embedding fixed-format data</primary></indexterm>

<literallayout>DATA LIST [FIXED]
        {TABLE,NOTABLE}
        [FILE=&#8217;<replaceable>file_name</replaceable>&#8217; [ENCODING=&#8217;<replaceable>encoding</replaceable>&#8217;]]
        [RECORDS=<replaceable>record_count</replaceable>]
        [END=<replaceable>end_var</replaceable>]
        [SKIP=<replaceable>record_count</replaceable>]
        /[line_no] <replaceable>var_spec</replaceable>&#8230;

where each <replaceable>var_spec</replaceable> takes one of the forms
        <replaceable>var_list</replaceable> <replaceable>start</replaceable>-<replaceable>end</replaceable> [<replaceable>type_spec</replaceable>]
        <replaceable>var_list</replaceable> (<replaceable>fortran_spec</replaceable>)
</literallayout>
<para><literal>DATA LIST FIXED</literal> is used to read data files that have values at fixed
positions on each line of single-line or multiline records.  The
keyword FIXED is optional.
</para>
<para>The <literal>FILE</literal> subcommand must be used if input is to be taken from an
external file.  It may be used to specify a file name as a string or a
file handle (see <link linkend="File-Handles">File Handles</link>).  If the <literal>FILE</literal> subcommand is not used,
then input is assumed to be specified within the command file using
<literal>BEGIN DATA</literal>&#8230;<literal>END DATA</literal> (see <link linkend="BEGIN-DATA">BEGIN DATA</link>).
The <literal>ENCODING</literal> subcommand may only be used if the <literal>FILE</literal>
subcommand is also used.  It specifies the character encoding of the
file.  See <link linkend="INSERT">INSERT</link>, for information on supported encodings.
</para>
<para>The optional <literal>RECORDS</literal> subcommand, which takes a single integer as an
argument, is used to specify the number of lines per record.
If <literal>RECORDS</literal>
is not specified, then the number of lines per record is calculated from
the list of variable specifications later in <literal>DATA LIST</literal>.
</para>
<para>The <literal>END</literal> subcommand is only useful in conjunction with <literal>INPUT
PROGRAM</literal>.  See <link linkend="INPUT-PROGRAM">INPUT PROGRAM</link>, for details.
</para>
<para>The optional <literal>SKIP</literal> subcommand specifies a number of records to skip at
the beginning of an input file.  It can be used to skip over a row
that contains variable names, for example.
</para>
<para><literal>DATA LIST</literal> can optionally output a table describing how the data file
is read.  The <literal>TABLE</literal> subcommand enables this output, and
<literal>NOTABLE</literal> disables it.  The default is to output the table.
</para>
<para>The list of variables to be read from the data list must come last.
Each line in the data record is introduced by a slash (&#8216;<literal>/</literal>&#8217;).
Optionally, a line number may follow the slash.  Following, any number
of variable specifications may be present.
</para>
<para>Each variable specification consists of a list of variable names
followed by a description of their location on the input line.  Sets of
variables may be specified using the <literal>DATA LIST</literal> <literal>TO</literal> convention
(see <link linkend="Sets-of-Variables">Sets of
Variables</link>).  There are two ways to specify the location of the variable
on the line: columnar style and FORTRAN style.
</para>
<para>In columnar style, the starting column and ending column for the field
are specified after the variable name, separated by a dash (&#8216;<literal>-</literal>&#8217;).
For instance, the third through fifth columns on a line would be
specified &#8216;<literal>3-5</literal>&#8217;.  By default, variables are considered to be in
&#8216;<literal>F</literal>&#8217; format (see <link linkend="Input-and-Output-Formats">Input and Output Formats</link>).  (This default can be
changed; see <link linkend="SET">SET</link> for more information.)
</para>
<para>In columnar style, to use a variable format other than the default,
specify the format type in parentheses after the column numbers.  For
instance, for alphanumeric &#8216;<literal>A</literal>&#8217; format, use &#8216;<literal>(A)</literal>&#8217;.
</para>
<para>In addition, implied decimal places can be specified in parentheses
after the column numbers.  As an example, suppose that a data file has a
field in which the characters &#8216;<literal>1234</literal>&#8217; should be interpreted as
having the value 12.34.  Then this field has two implied decimal places,
and the corresponding specification would be &#8216;<literal>(2)</literal>&#8217;.  If a field
that has implied decimal places contains a decimal point, then the
implied decimal places are not applied.
</para>
<para>Changing the variable format and adding implied decimal places can be
done together; for instance, &#8216;<literal>(N,5)</literal>&#8217;.
</para>
<para>When using columnar style, the input and output width of each variable is
computed from the field width.  The field width must be evenly divisible
into the number of variables specified.
</para>
<para>FORTRAN style is an altogether different approach to specifying field
locations.  With this approach, a list of variable input format
specifications, separated by commas, are placed after the variable names
inside parentheses.  Each format specifier advances as many characters
into the input line as it uses.
</para>
<para>Implied decimal places also exist in FORTRAN style.  A format
specification with <replaceable>d</replaceable> decimal places also has <replaceable>d</replaceable> implied
decimal places.
</para>
<para>In addition to the standard format specifiers (see <link linkend="Input-and-Output-Formats">Input and Output
Formats</link>), FORTRAN style defines some extensions:
</para>
<variablelist><varlistentry><term><literal>X</literal>
</term><listitem><para>Advance the current column on this line by one character position.
</para>
</listitem></varlistentry><varlistentry><term><literal>T</literal><replaceable>x</replaceable>
</term><listitem><para>Set the current column on this line to column <replaceable>x</replaceable>, with column
numbers considered to begin with 1 at the left margin.
</para>
</listitem></varlistentry><varlistentry><term><literal>NEWREC</literal><replaceable>x</replaceable>
</term><listitem><para>Skip forward <replaceable>x</replaceable> lines in the current record, resetting the active
column to the left margin.
</para>
</listitem></varlistentry><varlistentry><term>Repeat count
</term><listitem><para>Any format specifier may be preceded by a number.  This causes the
action of that format specifier to be repeated the specified number of
times.
</para>
</listitem></varlistentry><varlistentry><term>(<replaceable>spec1</replaceable>, &#8230;, <replaceable>specN</replaceable>)
</term><listitem><para>Group the given specifiers together.  This is most useful when preceded
by a repeat count.  Groups may be nested arbitrarily.
</para></listitem></varlistentry></variablelist>
<para>FORTRAN and columnar styles may be freely intermixed.  Columnar style
leaves the active column immediately after the ending column
specified.  Record motion using <literal>NEWREC</literal> in FORTRAN style also
applies to later FORTRAN and columnar specifiers.
</para>

<sect3 label="" id="DATA-LIST-FIXED-Examples">
<title>Examples</title>

<orderedlist numeration="arabic"><listitem><!-- Update the corresponding test in tests/language/commands/data-list.at if you change this. -->
<screen>DATA LIST TABLE /NAME 1-10 (A) INFO1 TO INFO3 12-17 (1).

BEGIN DATA.
John Smith 102311
Bob Arnold 122015
Bill Yates  918 6
END DATA.
</screen>
<para>Defines the following variables:
</para>
<itemizedlist><listitem><para><literal>NAME</literal>, a 10-character-wide string variable, in columns 1
through 10.
</para>
</listitem><listitem><para><literal>INFO1</literal>, a numeric variable, in columns 12 through 13.
</para>
</listitem><listitem><para><literal>INFO2</literal>, a numeric variable, in columns 14 through 15.
</para>
</listitem><listitem><para><literal>INFO3</literal>, a numeric variable, in columns 16 through 17.
</para></listitem></itemizedlist>
<para>The <literal>BEGIN DATA</literal>/<literal>END DATA</literal> commands cause three cases to be
defined:
</para>
<screen>Case   NAME         INFO1   INFO2   INFO3
   1   John Smith     10      23      11
   2   Bob Arnold     12      20      15
   3   Bill Yates      9      18       6
</screen>
<para>The <literal>TABLE</literal> keyword causes PSPP to print out a table
describing the four variables defined.
</para>
</listitem><listitem><!-- Update the corresponding test in tests/language/commands/data-list.at if you change this. -->
<screen>DATA LIST FILE=&quot;survey.dat&quot;
        /ID 1-5 NAME 7-36 (A) SURNAME 38-67 (A) MINITIAL 69 (A)
        /Q01 TO Q50 7-56
        /.
</screen>
<para>Defines the following variables:
</para>
<itemizedlist><listitem><para><literal>ID</literal>, a numeric variable, in columns 1-5 of the first record.
</para>
</listitem><listitem><para><literal>NAME</literal>, a 30-character string variable, in columns 7-36 of the
first record.
</para>
</listitem><listitem><para><literal>SURNAME</literal>, a 30-character string variable, in columns 38-67 of
the first record.
</para>
</listitem><listitem><para><literal>MINITIAL</literal>, a 1-character string variable, in column 69 of
the first record.
</para>
</listitem><listitem><para>Fifty variables <literal>Q01</literal>, <literal>Q02</literal>, <literal>Q03</literal>, &#8230;, <literal>Q49</literal>,
<literal>Q50</literal>, all numeric, <literal>Q01</literal> in column 7, <literal>Q02</literal> in column 8,
&#8230;, <literal>Q49</literal> in column 55, <literal>Q50</literal> in column 56, all in the second
record.
</para></listitem></itemizedlist>
<para>Cases are separated by a blank record.
</para>
<para>Data is read from file <filename>survey.dat</filename> in the current directory.
</para></listitem></orderedlist>
</sect3>
</sect2>
<sect2 label="8.5.2" id="DATA-LIST-FREE">
<title>DATA LIST FREE</title>
<indexterm role="vr"><primary>DATA LIST FREE</primary></indexterm>

<literallayout>DATA LIST FREE
        [({TAB,&#8217;<replaceable>c</replaceable>&#8217;}, &#8230;)]
        [{NOTABLE,TABLE}]
        [FILE=&#8217;<replaceable>file_name</replaceable>&#8217; [ENCODING=&#8217;<replaceable>encoding</replaceable>&#8217;]]
        [SKIP=<replaceable>n_records</replaceable>]
        /<replaceable>var_spec</replaceable>&#8230;

where each <replaceable>var_spec</replaceable> takes one of the forms
        <replaceable>var_list</replaceable> [(<replaceable>type_spec</replaceable>)]
        <replaceable>var_list</replaceable> *
</literallayout>
<para>In free format, the input data is, by default, structured as a series
of fields separated by spaces, tabs, or line breaks.
If the current <literal>DECIMAL</literal> separator is <literal>DOT</literal> (see <link linkend="SET">SET</link>),
then commas are also treated as field separators.
Each
field&#8217;s content may be unquoted, or it may be quoted with a pairs of
apostrophes (&#8216;<literal>'</literal>&#8217;) or double quotes (&#8216;<literal>&quot;</literal>&#8217;).  Unquoted white
space separates fields but is not part of any field.  Any mix of
spaces, tabs, and line breaks is equivalent to a single space for the
purpose of separating fields, but consecutive commas will skip a
field.
</para>
<para>Alternatively, delimiters can be specified explicitly, as a
parenthesized, comma-separated list of single-character strings
immediately following FREE.  The word TAB may also be used to specify
a tab character as a delimiter.  When delimiters are specified
explicitly, only the given characters, plus line breaks, separate
fields.  Furthermore, leading spaces at the beginnings of fields are
not trimmed, consecutive delimiters define empty fields, and no form
of quoting is allowed.
</para>
<para>The <literal>NOTABLE</literal> and <literal>TABLE</literal> subcommands are as in <literal>DATA LIST FIXED</literal> above.
<literal>NOTABLE</literal> is the default.
</para>
<para>The <literal>FILE</literal>, <literal>SKIP</literal>, and <literal>ENCODING</literal> subcommands
are as in <literal>DATA LIST FIXED</literal> above.
</para>
<para>The variables to be parsed are given as a single list of variable names.
This list must be introduced by a single slash (&#8216;<literal>/</literal>&#8217;).  The set of
variable names may contain format specifications in parentheses
(see <link linkend="Input-and-Output-Formats">Input and Output Formats</link>).  Format specifications apply to all
variables back to the previous parenthesized format specification.
</para>
<para>In addition, an asterisk may be used to indicate that all variables
preceding it are to have input/output format &#8216;<literal>F8.0</literal>&#8217;.
</para>
<para>Specified field widths are ignored on input, although all normal limits
on field width apply, but they are honored on output.
</para>
</sect2>
<sect2 label="8.5.3" id="DATA-LIST-LIST">
<title>DATA LIST LIST</title>
<indexterm role="vr"><primary>DATA LIST LIST</primary></indexterm>

<literallayout>DATA LIST LIST
        [({TAB,&#8217;<replaceable>c</replaceable>&#8217;}, &#8230;)]
        [{NOTABLE,TABLE}]
        [FILE=&#8217;<replaceable>file_name</replaceable>&#8217; [ENCODING=&#8217;<replaceable>encoding</replaceable>&#8217;]]
        [SKIP=<replaceable>record_count</replaceable>]
        /<replaceable>var_spec</replaceable>&#8230;

where each <replaceable>var_spec</replaceable> takes one of the forms
        <replaceable>var_list</replaceable> [(<replaceable>type_spec</replaceable>)]
        <replaceable>var_list</replaceable> *
</literallayout>
<para>With one exception, <literal>DATA LIST LIST</literal> is syntactically and
semantically equivalent to <literal>DATA LIST FREE</literal>.  The exception is
that each input line is expected to correspond to exactly one input
record.  If more or fewer fields are found on an input line than
expected, an appropriate diagnostic is issued.
</para>
</sect2>
</sect1>
<sect1 label="8.6" id="END-CASE">
<title>END CASE</title>
<indexterm role="vr"><primary>END CASE</primary></indexterm>

<literallayout>END CASE.
</literallayout>
<para><literal>END CASE</literal> is used only within <literal>INPUT PROGRAM</literal> to output the
current case.  See <link linkend="INPUT-PROGRAM">INPUT PROGRAM</link>, for details.
</para>
</sect1>
<sect1 label="8.7" id="END-FILE">
<title>END FILE</title>
<indexterm role="vr"><primary>END FILE</primary></indexterm>

<literallayout>END FILE.
</literallayout>
<para><literal>END FILE</literal> is used only within <literal>INPUT PROGRAM</literal> to terminate
the current input program.  See <link linkend="INPUT-PROGRAM">INPUT PROGRAM</link>.
</para>
</sect1>
<sect1 label="8.8" id="FILE-HANDLE">
<title>FILE HANDLE</title>
<indexterm role="vr"><primary>FILE HANDLE</primary></indexterm>

<literallayout>For text files:
        FILE HANDLE <replaceable>handle_name</replaceable>
                /NAME=&#8217;<replaceable>file_name</replaceable>
                [/MODE=CHARACTER]
                [/ENDS={CR,CRLF}]
                /TABWIDTH=<replaceable>tab_width</replaceable>
                [ENCODING=&#8217;<replaceable>encoding</replaceable>&#8217;]

For binary files in native encoding with fixed-length records:
        FILE HANDLE <replaceable>handle_name</replaceable>
                /NAME=&#8217;<replaceable>file_name</replaceable>&#8217;
                /MODE=IMAGE
                [/LRECL=<replaceable>rec_len</replaceable>]
                [ENCODING=&#8217;<replaceable>encoding</replaceable>&#8217;]

For binary files in native encoding with variable-length records:
        FILE HANDLE <replaceable>handle_name</replaceable>
                /NAME=&#8217;<replaceable>file_name</replaceable>&#8217;
                /MODE=BINARY
                [/LRECL=<replaceable>rec_len</replaceable>]
                [ENCODING=&#8217;<replaceable>encoding</replaceable>&#8217;]

For binary files encoded in EBCDIC:
        FILE HANDLE <replaceable>handle_name</replaceable>
                /NAME=&#8217;<replaceable>file_name</replaceable>&#8217;
                /MODE=360
                /RECFORM={FIXED,VARIABLE,SPANNED}
                [/LRECL=<replaceable>rec_len</replaceable>]
                [ENCODING=&#8217;<replaceable>encoding</replaceable>&#8217;]
</literallayout>
<para>Use <literal>FILE HANDLE</literal> to associate a file handle name with a file and
its attributes, so that later commands can refer to the file by its
handle name.  Names of text files can be specified directly on
commands that access files, so that <literal>FILE HANDLE</literal> is only needed when a
file is not an ordinary file containing lines of text.  However,
<literal>FILE HANDLE</literal> may be used even for text files, and it may be
easier to specify a file&#8217;s name once and later refer to it by an
abstract handle.
</para>
<para>Specify the file handle name as the identifier immediately following the
<literal>FILE HANDLE</literal> command name.  The identifier INLINE is reserved for
representing data embedded in the syntax file (see <link linkend="BEGIN-DATA">BEGIN DATA</link>) The
file handle name must not already have been used in a previous
invocation of <literal>FILE HANDLE</literal>, unless it has been closed by an
intervening command (see <link linkend="CLOSE-FILE-HANDLE">CLOSE FILE HANDLE</link>).
</para>
<para>The effect and syntax of <literal>FILE HANDLE</literal> depends on the selected MODE:
</para>
<itemizedlist><listitem><para>In CHARACTER mode, the default, the data file is read as a text file.
Each text line is read as one record.
</para>
<para>In CHARACTER mode only, tabs are expanded to spaces by input programs,
except by <literal>DATA LIST FREE</literal> with explicitly specified delimiters.
Each tab is 4 characters wide by default, but TABWIDTH (a PSPP
extension) may be used to specify an alternate width.  Use a TABWIDTH
of 0 to suppress tab expansion.
</para>
<para>A file written in CHARACTER mode by default uses the line ends of the
system on which PSPP is running, that is, on Windows, the default is
CR LF line ends, and on other systems the default is LF only.  Specify
ENDS as CR or CRLF to override the default.  PSPP reads files using
either convention on any kind of system, regardless of ENDS.
</para>
</listitem><listitem><para>In IMAGE mode, the data file is treated as a series of fixed-length
binary records.  LRECL should be used to specify the record length in
bytes, with a default of 1024.  On input, it is an error if an IMAGE
file&#8217;s length is not an integer multiple of the record length.  On
output, each record is padded with spaces or truncated, if necessary,
to make it exactly the correct length.
</para>
</listitem><listitem><para>In BINARY mode, the data file is treated as a series of
variable-length binary records.  LRECL may be specified, but its value
is ignored.  The data for each record is both preceded and followed by
a 32-bit signed integer in little-endian byte order that specifies the
length of the record.  (This redundancy permits records in these
files to be efficiently read in reverse order, although PSPP always
reads them in forward order.)  The length does not include either
integer.
</para>
</listitem><listitem><para>Mode 360 reads and writes files in formats first used for tapes in the
1960s on IBM mainframe operating systems and still supported today by
the modern successors of those operating systems.  For more
information, see <citetitle>OS/400 Tape and Diskette Device Programming</citetitle>,
available on IBM&#8217;s website.
</para>
<para>Alphanumeric data in mode 360 files are encoded in EBCDIC.  PSPP
translates EBCDIC to or from the host&#8217;s native format as necessary on
input or output, using an ASCII/EBCDIC translation that is one-to-one,
so that a &#8220;round trip&#8221; from ASCII to EBCDIC back to ASCII, or vice
versa, always yields exactly the original data.
</para>
<para>The <literal>RECFORM</literal> subcommand is required in mode 360.  The precise file
format depends on its setting:
</para>
<variablelist><varlistentry><term>F
</term><term>FIXED
</term><listitem><para>This record format is equivalent to IMAGE mode, except for EBCDIC
translation.
</para>
<para>IBM documentation calls this <literal>*F</literal> (fixed-length, deblocked)
format.
</para>
</listitem></varlistentry><varlistentry><term>V
</term><term>VARIABLE
</term><listitem><para>The file comprises a sequence of zero or more variable-length blocks.
Each block begins with a 4-byte <firstterm>block descriptor word</firstterm> (BDW).
The first two bytes of the BDW are an unsigned integer in big-endian
byte order that specifies the length of the block, including the BDW
itself.  The other two bytes of the BDW are ignored on input and
written as zeros on output.
</para>
<para>Following the BDW, the remainder of each block is a sequence of one or
more variable-length records, each of which in turn begins with a
4-byte <firstterm>record descriptor word</firstterm> (RDW) that has the same format as
the BDW.  Following the RDW, the remainder of each record is the
record data.
</para>
<para>The maximum length of a record in VARIABLE mode is 65,527 bytes:
65,535 bytes (the maximum value of a 16-bit unsigned integer), minus 4
bytes for the BDW, minus 4 bytes for the RDW.
</para>
<para>In mode VARIABLE, LRECL specifies a maximum, not a fixed, record
length, in bytes.  The default is 8,192.
</para>
<para>IBM documentation calls this <literal>*VB</literal> (variable-length, blocked,
unspanned) format.
</para>
</listitem></varlistentry><varlistentry><term>VS
</term><term>SPANNED
</term><listitem><para>The file format is like that of VARIABLE mode, except that logical
records may be split among multiple physical records (called
<firstterm>segments</firstterm>) or blocks.  In SPANNED mode, the third byte of each
RDW is called the segment control character (SCC).  Odd SCC values
cause the segment to be appended to a record buffer maintained in
memory; even values also append the segment and then flush its
contents to the input procedure.  Canonically, SCC value 0 designates
a record not spanned among multiple segments, and values 1 through 3
designate the first segment, the last segment, or an intermediate
segment, respectively, within a multi-segment record.  The record
buffer is also flushed at end of file regardless of the final record&#8217;s
SCC.
</para>
<para>The maximum length of a logical record in VARIABLE mode is limited
only by memory available to PSPP.  Segments are limited to 65,527
bytes, as in VARIABLE mode.
</para>
<para>This format is similar to what IBM documentation call <literal>*VS</literal>
(variable-length, deblocked, spanned) format.
</para></listitem></varlistentry></variablelist>
<para>In mode 360, fields of type A that extend beyond the end of a record
read from disk are padded with spaces in the host&#8217;s native character
set, which are then translated from EBCDIC to the native character
set.  Thus, when the host&#8217;s native character set is based on ASCII,
these fields are effectively padded with character <literal>X'80'</literal>.  This
wart is implemented for compatibility.
</para></listitem></itemizedlist>
<para>The <literal>NAME</literal> subcommand specifies the name of the file associated with the
handle.  It is required in all modes but SCRATCH mode, in which its
use is forbidden.
</para>
<para>The ENCODING subcommand specifies the encoding of text in the file.
For reading text files in CHARACTER mode, all of the forms described
for ENCODING on the INSERT command are supported (see <link linkend="INSERT">INSERT</link>).
For reading in other file-based modes, encoding autodetection is not
supported; if the specified encoding requests autodetection then the
default encoding is used.  This is also true when a file handle
is used for writing a file in any mode.
</para>
</sect1>
<sect1 label="8.9" id="INPUT-PROGRAM">
<title>INPUT PROGRAM</title>
<indexterm role="vr"><primary>INPUT PROGRAM</primary></indexterm>

<literallayout>INPUT PROGRAM.
&#8230; input commands &#8230;
END INPUT PROGRAM.
</literallayout>
<para><literal>INPUT PROGRAM</literal>&#8230;<literal>END INPUT PROGRAM</literal> specifies a
complex input program.  By placing data input commands within <literal>INPUT
PROGRAM</literal>, PSPP programs can take advantage of more complex file
structures than available with only <literal>DATA LIST</literal>.
</para>
<para>The first sort of extended input program is to simply put multiple <literal>DATA
LIST</literal> commands within the <literal>INPUT PROGRAM</literal>.  This will cause all of
the data
files to be read in parallel.  Input will stop when end of file is
reached on any of the data files.
</para>
<para>Transformations, such as conditional and looping constructs, can also be
included within <literal>INPUT PROGRAM</literal>.  These can be used to combine input
from several data files in more complex ways.  However, input will still
stop when end of file is reached on any of the data files.
</para>
<para>To prevent <literal>INPUT PROGRAM</literal> from terminating at the first end of
file, use
the <literal>END</literal> subcommand on <literal>DATA LIST</literal>.  This subcommand takes a
variable name,
which should be a numeric scratch variable (see <link linkend="Scratch-Variables">Scratch Variables</link>).
(It need not be a scratch variable but otherwise the results can be
surprising.)  The value of this variable is set to 0 when reading the
data file, or 1 when end of file is encountered.
</para>
<para>Two additional commands are useful in conjunction with <literal>INPUT PROGRAM</literal>.
<literal>END CASE</literal> is the first.  Normally each loop through the
<literal>INPUT PROGRAM</literal>
structure produces one case.  <literal>END CASE</literal> controls exactly
when cases are output.  When <literal>END CASE</literal> is used, looping from the end of
<literal>INPUT PROGRAM</literal> to the beginning does not cause a case to be output.
</para>
<para><literal>END FILE</literal> is the second.  When the <literal>END</literal> subcommand is used on <literal>DATA
LIST</literal>, there is no way for the <literal>INPUT PROGRAM</literal> construct to stop
looping,
so an infinite loop results.  <literal>END FILE</literal>, when executed,
stops the flow of input data and passes out of the <literal>INPUT PROGRAM</literal>
structure.
</para>
<para><literal>INPUT PROGRAM</literal> must contain at least one <literal>DATA LIST</literal> or
<literal>END FILE</literal> command.
</para>
<bridgehead renderas="sect2">Example 1: Read two files in parallel to the end of the shorter</bridgehead>

<para>The following example reads variable X from file <filename>a.txt</filename> and
variable Y from file <filename>b.txt</filename>.  If one file is shorter than the
other then the extra data in the longer file is ignored.
</para>
<screen>INPUT PROGRAM.
    DATA LIST NOTABLE FILE='a.txt'/X 1-10.
    DATA LIST NOTABLE FILE='b.txt'/Y 1-10.
END INPUT PROGRAM.
LIST.
</screen>
<bridgehead renderas="sect2">Example 2: Read two files in parallel, supplementing the shorter</bridgehead>

<para>The following example also reads variable X from <filename>a.txt</filename> and
variable Y from <filename>b.txt</filename>.  If one file is shorter than the other
then it continues reading the longer to its end, setting the other
variable to system-missing.
</para>
<screen>INPUT PROGRAM.
    NUMERIC #A #B.

    DO IF NOT #A.
        DATA LIST NOTABLE END=#A FILE='a.txt'/X 1-10.
    END IF.
    DO IF NOT #B.
        DATA LIST NOTABLE END=#B FILE='b.txt'/Y 1-10.
    END IF.
    DO IF #A AND #B.
        END FILE.
    END IF.
    END CASE.
END INPUT PROGRAM.
LIST.
</screen>
<bridgehead renderas="sect2">Example 3: Concatenate two files (version 1)</bridgehead>

<para>The following example reads data from file <filename>a.txt</filename>, then from
<filename>b.txt</filename>, and concatenates them into a single active dataset.
</para>
<screen>INPUT PROGRAM.
    NUMERIC #A #B.

    DO IF #A.
        DATA LIST NOTABLE END=#B FILE='b.txt'/X 1-10.
        DO IF #B.
            END FILE.
        ELSE.
            END CASE.
        END IF.
    ELSE.
        DATA LIST NOTABLE END=#A FILE='a.txt'/X 1-10.
        DO IF NOT #A.
            END CASE.
        END IF.
    END IF.
END INPUT PROGRAM.
LIST.
</screen>
<bridgehead renderas="sect2">Example 4: Concatenate two files (version 2)</bridgehead>

<para>This is another way to do the same thing as Example 3.
</para>
<screen>INPUT PROGRAM.
    NUMERIC #EOF.

    LOOP IF NOT #EOF.
        DATA LIST NOTABLE END=#EOF FILE='a.txt'/X 1-10.
        DO IF NOT #EOF.
            END CASE.
        END IF.
    END LOOP.

    COMPUTE #EOF = 0.
    LOOP IF NOT #EOF.
        DATA LIST NOTABLE END=#EOF FILE='b.txt'/X 1-10.
        DO IF NOT #EOF.
            END CASE.
        END IF.
    END LOOP.

    END FILE.
END INPUT PROGRAM.
LIST.
</screen>
<bridgehead renderas="sect2">Example 5: Generate random variates</bridgehead>

<para>The follows example creates a dataset that consists of 50 random
variates between 0 and 10.
</para>
<screen>INPUT PROGRAM.
    LOOP #I=1 TO 50.
        COMPUTE X=UNIFORM(10).
        END CASE.
    END LOOP.
    END FILE.
END INPUT PROGRAM.
LIST /FORMAT=NUMBERED.
</screen>
</sect1>
<sect1 label="8.10" id="LIST">
<title>LIST</title>
<indexterm role="vr"><primary>LIST</primary></indexterm>

<literallayout>LIST
        /VARIABLES=<replaceable>var_list</replaceable>
        /CASES=FROM <replaceable>start_index</replaceable> TO <replaceable>end_index</replaceable> BY <replaceable>incr_index</replaceable>
        /FORMAT={UNNUMBERED,NUMBERED} {WRAP,SINGLE}
</literallayout>
<para>The <literal>LIST</literal> procedure prints the values of specified variables to the
listing file.
</para>
<para>The <literal>VARIABLES</literal> subcommand specifies the variables whose values are to be
printed.  Keyword VARIABLES is optional.  If <literal>VARIABLES</literal> subcommand is not
specified then all variables in the active dataset are printed.
</para>
<para>The <literal>CASES</literal> subcommand can be used to specify a subset of cases to be
printed.  Specify <literal>FROM</literal> and the case number of the first case to print,
<literal>TO</literal> and the case number of the last case to print, and <literal>BY</literal> and the number
of cases to advance between printing cases, or any subset of those
settings.  If <literal>CASES</literal> is not specified then all cases are printed.
</para>
<para>The <literal>FORMAT</literal> subcommand can be used to change the output format.  <literal>NUMBERED</literal>
will print case numbers along with each case; <literal>UNNUMBERED</literal>, the default,
causes the case numbers to be omitted.  The <literal>WRAP</literal> and <literal>SINGLE</literal> settings are
currently not used.
</para>
<para>Case numbers start from 1.  They are counted after all transformations
have been considered.
</para>
<para><literal>LIST</literal> is a procedure.  It causes the data to be read.
</para>
</sect1>
<sect1 label="8.11" id="NEW-FILE">
<title>NEW FILE</title>
<indexterm role="vr"><primary>NEW FILE</primary></indexterm>

<literallayout>NEW FILE.
</literallayout>
<para><literal>NEW FILE</literal> command clears the dictionary and data from the current
active dataset.
</para>
</sect1>
<sect1 label="8.12" id="PRINT">
<title>PRINT</title>
<indexterm role="vr"><primary>PRINT</primary></indexterm>

<literallayout>PRINT
        [OUTFILE=&#8217;<replaceable>file_name</replaceable>&#8217;]
        [RECORDS=<replaceable>n_lines</replaceable>]
        [{NOTABLE,TABLE}]
        [ENCODING=&#8217;<replaceable>encoding</replaceable>&#8217;]
        [/[<replaceable>line_no</replaceable>] <replaceable>arg</replaceable>&#8230;]

<replaceable>arg</replaceable> takes one of the following forms:
        &#8217;<replaceable>string</replaceable>&#8217; [<replaceable>start</replaceable>]
        <replaceable>var_list</replaceable> <replaceable>start</replaceable>-<replaceable>end</replaceable> [<replaceable>type_spec</replaceable>]
        <replaceable>var_list</replaceable> (<replaceable>fortran_spec</replaceable>)
        <replaceable>var_list</replaceable> *
</literallayout>
<para>The <literal>PRINT</literal> transformation writes variable data to the listing
file or an output file.  <literal>PRINT</literal> is executed when a procedure
causes the data to be read.  Follow <literal>PRINT</literal> by <literal>EXECUTE</literal> to
print variable data without invoking a procedure (see <link linkend="EXECUTE">EXECUTE</link>).
</para>
<para>All <literal>PRINT</literal> subcommands are optional.  If no strings or variables
are specified, <literal>PRINT</literal> outputs a single blank line.
</para>
<para>The <literal>OUTFILE</literal> subcommand specifies the file to receive the output.  The
file may be a file name as a string or a file handle (see <link linkend="File-Handles">File
Handles</link>).  If <literal>OUTFILE</literal> is not present then output is sent to
PSPP&#8217;s output listing file.  When <literal>OUTFILE</literal> is present, the
output is written to <replaceable>file_name</replaceable> in a plain text format, with a
space inserted at beginning of each output line, even lines that
otherwise would be blank.
</para>
<para>The <literal>ENCODING</literal> subcommand may only be used if the
<literal>OUTFILE</literal> subcommand is also used.  It specifies the character
encoding of the file.  See <link linkend="INSERT">INSERT</link>, for information on supported
encodings.
</para>
<para>The <literal>RECORDS</literal> subcommand specifies the number of lines to be output.  The
number of lines may optionally be surrounded by parentheses.
</para>
<para><literal>TABLE</literal> will cause the <literal>PRINT</literal> command to output a table to the listing file
that describes what it will print to the output file.  <literal>NOTABLE</literal>, the
default, suppresses this output table.
</para>
<para>Introduce the strings and variables to be printed with a slash
(&#8216;<literal>/</literal>&#8217;).  Optionally, the slash may be followed by a number
indicating which output line is specified.  In the absence of this
line number, the next line number is specified.  Multiple lines may
be specified using multiple slashes with the intended output for a line
following its respective slash.
</para>
<para>Literal strings may be printed.  Specify the string itself.
Optionally the string may be followed by a column number, specifying
the column on the line where the string should start.  Otherwise, the
string is printed at the current position on the line.
</para>
<para>Variables to be printed can be specified in the same ways as available
for <literal>DATA LIST FIXED</literal> (see <link linkend="DATA-LIST-FIXED">DATA LIST FIXED</link>).  In addition, a
variable
list may be followed by an asterisk (&#8216;<literal>*</literal>&#8217;), which indicates that the
variables should be printed in their dictionary print formats, separated
by spaces.  A variable list followed by a slash or the end of command
is interpreted in the same way.
</para>
<para>If a FORTRAN type specification is used to move backwards on the current
line, then text is written at that point on the line, the line is
truncated to that length, although additional text being added will
again extend the line to that length.
</para>
</sect1>
<sect1 label="8.13" id="PRINT-EJECT">
<title>PRINT EJECT</title>
<indexterm role="vr"><primary>PRINT EJECT</primary></indexterm>

<literallayout>PRINT EJECT
        OUTFILE=&#8217;<replaceable>file_name</replaceable>&#8217;
        RECORDS=<replaceable>n_lines</replaceable>
        {NOTABLE,TABLE}
        /[<replaceable>line_no</replaceable>] <replaceable>arg</replaceable>&#8230;

<replaceable>arg</replaceable> takes one of the following forms:
        &#8217;<replaceable>string</replaceable>&#8217; [<replaceable>start</replaceable>-<replaceable>end</replaceable>]
        <replaceable>var_list</replaceable> <replaceable>start</replaceable>-<replaceable>end</replaceable> [<replaceable>type_spec</replaceable>]
        <replaceable>var_list</replaceable> (<replaceable>fortran_spec</replaceable>)
        <replaceable>var_list</replaceable> *
</literallayout>
<para><literal>PRINT EJECT</literal> advances to the beginning of a new output page in
the listing file or output file.  It can also output data in the same
way as <literal>PRINT</literal>.
</para>
<para>All <literal>PRINT EJECT</literal> subcommands are optional.
</para>
<para>Without <literal>OUTFILE</literal>, <literal>PRINT EJECT</literal> ejects the current page in
the listing file, then it produces other output, if any is specified.
</para>
<para>With <literal>OUTFILE</literal>, <literal>PRINT EJECT</literal> writes its output to the specified file.
The first line of output is written with &#8216;<literal>1</literal>&#8217; inserted in the
first column.  Commonly, this is the only line of output.  If
additional lines of output are specified, these additional lines are
written with a space inserted in the first column, as with <literal>PRINT</literal>.
</para>
<para>See <link linkend="PRINT">PRINT</link>, for more information on syntax and usage.
</para>
</sect1>
<sect1 label="8.14" id="PRINT-SPACE">
<title>PRINT SPACE</title>
<indexterm role="vr"><primary>PRINT SPACE</primary></indexterm>

<literallayout>PRINT SPACE [OUTFILE=&#8217;file_name&#8217;] [ENCODING=&#8217;<replaceable>encoding</replaceable>&#8217;] [n_lines].
</literallayout>
<para><literal>PRINT SPACE</literal> prints one or more blank lines to an output file.
</para>
<para>The <literal>OUTFILE</literal> subcommand is optional.  It may be used to direct output to
a file specified by file name as a string or file handle (see <link linkend="File-Handles">File
Handles</link>).  If OUTFILE is not specified then output is directed to
the listing file.
</para>
<para>The <literal>ENCODING</literal> subcommand may only be used if <literal>OUTFILE</literal>
is also used.  It specifies the character encoding of the file.
See <link linkend="INSERT">INSERT</link>, for information on supported encodings.
</para>
<para>n_lines is also optional.  If present, it is an expression
(see <link linkend="Expressions">Expressions</link>) specifying the number of blank lines to be
printed.  The expression must evaluate to a nonnegative value.
</para>
</sect1>
<sect1 label="8.15" id="REREAD">
<title>REREAD</title>
<indexterm role="vr"><primary>REREAD</primary></indexterm>

<literallayout>REREAD [FILE=handle] [COLUMN=column] [ENCODING=&#8217;<replaceable>encoding</replaceable>&#8217;].
</literallayout>
<para>The <literal>REREAD</literal> transformation allows the previous input line in a
data file
already processed by <literal>DATA LIST</literal> or another input command to be re-read
for further processing.
</para>
<para>The <literal>FILE</literal> subcommand, which is optional, is used to specify the file to
have its line re-read.  The file must be specified as the name of a file
handle (see <link linkend="File-Handles">File Handles</link>).  If FILE is not specified then the last
file specified on <literal>DATA LIST</literal> is assumed (last file specified
lexically, not in terms of flow-of-control).
</para>
<para>By default, the line re-read is re-read in its entirety.  With the
<literal>COLUMN</literal> subcommand, a prefix of the line can be exempted from
re-reading.  Specify an expression (see <link linkend="Expressions">Expressions</link>) evaluating to
the first column that should be included in the re-read line.  Columns
are numbered from 1 at the left margin.
</para>
<para>The <literal>ENCODING</literal> subcommand may only be used if the <literal>FILE</literal>
subcommand is also used.  It specifies the character encoding of the
file.   See <link linkend="INSERT">INSERT</link>, for information on supported encodings.
</para>
<para>Issuing <literal>REREAD</literal> multiple times will not back up in the data
file.  Instead, it will re-read the same line multiple times.
</para>
</sect1>
<sect1 label="8.16" id="WRITE">
<title>WRITE</title>
<indexterm role="vr"><primary>WRITE</primary></indexterm>

<literallayout>WRITE
        OUTFILE=&#8217;<replaceable>file_name</replaceable>&#8217;
        RECORDS=<replaceable>n_lines</replaceable>
        {NOTABLE,TABLE}
        /[<replaceable>line_no</replaceable>] <replaceable>arg</replaceable>&#8230;

<replaceable>arg</replaceable> takes one of the following forms:
        &#8217;<replaceable>string</replaceable>&#8217; [<replaceable>start</replaceable>-<replaceable>end</replaceable>]
        <replaceable>var_list</replaceable> <replaceable>start</replaceable>-<replaceable>end</replaceable> [<replaceable>type_spec</replaceable>]
        <replaceable>var_list</replaceable> (<replaceable>fortran_spec</replaceable>)
        <replaceable>var_list</replaceable> *
</literallayout>
<para><literal>WRITE</literal> writes text or binary data to an output file.
</para>
<para>See <link linkend="PRINT">PRINT</link>, for more information on syntax and usage.  <literal>PRINT</literal>
and <literal>WRITE</literal> differ in only a few ways:
</para>
<itemizedlist><listitem><para><literal>WRITE</literal> uses write formats by default, whereas <literal>PRINT</literal> uses
print formats.
</para>
</listitem><listitem><para><literal>PRINT</literal> inserts a space between variables unless a format is
explicitly specified, but <literal>WRITE</literal> never inserts space between
variables in output.
</para>
</listitem><listitem><para><literal>PRINT</literal> inserts a space at the beginning of each line that it
writes to an output file (and <literal>PRINT EJECT</literal> inserts &#8216;<literal>1</literal>&#8217; at
the beginning of each line that should begin a new page), but
<literal>WRITE</literal> does not.
</para>
</listitem><listitem><para><literal>PRINT</literal> outputs the system-missing value according to its
specified output format, whereas <literal>WRITE</literal> outputs the
system-missing value as a field filled with spaces.  Binary formats
are an exception.
</para></listitem></itemizedlist><!-- PSPP - a program for statistical analysis. -->
<!-- Copyright (C) 2017, 2020 Free Software Foundation, Inc. -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.3 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<!-- A copy of the license is included in the section entitled "GNU -->
<!-- Free Documentation License". -->
<!-- -->
</sect1>
</chapter>
<chapter label="9" id="System-and-Portable-File-IO">
<title>System and Portable File I/O</title>

<para>The commands in this chapter read, write, and examine system files and
portable files.
</para>

<sect1 label="9.1" id="APPLY-DICTIONARY">
<title>APPLY DICTIONARY</title>
<indexterm role="vr"><primary>APPLY DICTIONARY</primary></indexterm>

<literallayout>APPLY DICTIONARY FROM={&#8217;<replaceable>file_name</replaceable>&#8217;,<replaceable>file_handle</replaceable>}.
</literallayout>
<para><literal>APPLY DICTIONARY</literal> applies the variable labels, value labels,
and missing values taken from a file to corresponding
variables in the active dataset.  In some cases it also updates the
weighting variable.
</para>
<para>The <literal>FROM</literal> clause is mandatory.  Use it to specify a system
file or portable file&#8217;s name in single quotes, a data set name
(see <link linkend="Datasets">Datasets</link>), or a file handle name (see <link linkend="File-Handles">File Handles</link>).
The dictionary in the file is be read, but it does not replace the active
dataset&#8217;s dictionary. The file&#8217;s data is not read.
</para>
<para>Only variables with names that exist in both the active dataset and the
system file are considered.  Variables with the same name but different
types (numeric, string) cause an error message.  Otherwise, the
system file variables&#8217; attributes replace those in their matching
active dataset variables:
</para>
<itemizedlist><listitem><para>If a system file variable has a variable label, then it replaces
the variable label of the active dataset variable.  If the system
file variable does not have a variable label, then the active dataset
variable&#8217;s variable label, if any, is retained.
</para>
</listitem><listitem><para>If the system file variable has custom attributes (see <link linkend="VARIABLE-ATTRIBUTE">VARIABLE
ATTRIBUTE</link>), then those attributes replace the active dataset variable&#8217;s
custom attributes.  If the system file variable does not have custom
attributes, then the active dataset variable&#8217;s custom attributes, if any,
is retained.
</para>
</listitem><listitem><para>If the active dataset variable is numeric or short string, then value
labels and missing values, if any, are copied to the active dataset
variable.  If the system file variable does not have value labels or
missing values, then those in the active dataset variable, if any, are not
disturbed.
</para></listitem></itemizedlist>
<para>In addition to properties of variables, some properties of the active
file dictionary as a whole are updated:
</para>
<itemizedlist><listitem><para>If the system file has custom attributes (see <link linkend="DATAFILE-ATTRIBUTE">DATAFILE ATTRIBUTE</link>),
then those attributes replace the active dataset variable&#8217;s custom
attributes.
</para>
</listitem><listitem><para>If the active dataset has a weighting variable (see <link linkend="WEIGHT">WEIGHT</link>), and the
system file does not, or if the weighting variable in the system file
does not exist in the active dataset, then the active dataset weighting
variable, if any, is retained.  Otherwise, the weighting variable in
the system file becomes the active dataset weighting variable.
</para></listitem></itemizedlist>
<para><literal>APPLY DICTIONARY</literal> takes effect immediately.  It does not read the
active dataset.  The system file is not modified.
</para>
</sect1>
<sect1 label="9.2" id="EXPORT">
<title>EXPORT</title>
<indexterm role="vr"><primary>EXPORT</primary></indexterm>

<literallayout>EXPORT
        /OUTFILE=&#8217;<replaceable>file_name</replaceable>&#8217;
        /UNSELECTED={RETAIN,DELETE}
        /DIGITS=<replaceable>n</replaceable>
        /DROP=<replaceable>var_list</replaceable>
        /KEEP=<replaceable>var_list</replaceable>
        /RENAME=(<replaceable>src_names</replaceable>=<replaceable>target_names</replaceable>)&#8230;
        /TYPE={COMM,TAPE}
        /MAP
</literallayout>
<para>The <literal>EXPORT</literal> procedure writes the active dataset&#8217;s dictionary and
data to a specified portable file.
</para>
<para>By default, cases excluded with FILTER are written to the
file.  These can be excluded by specifying DELETE on the <literal>UNSELECTED</literal>
subcommand.  Specifying RETAIN makes the default explicit.
</para>
<para>Portable files express real numbers in base 30.  Integers are always
expressed to the maximum precision needed to make them exact.
Non-integers are, by default, expressed to the machine&#8217;s maximum
natural precision (approximately 15 decimal digits on many machines).
If many numbers require this many digits, the portable file may
significantly increase in size.  As an alternative, the <literal>DIGITS</literal>
subcommand may be used to specify the number of decimal digits of
precision to write.  <literal>DIGITS</literal> applies only to non-integers.
</para>
<para>The <literal>OUTFILE</literal> subcommand, which is the only required subcommand, specifies
the portable file to be written as a file name string or
a file handle (see <link linkend="File-Handles">File Handles</link>).
</para>
<para><literal>DROP</literal>, <literal>KEEP</literal>, and <literal>RENAME</literal> follow the same format as the
<literal>SAVE</literal> procedure (see <link linkend="SAVE">SAVE</link>).
</para>
<para>The <literal>TYPE</literal> subcommand specifies the character set for use in the
portable file.  Its value is currently not used.
</para>
<para>The <literal>MAP</literal> subcommand is currently ignored.
</para>
<para><literal>EXPORT</literal> is a procedure.  It causes the active dataset to be read.
</para>
</sect1>
<sect1 label="9.3" id="GET">
<title>GET</title>
<indexterm role="vr"><primary>GET</primary></indexterm>

<literallayout>GET
        /FILE={&#8217;<replaceable>file_name</replaceable>&#8217;,<replaceable>file_handle</replaceable>}
        /DROP=<replaceable>var_list</replaceable>
        /KEEP=<replaceable>var_list</replaceable>
        /RENAME=(<replaceable>src_names</replaceable>=<replaceable>target_names</replaceable>)&#8230;
        /ENCODING=&#8217;<replaceable>encoding</replaceable>&#8217;
</literallayout>
<para><literal>GET</literal> clears the current dictionary and active dataset and
replaces them with the dictionary and data from a specified file.
</para>
<para>The <literal>FILE</literal> subcommand is the only required subcommand.  Specify
the SPSS system file, SPSS/PC+ system file, or SPSS portable file to
be read as a string file name or a file handle (see <link linkend="File-Handles">File Handles</link>).
</para>
<para>By default, all the variables in a file are read.  The DROP
subcommand can be used to specify a list of variables that are not to be
read.  By contrast, the <literal>KEEP</literal> subcommand can be used to specify
variable that are to be read, with all other variables not read.
</para>
<para>Normally variables in a file retain the names that they were
saved under.  Use the <literal>RENAME</literal> subcommand to change these names.
Specify,
within parentheses, a list of variable names followed by an equals sign
(&#8216;<literal>=</literal>&#8217;) and the names that they should be renamed to.  Multiple
parenthesized groups of variable names can be included on a single
<literal>RENAME</literal> subcommand.
Variables&#8217; names may be swapped using a <literal>RENAME</literal>
subcommand of the form <literal>/RENAME=(<replaceable>A</replaceable> <replaceable>B</replaceable>=<replaceable>B</replaceable> <replaceable>A</replaceable>)</literal>.
</para>
<para>Alternate syntax for the <literal>RENAME</literal> subcommand allows the parentheses to be
eliminated.  When this is done, only a single variable may be renamed at
once.  For instance, <literal>/RENAME=<replaceable>A</replaceable>=<replaceable>B</replaceable></literal>.  This alternate syntax is
deprecated.
</para>
<para><literal>DROP</literal>, <literal>KEEP</literal>, and <literal>RENAME</literal> are executed in left-to-right order.
Each may be present any number of times.  <literal>GET</literal> never modifies a
file on disk.  Only the active dataset read from the file
is affected by these subcommands.
</para>
<para>PSPP automatically detects the encoding of string data in the file,
when possible.  The character encoding of old SPSS system files cannot
always be guessed correctly, and SPSS/PC+ system files do not include
any indication of their encoding.  Specify the <literal>ENCODING</literal>
subcommand with an <acronym>IANA</acronym> character set name as its string
argument to override the default.  Use <literal>SYSFILE INFO</literal> to analyze
the encodings that might be valid for a system file.  The
<literal>ENCODING</literal> subcommand is a PSPP extension.
</para>
<para><literal>GET</literal> does not cause the data to be read, only the dictionary.  The data
is read later, when a procedure is executed.
</para>
<para>Use of <literal>GET</literal> to read a portable file is a PSPP extension.
</para>
</sect1>
<sect1 label="9.4" id="GET-DATA">
<title>GET DATA</title>
<indexterm role="vr"><primary>GET DATA</primary></indexterm>

<literallayout>GET DATA
        /TYPE={GNM,ODS,PSQL,TXT}
        &#8230;additional subcommands depending on TYPE&#8230;
</literallayout>
<para>The <literal>GET DATA</literal> command is used to read files and other data
sources created by other applications.  When this command is executed,
the current dictionary and active dataset are replaced with variables
and data read from the specified source.
</para>
<para>The <literal>TYPE</literal> subcommand is mandatory and must be the first subcommand
specified.  It determines the type of the file or source to read.
PSPP currently supports the following file types:
</para>
<variablelist><varlistentry><term>GNM
</term><listitem><para>Spreadsheet files created by Gnumeric (<ulink url="http://gnumeric.org">http://gnumeric.org</ulink>).
</para>
</listitem></varlistentry><varlistentry><term>ODS
</term><listitem><para>Spreadsheet files in OpenDocument format (<ulink url="http://opendocumentformat.org">http://opendocumentformat.org</ulink>).
</para>
</listitem></varlistentry><varlistentry><term>PSQL
</term><listitem><para>Relations from PostgreSQL databases (<ulink url="http://postgresql.org">http://postgresql.org</ulink>).
</para>
</listitem></varlistentry><varlistentry><term>TXT
</term><listitem><para>Textual data files in columnar and delimited formats.
</para></listitem></varlistentry></variablelist>
<para>Each supported file type has additional subcommands, explained in
separate sections below.
</para>

<sect2 label="9.4.1" id="GET-DATA-_002fTYPE_003dGNM_002fODS">
<title>Spreadsheet Files</title>

<literallayout>GET DATA /TYPE={GNM, ODS}
        /FILE={&#8217;<replaceable>file_name</replaceable>&#8217;}
        /SHEET={NAME &#8217;<replaceable>sheet_name</replaceable>&#8217;, INDEX <replaceable>n</replaceable>}
        /CELLRANGE={RANGE &#8217;<replaceable>range</replaceable>&#8217;, FULL}
        /READNAMES={ON, OFF}
        /ASSUMEDSTRWIDTH=<replaceable>n</replaceable>.
</literallayout>
<indexterm role="cp"><primary>Gnumeric</primary></indexterm>
<indexterm role="cp"><primary>OpenDocument</primary></indexterm>
<indexterm role="cp"><primary>spreadsheet files</primary></indexterm>

<para>Gnumeric spreadsheets (<ulink url="http://gnumeric.org">http://gnumeric.org</ulink>), and spreadsheets
in OpenDocument format
(<ulink url="http://libreplanet.org/wiki/Group:OpenDocument/Software">http://libreplanet.org/wiki/Group:OpenDocument/Software</ulink>)
can be read using the <literal>GET DATA</literal> command.
Use the <literal>TYPE</literal> subcommand to indicate the file&#8217;s format.
/TYPE=GNM indicates Gnumeric files,
/TYPE=ODS indicates OpenDocument.
The <literal>FILE</literal> subcommand is mandatory.
Use it to specify the name file to be read.
All other subcommands are optional.
</para>
<para>The format of each variable is determined by the format of the spreadsheet
cell containing the first datum for the variable.
If this cell is of string (text) format, then the width of the variable is
determined from the length of the string it contains, unless the
<literal>ASSUMEDSTRWIDTH</literal> subcommand is given.
</para>
<para>The <literal>SHEET</literal> subcommand specifies the sheet within the spreadsheet file to read.
There are two forms of the <literal>SHEET</literal> subcommand.
In the first form,
<literal>/SHEET=name <replaceable>sheet_name</replaceable></literal>, the string <replaceable>sheet_name</replaceable> is the
name of the sheet to read.
In the second form, <literal>/SHEET=index <replaceable>idx</replaceable></literal>, <replaceable>idx</replaceable> is a
integer which is the index of the sheet to read.
The first sheet has the index 1.
If the <literal>SHEET</literal> subcommand is omitted, then the command reads the
first sheet in the file.
</para>
<para>The <literal>CELLRANGE</literal> subcommand specifies the range of cells within the sheet to read.
If the subcommand is given as <literal>/CELLRANGE=FULL</literal>, then the entire
sheet  is read.
To read only part of a sheet, use the form
<literal>/CELLRANGE=range '<replaceable>top_left_cell</replaceable>:<replaceable>bottom_right_cell</replaceable>'</literal>.
For example, the subcommand <literal>/CELLRANGE=range 'C3:P19'</literal> reads
columns C&#8211;P, and rows 3&#8211;19 inclusive.
If no <literal>CELLRANGE</literal> subcommand is given, then the entire sheet is read.
</para>
<para>If <literal>/READNAMES=ON</literal> is specified, then the contents of cells of
the first row are used as the names of the variables in which to store
the data from subsequent rows.  This is the default.
If <literal>/READNAMES=OFF</literal> is
used, then the variables  receive automatically assigned names.
</para>
<para>The <literal>ASSUMEDSTRWIDTH</literal> subcommand specifies the maximum width of string
variables read  from the file.
If omitted, the default value is determined from the length of the
string in the first spreadsheet cell for each variable.
</para>

</sect2>
<sect2 label="9.4.2" id="GET-DATA-_002fTYPE_003dPSQL">
<title>Postgres Database Queries</title>

<literallayout>GET DATA /TYPE=PSQL
         /CONNECT={<replaceable>connection info</replaceable>}
         /SQL={<replaceable>query</replaceable>}
         [/ASSUMEDSTRWIDTH=<replaceable>w</replaceable>]
         [/UNENCRYPTED]
         [/BSIZE=<replaceable>n</replaceable>].
</literallayout>
<indexterm role="cp"><primary>postgres</primary></indexterm>
<indexterm role="cp"><primary>databases</primary></indexterm>

<para><literal>GET DATA /TYPE=PSQL</literal> imports data from a local or remote
Postgres database server.
It automatically creates variables based on the table column names
or the names specified in the SQL query.
PSPP cannot support the full precision of some Postgres data types,
so data of those types will lose some precision when PSPP imports them.
PSPP does not support all Postgres data types.
If PSPP cannot support a datum, <literal>GET DATA</literal> issues a warning
and substitutes the system-missing value.
</para>
<para>The <literal>CONNECT</literal> subcommand is mandatory.
It is a string specifying the parameters of the database server from
which the data should be fetched.
The format of the string is given in the postgres manual
<ulink url="http://www.postgresql.org/docs/8.0/static/libpq.html#LIBPQ-CONNECT">http://www.postgresql.org/docs/8.0/static/libpq.html#LIBPQ-CONNECT</ulink>.
</para>
<para>The <literal>SQL</literal> subcommand is mandatory.
It must be a valid SQL string to retrieve data from the database.
</para>
<para>The <literal>ASSUMEDSTRWIDTH</literal> subcommand specifies the maximum width of string
variables read  from the database.
If omitted, the default value is determined from the length of the
string in the first value read for each variable.
</para>
<para>The <literal>UNENCRYPTED</literal> subcommand allows data to be retrieved over an insecure
connection.
If the connection is not encrypted, and the <literal>UNENCRYPTED</literal> subcommand is
not given, then an error occurs.
Whether or not the connection is
encrypted depends upon the underlying psql library and the
capabilities of the database server.
</para>
<para>The <literal>BSIZE</literal> subcommand serves only to optimise the speed of data transfer.
It specifies an upper limit on
number of cases to fetch from the database at once.
The default value is 4096.
If your SQL statement fetches a large number of cases but only a small number of
variables, then the data transfer may be faster if you increase this value.
Conversely, if the number of variables is large, or if the machine on which
PSPP is running has only a
small amount of memory, then a smaller value is probably better.
</para>

<para>The following syntax is an example:
</para><screen>GET DATA /TYPE=PSQL
     /CONNECT='host=example.com port=5432 dbname=product user=fred passwd=xxxx'
     /SQL='select * from manufacturer'.
</screen>

</sect2>
<sect2 label="9.4.3" id="GET-DATA-_002fTYPE_003dTXT">
<title>Textual Data Files</title>

<literallayout>GET DATA /TYPE=TXT
        /FILE={&#8217;<replaceable>file_name</replaceable>&#8217;,<replaceable>file_handle</replaceable>}
        [ENCODING=&#8217;<replaceable>encoding</replaceable>&#8217;]
        [/ARRANGEMENT={DELIMITED,FIXED}]
        [/FIRSTCASE={<replaceable>first_case</replaceable>}]
        [/IMPORTCASES=...]
        &#8230;additional subcommands depending on ARRANGEMENT&#8230;
</literallayout>
<indexterm role="cp"><primary>text files</primary></indexterm>
<indexterm role="cp"><primary>data files</primary></indexterm>
<para>When TYPE=TXT is specified, GET DATA reads data in a delimited or
fixed columnar format, much like DATA LIST (see <link linkend="DATA-LIST">DATA LIST</link>).
</para>
<para>The <literal>FILE</literal> subcommand is mandatory.  Specify the file to be read as
a string file name or (for textual data only) a
file handle (see <link linkend="File-Handles">File Handles</link>).
</para>
<para>The <literal>ENCODING</literal> subcommand specifies the character encoding of
the file to be read.  See <link linkend="INSERT">INSERT</link>, for information on supported
encodings.
</para>
<para>The <literal>ARRANGEMENT</literal> subcommand determines the file&#8217;s basic format.
DELIMITED, the default setting, specifies that fields in the input
data are separated by spaces, tabs, or other user-specified
delimiters.  FIXED specifies that fields in the input data appear at
particular fixed column positions within records of a case.
</para>
<para>By default, cases are read from the input file starting from the first
line.  To skip lines at the beginning of an input file, set <literal>FIRSTCASE</literal>
to the number of the first line to read: 2 to skip the first line, 3
to skip the first two lines, and so on.
</para>
<para><literal>IMPORTCASES</literal> is ignored, for compatibility.  Use <literal>N OF
CASES</literal> to limit the number of cases read from a file (see <link linkend="N-OF-CASES">N OF
CASES</link>), or <literal>SAMPLE</literal> to obtain a random sample of cases
(see <link linkend="SAMPLE">SAMPLE</link>).
</para>
<para>The remaining subcommands apply only to one of the two file
arrangements, described below.
</para>

<sect3 label="9.4.3.1" id="GET-DATA-_002fTYPE_003dTXT-_002fARRANGEMENT_003dDELIMITED">
<title>Reading Delimited Data</title>

<literallayout>GET DATA /TYPE=TXT
        /FILE={&#8217;<replaceable>file_name</replaceable>&#8217;,<replaceable>file_handle</replaceable>}
        [/ARRANGEMENT={DELIMITED,FIXED}]
        [/FIRSTCASE={<replaceable>first_case</replaceable>}]
        [/IMPORTCASE={ALL,FIRST <replaceable>max_cases</replaceable>,PERCENT <replaceable>percent</replaceable>}]

        /DELIMITERS=&quot;<replaceable>delimiters</replaceable>&quot;
        [/QUALIFIER=&quot;<replaceable>quotes</replaceable>&quot;
        [/DELCASE={LINE,VARIABLES <replaceable>n_variables</replaceable>}]
        /VARIABLES=<replaceable>del_var1</replaceable> [<replaceable>del_var2</replaceable>]&#8230;
where each <replaceable>del_var</replaceable> takes the form:
        variable format
</literallayout>
<para>The GET DATA command with TYPE=TXT and ARRANGEMENT=DELIMITED reads
input data from text files in delimited format, where fields are
separated by a set of user-specified delimiters.  Its capabilities are
similar to those of DATA LIST FREE (see <link linkend="DATA-LIST-FREE">DATA LIST FREE</link>), with a
few enhancements.
</para>
<para>The required <literal>FILE</literal> subcommand and optional <literal>FIRSTCASE</literal> and <literal>IMPORTCASE</literal>
subcommands are described above (see <link linkend="GET-DATA-_002fTYPE_003dTXT">GET DATA /TYPE=TXT</link>).
</para>
<para><literal>DELIMITERS</literal>, which is required, specifies the set of characters that
may separate fields.  Each character in the string specified on
<literal>DELIMITERS</literal> separates one field from the next.  The end of a line also
separates fields, regardless of <literal>DELIMITERS</literal>.  Two consecutive
delimiters in the input yield an empty field, as does a delimiter at
the end of a line.  A space character as a delimiter is an exception:
consecutive spaces do not yield an empty field and neither does any
number of spaces at the end of a line.
</para>
<para>To use a tab as a delimiter, specify &#8216;<literal>\t</literal>&#8217; at the beginning of the
<literal>DELIMITERS</literal> string.  To use a backslash as a delimiter, specify
&#8216;<literal>\\</literal>&#8217; as the first delimiter or, if a tab should also be a
delimiter, immediately following &#8216;<literal>\t</literal>&#8217;.  To read a data file in
which each field appears on a separate line, specify the empty string
for <literal>DELIMITERS</literal>.
</para>
<para>The optional <literal>QUALIFIER</literal> subcommand names one or more characters that
can be used to quote values within fields in the input.  A field that
begins with one of the specified quote characters ends at the next
matching quote.  Intervening delimiters become part of the field,
instead of terminating it.  The ability to specify more than one quote
character is a PSPP extension.
</para>
<para>The character specified on <literal>QUALIFIER</literal> can be embedded within a
field that it quotes by doubling the qualifier.  For example, if
&#8216;<literal>'</literal>&#8217; is specified on <literal>QUALIFIER</literal>, then <literal>'a''b'</literal>
specifies a field that contains &#8216;<literal>a'b</literal>&#8217;.
</para>
<para>The <literal>DELCASE</literal> subcommand controls how data may be broken across lines in
the data file.  With LINE, the default setting, each line must contain
all the data for exactly one case.  For additional flexibility, to
allow a single case to be split among lines or multiple cases to be
contained on a single line, specify VARIABLES <emphasis>n_variables</emphasis>, where
<emphasis>n_variables</emphasis> is the number of variables per case.
</para>
<para>The <literal>VARIABLES</literal> subcommand is required and must be the last subcommand.
Specify the name of each variable and its input format (see <link linkend="Input-and-Output-Formats">Input
and Output Formats</link>) in the order they should be read from the input
file.
</para>
<bridgehead renderas="sect3">Examples</bridgehead>

<para>On a Unix-like system, the &#8216;<literal>/etc/passwd</literal>&#8217; file has a format
similar to this:
</para>
<screen>root:$1$nyeSP5gD$pDq/:0:0:,,,:/root:/bin/bash
blp:$1$BrP/pFg4$g7OG:1000:1000:Ben Pfaff,,,:/home/blp:/bin/bash
john:$1$JBuq/Fioq$g4A:1001:1001:John Darrington,,,:/home/john:/bin/bash
jhs:$1$D3li4hPL$88X1:1002:1002:Jason Stover,,,:/home/jhs:/bin/csh
</screen>
<para>The following syntax reads a file in the format used by
&#8216;<literal>/etc/passwd</literal>&#8217;:
</para>
<!-- If you change this example, change the regression test in -->
<!-- tests/language/commands/get-data.at to match. -->
<screen>GET DATA /TYPE=TXT /FILE='/etc/passwd' /DELIMITERS=':'
        /VARIABLES=username A20
                   password A40
                   uid F10
                   gid F10
                   gecos A40
                   home A40
                   shell A40.
</screen>
<para>Consider the following data on used cars:
</para>
<screen>model   year    mileage price   type    age
Civic   2002    29883   15900   Si      2
Civic   2003    13415   15900   EX      1
Civic   1992    107000  3800    n/a     12
Accord  2002    26613   17900   EX      1
</screen>
<para>The following syntax can be used to read the used car data:
</para>
<!-- If you change this example, change the regression test in -->
<!-- tests/language/commands/get-data.at to match. -->
<screen>GET DATA /TYPE=TXT /FILE='cars.data' /DELIMITERS=' ' /FIRSTCASE=2
        /VARIABLES=model A8
                   year F4
                   mileage F6
                   price F5
                   type A4
                   age F2.
</screen>
<para>Consider the following information on animals in a pet store:
</para>
<screen>'Pet''s Name', &quot;Age&quot;, &quot;Color&quot;, &quot;Date Received&quot;, &quot;Price&quot;, &quot;Height&quot;, &quot;Type&quot;
, (Years), , , (Dollars), ,
&quot;Rover&quot;, 4.5, Brown, &quot;12 Feb 2004&quot;, 80, '1''4&quot;', &quot;Dog&quot;
&quot;Charlie&quot;, , Gold, &quot;5 Apr 2007&quot;, 12.3, &quot;3&quot;&quot;&quot;, &quot;Fish&quot;
&quot;Molly&quot;, 2, Black, &quot;12 Dec 2006&quot;, 25, '5&quot;', &quot;Cat&quot;
&quot;Gilly&quot;, , White, &quot;10 Apr 2007&quot;, 10, &quot;3&quot;&quot;&quot;, &quot;Guinea Pig&quot;
</screen>
<para>The following syntax can be used to read the pet store data:
</para>
<!-- If you change this example, change the regression test in -->
<!-- tests/language/commands/get-data.at to match. -->
<screen>GET DATA /TYPE=TXT /FILE='pets.data' /DELIMITERS=', ' /QUALIFIER='''&quot;' /ESCAPE
        /FIRSTCASE=3
        /VARIABLES=name A10
                   age F3.1
                   color A5
                   received EDATE10
                   price F5.2
                   height a5
                   type a10.
</screen>
</sect3>
<sect3 label="9.4.3.2" id="GET-DATA-_002fTYPE_003dTXT-_002fARRANGEMENT_003dFIXED">
<title>Reading Fixed Columnar Data</title>

<!-- (modify-syntax-entry ?_ "w") -->
<!-- (modify-syntax-entry ?' "'") -->
<!-- (modify-syntax-entry ?@ "'") -->

<literallayout>GET DATA /TYPE=TXT
        /FILE={&#8217;file_name&#8217;,<replaceable>file_handle</replaceable>}
        [/ARRANGEMENT={DELIMITED,FIXED}]
        [/FIRSTCASE={<replaceable>first_case</replaceable>}]
        [/IMPORTCASE={ALL,FIRST <replaceable>max_cases</replaceable>,PERCENT <replaceable>percent</replaceable>}]

        [/FIXCASE=<replaceable>n</replaceable>]
        /VARIABLES <replaceable>fixed_var</replaceable> [<replaceable>fixed_var</replaceable>]&#8230;
            [/rec# <replaceable>fixed_var</replaceable> [<replaceable>fixed_var</replaceable>]&#8230;]&#8230;
where each <replaceable>fixed_var</replaceable> takes the form:
        <replaceable>variable</replaceable> <replaceable>start</replaceable>-<replaceable>end</replaceable> <replaceable>format</replaceable>
</literallayout>
<para>The <literal>GET DATA</literal> command with TYPE=TXT and ARRANGEMENT=FIXED reads input
data from text files in fixed format, where each field is located in
particular fixed column positions within records of a case.  Its
capabilities are similar to those of DATA LIST FIXED (see <link linkend="DATA-LIST-FIXED">DATA LIST
FIXED</link>), with a few enhancements.
</para>
<para>The required <literal>FILE</literal> subcommand and optional <literal>FIRSTCASE</literal> and <literal>IMPORTCASE</literal>
subcommands are described above (see <link linkend="GET-DATA-_002fTYPE_003dTXT">GET DATA /TYPE=TXT</link>).
</para>
<para>The optional <literal>FIXCASE</literal> subcommand may be used to specify the positive
integer number of input lines that make up each case.  The default
value is 1.
</para>
<para>The <literal>VARIABLES</literal> subcommand, which is required, specifies the positions
at which each variable can be found.  For each variable, specify its
name, followed by its start and end column separated by &#8216;<literal>-</literal>&#8217;
(<emphasis>e.g.</emphasis> &#8216;<literal>0-9</literal>&#8217;), followed by an input format type (<emphasis>e.g.</emphasis>
&#8216;<literal>F</literal>&#8217;) or a full format specification (<emphasis>e.g.</emphasis> &#8216;<literal>DOLLAR12.2</literal>&#8217;).
For this command, columns are numbered starting from 0 at
the left column.  Introduce the variables in the second and later
lines of a case by a slash followed by the number of the line within
the case, <emphasis>e.g.</emphasis> &#8216;<literal>/2</literal>&#8217; for the second line.
</para>
<bridgehead renderas="sect3">Examples</bridgehead>

<para>Consider the following data on used cars:
</para>
<screen>model   year    mileage price   type    age
Civic   2002    29883   15900   Si      2
Civic   2003    13415   15900   EX      1
Civic   1992    107000  3800    n/a     12
Accord  2002    26613   17900   EX      1
</screen>
<para>The following syntax can be used to read the used car data:
</para>
<!-- If you change this example, change the regression test in -->
<!-- tests/language/commands/get-data.at to match. -->
<screen>GET DATA /TYPE=TXT /FILE='cars.data' /ARRANGEMENT=FIXED /FIRSTCASE=2
        /VARIABLES=model 0-7 A
                   year 8-15 F
                   mileage 16-23 F
                   price 24-31 F
                   type 32-40 A
                   age 40-47 F.
</screen>
</sect3>
</sect2>
</sect1>
<sect1 label="9.5" id="IMPORT">
<title>IMPORT</title>
<indexterm role="vr"><primary>IMPORT</primary></indexterm>

<literallayout>IMPORT
        /FILE=&#8217;<replaceable>file_name</replaceable>&#8217;
        /TYPE={COMM,TAPE}
        /DROP=<replaceable>var_list</replaceable>
        /KEEP=<replaceable>var_list</replaceable>
        /RENAME=(<replaceable>src_names</replaceable>=<replaceable>target_names</replaceable>)&#8230;
</literallayout>
<para>The <literal>IMPORT</literal> transformation clears the active dataset dictionary and
data and
replaces them with a dictionary and data from a system file or
portable file.
</para>
<para>The <literal>FILE</literal> subcommand, which is the only required subcommand, specifies
the portable file to be read as a file name string or a file handle
(see <link linkend="File-Handles">File Handles</link>).
</para>
<para>The <literal>TYPE</literal> subcommand is currently not used.
</para>
<para><literal>DROP</literal>, <literal>KEEP</literal>, and <literal>RENAME</literal> follow the syntax used by <literal>GET</literal> (see <link linkend="GET">GET</link>).
</para>
<para><literal>IMPORT</literal> does not cause the data to be read; only the dictionary.  The
data is read later, when a procedure is executed.
</para>
<para>Use of <literal>IMPORT</literal> to read a system file is a PSPP extension.
</para>
</sect1>
<sect1 label="9.6" id="SAVE">
<title>SAVE</title>
<indexterm role="vr"><primary>SAVE</primary></indexterm>

<literallayout>SAVE
        /OUTFILE={&#8217;<replaceable>file_name</replaceable>&#8217;,<replaceable>file_handle</replaceable>}
        /UNSELECTED={RETAIN,DELETE}
        /{UNCOMPRESSED,COMPRESSED,ZCOMPRESSED}
        /PERMISSIONS={WRITEABLE,READONLY}
        /DROP=<replaceable>var_list</replaceable>
        /KEEP=<replaceable>var_list</replaceable>
        /VERSION=<replaceable>version</replaceable>
        /RENAME=(<replaceable>src_names</replaceable>=<replaceable>target_names</replaceable>)&#8230;
        /NAMES
        /MAP
</literallayout>
<para>The <literal>SAVE</literal> procedure causes the dictionary and data in the active
dataset to
be written to a system file.
</para>
<para>OUTFILE is the only required subcommand.  Specify the system file
to be written as a string file name or a file handle
(see <link linkend="File-Handles">File Handles</link>).
</para>
<para>By default, cases excluded with FILTER are written to the system file.
These can be excluded by specifying <literal>DELETE</literal> on the <literal>UNSELECTED</literal>
subcommand.  Specifying <literal>RETAIN</literal> makes the default explicit.
</para>
<para>The <literal>UNCOMPRESSED</literal>, <literal>COMPRESSED</literal>, and
<literal>ZCOMPRESSED</literal> subcommand determine the system file&#8217;s
compression level:
</para>
<variablelist><varlistentry><term><literal>UNCOMPRESSED</literal>
</term><listitem><para>Data is not compressed.  Each numeric value uses 8 bytes of disk
space.  Each string value uses one byte per column width, rounded up
to a multiple of 8 bytes.
</para>
</listitem></varlistentry><varlistentry><term><literal>COMPRESSED</literal>
</term><listitem><para>Data is compressed with a simple algorithm.  Each integer numeric
value between &#8722;99 and 151, inclusive, or system missing value
uses one byte of disk space.  Each 8-byte segment of a string that
consists only of spaces uses 1 byte.  Any other numeric value or
8-byte string segment uses 9 bytes of disk space.
</para>
</listitem></varlistentry><varlistentry><term><literal>ZCOMPRESSED</literal>
</term><listitem><para>Data is compressed with the &#8220;deflate&#8221; compression algorithm
specified in RFC&#160;1951 (the same algorithm used by
<command>gzip</command>).  Files written with this compression level cannot be
read by PSPP 0.8.1 or earlier or by SPSS 20 or earlier.
</para></listitem></varlistentry></variablelist>
<para><literal>COMPRESSED</literal> is the default compression level.  The SET command
(see <link linkend="SET">SET</link>) can change this default.
</para>
<para>The <literal>PERMISSIONS</literal> subcommand specifies permissions for the new system
file.  WRITEABLE, the default, creates the file with read and write
permission.  READONLY creates the file for read-only access.
</para>
<para>By default, all the variables in the active dataset dictionary are written
to the system file.  The <literal>DROP</literal> subcommand can be used to specify a list
of variables not to be written.  In contrast, KEEP specifies variables
to be written, with all variables not specified not written.
</para>
<para>Normally variables are saved to a system file under the same names they
have in the active dataset.  Use the <literal>RENAME</literal> subcommand to change these names.
Specify, within parentheses, a list of variable names followed by an
equals sign (&#8216;<literal>=</literal>&#8217;) and the names that they should be renamed to.
Multiple parenthesized groups of variable names can be included on a
single <literal>RENAME</literal> subcommand.  Variables&#8217; names may be swapped using a
<literal>RENAME</literal> subcommand of the
form <literal>/RENAME=(<replaceable>A</replaceable> <replaceable>B</replaceable>=<replaceable>B</replaceable> <replaceable>A</replaceable>)</literal>.
</para>
<para>Alternate syntax for the <literal>RENAME</literal> subcommand allows the parentheses to be
eliminated.  When this is done, only a single variable may be renamed at
once.  For instance, <literal>/RENAME=<replaceable>A</replaceable>=<replaceable>B</replaceable></literal>.  This alternate syntax is
deprecated.
</para>
<para><literal>DROP</literal>, <literal>KEEP</literal>, and <literal>RENAME</literal> are performed in
left-to-right order.  They
each may be present any number of times.  <literal>SAVE</literal> never modifies
the active dataset.  <literal>DROP</literal>, <literal>KEEP</literal>, and <literal>RENAME</literal> only
affect the system file written to disk.
</para>
<para>The <literal>VERSION</literal> subcommand specifies the version of the file format. Valid
versions are 2 and 3.  The default version is 3.  In version 2 system
files, variable names longer than 8 bytes are truncated.  The two
versions are otherwise identical.
</para>
<para>The <literal>NAMES</literal> and <literal>MAP</literal> subcommands are currently ignored.
</para>
<para><literal>SAVE</literal> causes the data to be read.  It is a procedure.
</para>
</sect1>
<sect1 label="9.7" id="SAVE-DATA-COLLECTION">
<title>SAVE DATA COLLECTION</title>
<indexterm role="vr"><primary>SAVE DATA COLLECTION</primary></indexterm>

<literallayout>SAVE DATA COLLECTION
        /OUTFILE={&#8217;<replaceable>file_name</replaceable>&#8217;,<replaceable>file_handle</replaceable>}
        /METADATA={&#8217;<replaceable>file_name</replaceable>&#8217;,<replaceable>file_handle</replaceable>}
        /{UNCOMPRESSED,COMPRESSED,ZCOMPRESSED}
        /PERMISSIONS={WRITEABLE,READONLY}
        /DROP=<replaceable>var_list</replaceable>
        /KEEP=<replaceable>var_list</replaceable>
        /VERSION=<replaceable>version</replaceable>
        /RENAME=(<replaceable>src_names</replaceable>=<replaceable>target_names</replaceable>)&#8230;
        /NAMES
        /MAP
</literallayout>
<para>Like <literal>SAVE</literal>, <literal>SAVE DATA COLLECTION</literal> writes the dictionary and
data in the active dataset to a system file.  In addition, it writes
metadata to an additional XML metadata file.
</para>
<para>OUTFILE is required.  Specify the system file to be written as a
string file name or a file handle (see <link linkend="File-Handles">File Handles</link>).
</para>
<para>METADATA is also required.  Specify the metadata file to be written as
a string file name or a file handle.  Metadata files customarily use a
<filename>.mdd</filename> extension.
</para>
<para>The current implementation of this command is experimental.  It only
outputs an approximation of the metadata file format.  Please report
bugs.
</para>
<para>Other subcommands are optional.  They have the same meanings as in the
<literal>SAVE</literal> command.
</para>
<para><literal>SAVE DATA COLLECTION</literal> causes the data to be read.  It is a
procedure.
</para>
</sect1>
<sect1 label="9.8" id="SAVE-TRANSLATE">
<title>SAVE TRANSLATE</title>
<indexterm role="vr"><primary>SAVE TRANSLATE</primary></indexterm>

<literallayout>SAVE TRANSLATE
        /OUTFILE={&#8217;<replaceable>file_name</replaceable>&#8217;,<replaceable>file_handle</replaceable>}
        /TYPE={CSV,TAB}
        [/REPLACE]
        [/MISSING={IGNORE,RECODE}]

        [/DROP=<replaceable>var_list</replaceable>]
        [/KEEP=<replaceable>var_list</replaceable>]
        [/RENAME=(<replaceable>src_names</replaceable>=<replaceable>target_names</replaceable>)&#8230;]
        [/UNSELECTED={RETAIN,DELETE}]
        [/MAP]

        &#8230;additional subcommands depending on TYPE&#8230;
</literallayout>
<para>The <literal>SAVE TRANSLATE</literal> command is used to save data into various
formats understood by other applications.
</para>
<para>The <literal>OUTFILE</literal> and <literal>TYPE</literal> subcommands are mandatory.
<literal>OUTFILE</literal> specifies the file to be written, as a string file name or a file handle
(see <link linkend="File-Handles">File Handles</link>).  <literal>TYPE</literal> determines the type of the file or
source to read.  It must be one of the following:
</para>
<variablelist><varlistentry><term>CSV
</term><listitem><para>Comma-separated value format,
</para>
</listitem></varlistentry><varlistentry><term>TAB
</term><listitem><para>Tab-delimited format.
</para></listitem></varlistentry></variablelist>
<para>By default, <literal>SAVE TRANSLATE</literal> does not overwrite an existing file.  Use
<literal>REPLACE</literal> to force an existing file to be overwritten.
</para>
<para>With MISSING=IGNORE, the default, <literal>SAVE TRANSLATE</literal> treats user-missing
values as if they were not missing.  Specify MISSING=RECODE to output
numeric user-missing values like system-missing values and string
user-missing values as all spaces.
</para>
<para>By default, all the variables in the active dataset dictionary are
saved to the system file, but <literal>DROP</literal> or <literal>KEEP</literal> can
select a subset of variable to save.  The <literal>RENAME</literal> subcommand
can also be used to change the names under which variables are saved;
because they are used only in the output, these names do not have to
conform to the usual PSPP variable naming rules.  <literal>UNSELECTED</literal>
determines whether cases filtered out by the <literal>FILTER</literal> command are
written to the output file.  These subcommands have the same syntax
and meaning as on the <literal>SAVE</literal> command (see <link linkend="SAVE">SAVE</link>).
</para>
<para>Each supported file type has additional subcommands, explained in
separate sections below.
</para>
<para><literal>SAVE TRANSLATE</literal> causes the data to be read.  It is a procedure.
</para>

<sect2 label="9.8.1" id="SAVE-TRANSLATE-_002fTYPE_003dCSV-and-TYPE_003dTAB">
<title>Writing Comma- and Tab-Separated Data Files</title>

<literallayout>SAVE TRANSLATE
        /OUTFILE={&#8217;<replaceable>file_name</replaceable>&#8217;,<replaceable>file_handle</replaceable>}
        /TYPE=CSV
        [/REPLACE]
        [/MISSING={IGNORE,RECODE}]

        [/DROP=<replaceable>var_list</replaceable>]
        [/KEEP=<replaceable>var_list</replaceable>]
        [/RENAME=(<replaceable>src_names</replaceable>=<replaceable>target_names</replaceable>)&#8230;]
        [/UNSELECTED={RETAIN,DELETE}]

        [/FIELDNAMES]
        [/CELLS={VALUES,LABELS}]
        [/TEXTOPTIONS DELIMITER=&#8217;<replaceable>delimiter</replaceable>&#8217;]
        [/TEXTOPTIONS QUALIFIER=&#8217;<replaceable>qualifier</replaceable>&#8217;]
        [/TEXTOPTIONS DECIMAL={DOT,COMMA}]
        [/TEXTOPTIONS FORMAT={PLAIN,VARIABLE}]
</literallayout>
<para>The SAVE TRANSLATE command with TYPE=CSV or TYPE=TAB writes data in a
comma- or tab-separated value format similar to that described by
RFC&#160;4180.  Each variable becomes one output column, and each case
becomes one line of output.  If FIELDNAMES is specified, an additional
line at the top of the output file lists variable names.
</para>
<para>The CELLS and TEXTOPTIONS FORMAT settings determine how values are
written to the output file:
</para>
<variablelist><varlistentry><term>CELLS=VALUES FORMAT=PLAIN (the default settings)
</term><listitem><para>Writes variables to the output in &#8220;plain&#8221; formats that ignore the
details of variable formats.  Numeric values are written as plain
decimal numbers with enough digits to indicate their exact values in
machine representation.  Numeric values include &#8216;<literal>e</literal>&#8217; followed by
an exponent if the exponent value would be less than -4 or greater
than 16.  Dates are written in MM/DD/YYYY format and times in HH:MM:SS
format.  WKDAY and MONTH values are written as decimal numbers.
</para>
<para>Numeric values use, by default, the decimal point character set with
SET DECIMAL (see <link linkend="SET-DECIMAL">SET DECIMAL</link>).  Use DECIMAL=DOT or DECIMAL=COMMA
to force a particular decimal point character.
</para>
</listitem></varlistentry><varlistentry><term>CELLS=VALUES FORMAT=VARIABLE
</term><listitem><para>Writes variables using their print formats.  Leading and trailing
spaces are removed from numeric values, and trailing spaces are
removed from string values.
</para>
</listitem></varlistentry><varlistentry><term>CELLS=LABEL FORMAT=PLAIN
</term><term>CELLS=LABEL FORMAT=VARIABLE
</term><listitem><para>Writes value labels where they exist, and otherwise writes the values
themselves as described above.
</para></listitem></varlistentry></variablelist>
<para>Regardless of CELLS and TEXTOPTIONS FORMAT, numeric system-missing
values are output as a single space.
</para>
<para>For TYPE=TAB, tab characters delimit values.  For TYPE=CSV, the
TEXTOPTIONS DELIMITER and DECIMAL settings determine the character
that separate values within a line.  If DELIMITER is specified, then
the specified string separate values.  If DELIMITER is not specified,
then the default is a comma with DECIMAL=DOT or a semicolon with
DECIMAL=COMMA.  If DECIMAL is not given either, it is implied by the
decimal point character set with SET DECIMAL (see <link linkend="SET-DECIMAL">SET DECIMAL</link>).
</para>
<para>The TEXTOPTIONS QUALIFIER setting specifies a character that is output
before and after a value that contains the delimiter character or the
qualifier character.  The default is a double quote (&#8216;<literal>&quot;</literal>&#8217;).  A
qualifier character that appears within a value is doubled.
</para>
</sect2>
</sect1>
<sect1 label="9.9" id="SYSFILE-INFO">
<title>SYSFILE INFO</title>
<indexterm role="vr"><primary>SYSFILE INFO</primary></indexterm>

<literallayout>SYSFILE INFO FILE=&#8217;<replaceable>file_name</replaceable>&#8217; [ENCODING=&#8217;<replaceable>encoding</replaceable>&#8217;].
</literallayout>
<para><literal>SYSFILE INFO</literal> reads the dictionary in an SPSS system file,
SPSS/PC+ system file, or SPSS portable file, and displays the
information in its dictionary.
</para>
<para>Specify a file name or file handle.  <literal>SYSFILE INFO</literal> reads that
file and displays information on its dictionary.
</para>
<para>PSPP automatically detects the encoding of string data in the file,
when possible.  The character encoding of old SPSS system files cannot
always be guessed correctly, and SPSS/PC+ system files do not include
any indication of their encoding.  Specify the <literal>ENCODING</literal>
subcommand with an <acronym>IANA</acronym> character set name as its string
argument to override the default, or specify <literal>ENCODING='DETECT'</literal>
to analyze and report possibly valid encodings for the system file.
The <literal>ENCODING</literal> subcommand is a PSPP extension.
</para>
<para><literal>SYSFILE INFO</literal> does not affect the current active dataset.
</para>
</sect1>
<sect1 label="9.10" id="XEXPORT">
<title>XEXPORT</title>
<indexterm role="vr"><primary>XEXPORT</primary></indexterm>

<literallayout>XEXPORT
        /OUTFILE=&#8217;<replaceable>file_name</replaceable>&#8217;
        /DIGITS=<replaceable>n</replaceable>
        /DROP=<replaceable>var_list</replaceable>
        /KEEP=<replaceable>var_list</replaceable>
        /RENAME=(<replaceable>src_names</replaceable>=<replaceable>target_names</replaceable>)&#8230;
        /TYPE={COMM,TAPE}
        /MAP
</literallayout>
<para>The <literal>XEXPORT</literal> transformation writes the active dataset dictionary and
data to a specified portable file.
</para>
<para>This transformation is a PSPP extension.
</para>
<para>It is similar to the <literal>EXPORT</literal> procedure, with two differences:
</para>
<itemizedlist><listitem><para><literal>XEXPORT</literal> is a transformation, not a procedure.  It is executed when
the data is read by a procedure or procedure-like command.
</para>
</listitem><listitem><para><literal>XEXPORT</literal> does not support the <literal>UNSELECTED</literal> subcommand.
</para></listitem></itemizedlist>
<para>See <link linkend="EXPORT">EXPORT</link>, for more information.
</para>
</sect1>
<sect1 label="9.11" id="XSAVE">
<title>XSAVE</title>
<indexterm role="vr"><primary>XSAVE</primary></indexterm>

<literallayout>XSAVE
        /OUTFILE=&#8217;<replaceable>file_name</replaceable>&#8217;
        /{UNCOMPRESSED,COMPRESSED,ZCOMPRESSED}
        /PERMISSIONS={WRITEABLE,READONLY}
        /DROP=<replaceable>var_list</replaceable>
        /KEEP=<replaceable>var_list</replaceable>
        /VERSION=<replaceable>version</replaceable>
        /RENAME=(<replaceable>src_names</replaceable>=<replaceable>target_names</replaceable>)&#8230;
        /NAMES
        /MAP
</literallayout>
<para>The <literal>XSAVE</literal> transformation writes the active dataset&#8217;s dictionary and
data to a system file.  It is similar to the <literal>SAVE</literal>
procedure, with two differences:
</para>
<itemizedlist><listitem><para><literal>XSAVE</literal> is a transformation, not a procedure.  It is executed when
the data is read by a procedure or procedure-like command.
</para>
</listitem><listitem><para><literal>XSAVE</literal> does not support the <literal>UNSELECTED</literal> subcommand.
</para></listitem></itemizedlist>
<para>See <link linkend="SAVE">SAVE</link>, for more information.
<!-- PSPP - a program for statistical analysis. -->
<!-- Copyright (C) 2017, 2020 Free Software Foundation, Inc. -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.3 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<!-- A copy of the license is included in the section entitled "GNU -->
<!-- Free Documentation License". -->
<!-- -->
</para></sect1>
</chapter>
<chapter label="10" id="Combining-Data-Files">
<title>Combining Data Files</title>

<para>This chapter describes commands that allow data from system files,
portable files, and open datasets to be combined to
form a new active dataset.  These commands can combine data files in the
following ways:
</para>
<itemizedlist><listitem><para><literal>ADD FILES</literal> interleaves or appends the cases from each input file.
It is used with input files that have variables in common, but
distinct sets of cases.
</para>
</listitem><listitem><para><literal>MATCH FILES</literal> adds the data together in cases that match across
multiple input files.  It is used with input files that have cases in
common, but different information about each case.
</para>
</listitem><listitem><para><literal>UPDATE</literal> updates a master data file from data in a set of
transaction files.  Each case in a transaction data file modifies a
matching case in the primary data file, or it adds a new case if no
matching case can be found.
</para></listitem></itemizedlist>
<para>These commands share the majority of their syntax, which is described
in the following section, followed by one section for each command
that describes its specific syntax and semantics.
</para>

<sect1 label="10.1" id="Combining-Files-Common-Syntax">
<title>Common Syntax</title>

<literallayout>Per input file:
        /FILE={*,&#8217;<replaceable>file_name</replaceable>&#8217;}
        [/RENAME=(<replaceable>src_names</replaceable>=<replaceable>target_names</replaceable>)&#8230;]
        [/IN=<replaceable>var_name</replaceable>]
        [/SORT]

Once per command:
        /BY <replaceable>var_list</replaceable>[({D|A})] [<replaceable>var_list</replaceable>[({D|A}]]&#8230;
        [/DROP=<replaceable>var_list</replaceable>]
        [/KEEP=<replaceable>var_list</replaceable>]
        [/FIRST=<replaceable>var_name</replaceable>]
        [/LAST=<replaceable>var_name</replaceable>]
        [/MAP]
</literallayout>
<para>This section describes the syntactical features in common among the
<literal>ADD FILES</literal>, <literal>MATCH FILES</literal>, and <literal>UPDATE</literal> commands.  The
following sections describe details specific to each command.
</para>
<para>Each of these commands reads two or more input files and combines them.
The command&#8217;s output becomes the new active dataset.
None of the commands actually change the input files.
Therefore, if you want the changes to become permanent, you must explicitly
save them using an appropriate procedure or transformation (see <link linkend="System-and-Portable-File-IO">System and Portable File IO</link>).
</para>
<para>The syntax of each command begins with a specification of the files to
be read as input.  For each input file, specify FILE with a system
file or portable file&#8217;s name as a string, a dataset (see <link linkend="Datasets">Datasets</link>)
or file handle name, (see <link linkend="File-Handles">File Handles</link>), or an asterisk (&#8216;<literal>*</literal>&#8217;)
to use the active dataset as input.  Use of portable files on <literal>FILE</literal> is a
PSPP extension.
</para>
<para>At least two <literal>FILE</literal> subcommands must be specified.  If the active dataset
is used as an input source, then <literal>TEMPORARY</literal> must not be in
effect.
</para>
<para>Each <literal>FILE</literal> subcommand may be followed by any number of <literal>RENAME</literal>
subcommands that specify a parenthesized group or groups of variable
names as they appear in the input file, followed by those variables&#8217;
new names, separated by an equals sign (<literal>=</literal>),
<emphasis>e.g.</emphasis> <literal>/RENAME=(OLD1=NEW1)(OLD2=NEW2)</literal>.  To rename a single
variable, the parentheses may be omitted: <literal>/RENAME=<replaceable>old</replaceable>=<replaceable>new</replaceable></literal>.
Within a parenthesized group, variables are renamed simultaneously, so
that <literal>/RENAME=(<replaceable>A</replaceable> <replaceable>B</replaceable>=<replaceable>B</replaceable> <replaceable>A</replaceable>)</literal> exchanges the
names of variables <replaceable>A</replaceable> and <replaceable>B</replaceable>.
Otherwise, renaming occurs in left-to-right order.
</para>
<para>Each <literal>FILE</literal> subcommand may optionally be followed by a single <literal>IN</literal>
subcommand, which creates a numeric variable with the specified name
and format F1.0.  The IN variable takes value 1 in an output case if
the given input file contributed to that output case, and 0 otherwise.
The <literal>DROP</literal>, <literal>KEEP</literal>, and <literal>RENAME</literal> subcommands have no effect on IN variables.
</para>
<para>If <literal>BY</literal> is used (see below), the <literal>SORT</literal> keyword must be specified after a
<literal>FILE</literal> if that input file is not already sorted on the <literal>BY</literal> variables.
When <literal>SORT</literal> is specified, PSPP sorts the input file&#8217;s data on the <literal>BY</literal>
variables before it applies it to the command.  When <literal>SORT</literal> is used, <literal>BY</literal>
is required.  <literal>SORT</literal> is a PSPP extension.
</para>
<para>PSPP merges the dictionaries of all of the input files to form the
dictionary of the new active dataset, like so:
</para>
<itemizedlist><listitem><para>The variables in the new active dataset are the union of all the input files&#8217;
variables, matched based on their name.  When a single input file
contains a variable with a given name, the output file will contain
exactly that variable.  When more than one input file contains a
variable with a given name, those variables must be all string or all numeric.
If they are string variables, then the result will have the width of the longest
variable with that name, with narrower values padded on the right with spaces
to fill the width.
Variables are matched after renaming with the <literal>RENAME</literal> subcommand.
Thus, <literal>RENAME</literal> can be used to resolve conflicts.
Only variables in the output file can conflict, so <literal>DROP</literal> or
<literal>KEEP</literal>, as described below, can also resolve a conflict.
</para>
</listitem><listitem><para>The variable label for each output variable is taken from the first
specified input file that has a variable label for that variable, and
similarly for value labels and missing values.
</para>
</listitem><listitem><para>The file label of the new active dataset (see <link linkend="FILE-LABEL">FILE LABEL</link>) is that of the
first specified <literal>FILE</literal> that has a file label.
</para>
</listitem><listitem><para>The documents in the new active dataset (see <link linkend="DOCUMENT">DOCUMENT</link>) are the
concatenation of all the input files&#8217; documents, in the order in which
the <literal>FILE</literal> subcommands are specified.
</para>
</listitem><listitem><para>If all of the input files are weighted on the same variable, then the
new active dataset is weighted on that variable.  Otherwise, the new
active dataset is not weighted.
</para></listitem></itemizedlist>
<para>The remaining subcommands apply to the output file as a whole, rather
than to individual input files.  They must be specified at the end of
the command specification, following all of the <literal>FILE</literal> and related
subcommands.  The most important of these subcommands is <literal>BY</literal>, which
specifies a set of one or more variables that may be used to find
corresponding cases in each of the input files.  The variables
specified on <literal>BY</literal> must be present in all of the input files.
Furthermore, if any of the input files are not sorted on the <literal>BY</literal>
variables, then <literal>SORT</literal> must be specified for those input files.
</para>
<para>The variables listed on <literal>BY</literal> may include (A) or (D) annotations to
specify ascending or descending sort order.  See <link linkend="SORT-CASES">SORT CASES</link>, for
more details on this notation.  Adding (A) or (D) to the <literal>BY</literal> subcommand
specification is a PSPP extension.
</para>
<para>The <literal>DROP</literal> subcommand can be used to specify a list of variables to
exclude from the output.  By contrast, the <literal>KEEP</literal> subcommand can be used
to specify variables to include in the output; all variables not
listed are dropped.  <literal>DROP</literal> and <literal>KEEP</literal> are executed in left-to-right order
and may be repeated any number of times.  <literal>DROP</literal> and <literal>KEEP</literal> do not affect
variables created by the <literal>IN</literal>, <literal>FIRST</literal>, and <literal>LAST</literal> subcommands, which are
always included in the new active dataset, but they can be used to drop
<literal>BY</literal> variables.
</para>
<para>The <literal>FIRST</literal> and <literal>LAST</literal> subcommands are optional.  They may only be
specified on <literal>MATCH FILES</literal> and <literal>ADD FILES</literal>, and only when <literal>BY</literal>
is used.  <literal>FIRST</literal> and <literal>LIST</literal> each adds a numeric variable to the new
active dataset, with the name given as the subcommand&#8217;s argument and F1.0
print and write formats.  The value of the <literal>FIRST</literal> variable is 1 in the
first output case with a given set of values for the <literal>BY</literal> variables, and
0 in other cases.  Similarly, the <literal>LAST</literal> variable is 1 in the last case
with a given of <literal>BY</literal> values, and 0 in other cases.
</para>
<para>When any of these commands creates an output case, variables that are
only in files that are not present for the current case are set to the
system-missing value for numeric variables or spaces for string
variables.
</para>
<para>These commands may combine any number of files, limited only by the
machine&#8217;s memory.
</para>
</sect1>
<sect1 label="10.2" id="ADD-FILES">
<title>ADD FILES</title>
<indexterm role="vr"><primary>ADD FILES</primary></indexterm>

<literallayout>ADD FILES

Per input file:
        /FILE={*,&#8217;<replaceable>file_name</replaceable>&#8217;}
        [/RENAME=(<replaceable>src_names</replaceable>=<replaceable>target_names</replaceable>)&#8230;]
        [/IN=<replaceable>var_name</replaceable>]
        [/SORT]

Once per command:
        [/BY <replaceable>var_list</replaceable>[({D|A})] [<replaceable>var_list</replaceable>[({D|A})]&#8230;]]
        [/DROP=<replaceable>var_list</replaceable>]
        [/KEEP=<replaceable>var_list</replaceable>]
        [/FIRST=<replaceable>var_name</replaceable>]
        [/LAST=<replaceable>var_name</replaceable>]
        [/MAP]
</literallayout>
<para><literal>ADD FILES</literal> adds cases from multiple input files.  The output,
which replaces the active dataset, consists all of the cases in all of
the input files.
</para>
<para><literal>ADD FILES</literal> shares the bulk of its syntax with other PSPP commands for
combining multiple data files.  See <link linkend="Combining-Files-Common-Syntax">Combining Files Common Syntax</link>,
above, for an explanation of this common syntax.
</para>
<para>When <literal>BY</literal> is not used, the output of <literal>ADD FILES</literal> consists of all the cases
from the first input file specified, followed by all the cases from
the second file specified, and so on.  When <literal>BY</literal> is used, the output is
additionally sorted on the <literal>BY</literal> variables.
</para>
<para>When <literal>ADD FILES</literal> creates an output case, variables that are not part of
the input file from which the case was drawn are set to the
system-missing value for numeric variables or spaces for string
variables.
</para>
</sect1>
<sect1 label="10.3" id="MATCH-FILES">
<title>MATCH FILES</title>
<indexterm role="vr"><primary>MATCH FILES</primary></indexterm>

<literallayout>MATCH FILES

Per input file:
        /{FILE,TABLE}={*,&#8217;<replaceable>file_name</replaceable>&#8217;}
        [/RENAME=(<replaceable>src_names</replaceable>=<replaceable>target_names</replaceable>)&#8230;]
        [/IN=<replaceable>var_name</replaceable>]
        [/SORT]

Once per command:
        /BY <replaceable>var_list</replaceable>[({D|A}] [<replaceable>var_list</replaceable>[({D|A})]&#8230;]
        [/DROP=<replaceable>var_list</replaceable>]
        [/KEEP=<replaceable>var_list</replaceable>]
        [/FIRST=<replaceable>var_name</replaceable>]
        [/LAST=<replaceable>var_name</replaceable>]
        [/MAP]
</literallayout>
<para><literal>MATCH FILES</literal> merges sets of corresponding cases in multiple
input files into single cases in the output, combining their data.
</para>
<para><literal>MATCH FILES</literal> shares the bulk of its syntax with other PSPP commands for
combining multiple data files.  See <link linkend="Combining-Files-Common-Syntax">Combining Files Common Syntax</link>,
above, for an explanation of this common syntax.
</para>
<para>How <literal>MATCH FILES</literal> matches up cases from the input files depends on
whether <literal>BY</literal> is specified:
</para>
<itemizedlist><listitem><para>If <literal>BY</literal> is not used, <literal>MATCH FILES</literal> combines the first case from each input
file to produce the first output case, then the second case from each
input file for the second output case, and so on.  If some input files
have fewer cases than others, then the shorter files do not contribute
to cases output after their input has been exhausted.
</para>
</listitem><listitem><para>If <literal>BY</literal> is used, <literal>MATCH FILES</literal> combines cases from each input file that
have identical values for the <literal>BY</literal> variables.
</para>
<para>When <literal>BY</literal> is used, <literal>TABLE</literal> subcommands may be used to introduce <firstterm>table
lookup file</firstterm>.  <literal>TABLE</literal> has same syntax as <literal>FILE</literal>, and the <literal>RENAME</literal>, <literal>IN</literal>, and
<literal>SORT</literal> subcommands may follow a <literal>TABLE</literal> in the same way as <literal>FILE</literal>.
Regardless of the number of <literal>TABLE</literal>s, at least one <literal>FILE</literal> must specified.
Table lookup files are treated in the same way as other input files
for most purposes and, in particular, table lookup files must be
sorted on the <literal>BY</literal> variables or the <literal>SORT</literal> subcommand must be specified
for that <literal>TABLE</literal>.
</para>
<para>Cases in table lookup files are not consumed after they have been used
once.  This means that data in table lookup files can correspond to
any number of cases in <literal>FILE</literal> input files.  Table lookup files are
analogous to lookup tables in traditional relational database systems.
</para>
<para>If a table lookup file contains more than one case with a given set of
<literal>BY</literal> variables, only the first case is used.
</para></listitem></itemizedlist>
<para>When <literal>MATCH FILES</literal> creates an output case, variables that are only in
files that are not present for the current case are set to the
system-missing value for numeric variables or spaces for string
variables.
</para>
</sect1>
<sect1 label="10.4" id="UPDATE">
<title>UPDATE</title>
<indexterm role="vr"><primary>UPDATE</primary></indexterm>

<literallayout>UPDATE

Per input file:
        /FILE={*,&#8217;<replaceable>file_name</replaceable>&#8217;}
        [/RENAME=(<replaceable>src_names</replaceable>=<replaceable>target_names</replaceable>)&#8230;]
        [/IN=<replaceable>var_name</replaceable>]
        [/SORT]

Once per command:
        /BY <replaceable>var_list</replaceable>[({D|A})] [<replaceable>var_list</replaceable>[({D|A})]]&#8230;
        [/DROP=<replaceable>var_list</replaceable>]
        [/KEEP=<replaceable>var_list</replaceable>]
        [/MAP]
</literallayout>
<para><literal>UPDATE</literal> updates a <firstterm>master file</firstterm> by applying modifications
from one or more <firstterm>transaction files</firstterm>.
</para>
<para><literal>UPDATE</literal> shares the bulk of its syntax with other PSPP commands for
combining multiple data files.  See <link linkend="Combining-Files-Common-Syntax">Combining Files Common Syntax</link>,
above, for an explanation of this common syntax.
</para>
<para>At least two <literal>FILE</literal> subcommands must be specified.  The first <literal>FILE</literal>
subcommand names the master file, and the rest name transaction files.
Every input file must either be sorted on the variables named on the
<literal>BY</literal> subcommand, or the <literal>SORT</literal> subcommand must be used just after the <literal>FILE</literal>
subcommand for that input file.
</para>
<para><literal>UPDATE</literal> uses the variables specified on the <literal>BY</literal> subcommand, which is
required, to attempt to match each case in a transaction file with a
case in the master file:
</para>
<itemizedlist><listitem><para>When a match is found, then the values of the variables present in the
transaction file replace those variables&#8217; values in the new active
file.  If there are matching cases in more than more transaction file,
PSPP applies the replacements from the first transaction file, then
from the second transaction file, and so on.  Similarly, if a single
transaction file has cases with duplicate <literal>BY</literal> values, then those are
applied in order to the master file.
</para>
<para>When a variable in a transaction file has a missing value or when a string
variable&#8217;s value is all blanks, that value is never used to update the
master file.
</para>
</listitem><listitem><para>If a case in the master file has no matching case in any transaction
file, then it is copied unchanged to the output.
</para>
</listitem><listitem><para>If a case in a transaction file has no matching case in the master
file, then it causes a new case to be added to the output, initialized
from the values in the transaction file.
</para></listitem></itemizedlist><!-- PSPP - a program for statistical analysis. -->
<!-- Copyright (C) 2017, 2020 Free Software Foundation, Inc. -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.3 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<!-- A copy of the license is included in the section entitled "GNU -->
<!-- Free Documentation License". -->
<!-- -->
</sect1>
</chapter>
<chapter label="11" id="Manipulating-Variables">
<title>Manipulating Variables</title>
<indexterm role="cp"><primary>Variables</primary></indexterm>

<para>Every value in a dataset is associated with a <firstterm>variable</firstterm>.
Variables describe what the values represent and properties of those values,
such as the format in which they should be displayed, whether they are numeric
or alphabetic and how missing values should be represented.
There are several utility commands for examining and adjusting variables.
</para>

<sect1 label="11.1" id="DISPLAY">
<title>DISPLAY</title>
<indexterm role="vr"><primary>DISPLAY</primary></indexterm>

<para>The <literal>DISPLAY</literal> command displays information about the variables in the active dataset.
A variety of different forms of information can be requested.
By default, all variables in the active dataset are displayed.  However you can select
variables of interest using the <literal>/VARIABLES</literal> subcommand.
</para>
<literallayout>DISPLAY [SORTED] NAMES [[/VARIABLES=]<replaceable>var_list</replaceable>].
DISPLAY [SORTED] INDEX [[/VARIABLES=]<replaceable>var_list</replaceable>].
DISPLAY [SORTED] LABELS [[/VARIABLES=]<replaceable>var_list</replaceable>].
DISPLAY [SORTED] VARIABLES [[/VARIABLES=]<replaceable>var_list</replaceable>].
DISPLAY [SORTED] DICTIONARY [[/VARIABLES=]<replaceable>var_list</replaceable>].
DISPLAY [SORTED] SCRATCH [[/VARIABLES=]<replaceable>var_list</replaceable>].
DISPLAY [SORTED] ATTRIBUTES [[/VARIABLES=]<replaceable>var_list</replaceable>].
DISPLAY [SORTED] @ATTRIBUTES [[/VARIABLES=]<replaceable>var_list</replaceable>].
DISPLAY [SORTED] VECTORS.
</literallayout>
<para>The following keywords primarily cause information about variables to
be displayed.  With these keywords, by default information is
displayed about all variable in the active dataset, in the order that
variables occur in the active dataset dictionary.  The <literal>SORTED</literal> keyword
causes output to be sorted alphabetically by variable name.
</para>
<variablelist><varlistentry><term>NAMES
</term><listitem><para>The variables&#8217; names are displayed.
</para>
</listitem></varlistentry><varlistentry><term>INDEX
</term><listitem><para>The variables&#8217; names are displayed along with a value describing their
position within the active dataset dictionary.
</para>
</listitem></varlistentry><varlistentry><term>LABELS
</term><listitem><para>Variable names, positions, and variable labels are displayed.
</para>
</listitem></varlistentry><varlistentry><term>VARIABLES
</term><listitem><para>Variable names, positions, print and write formats, and missing values
are displayed.
</para>
</listitem></varlistentry><varlistentry><term>DICTIONARY
</term><listitem><para>Variable names, positions, print and write formats, missing values,
variable labels, and value labels are displayed.
</para>
</listitem></varlistentry><varlistentry><term>SCRATCH
</term><listitem><para>Variable names are displayed, for scratch variables only (see <link linkend="Scratch-Variables">Scratch
Variables</link>).
</para>
</listitem></varlistentry><varlistentry><term>ATTRIBUTES
</term><term>@ATTRIBUTES
</term><listitem><para>Datafile and variable attributes are displayed.
The first form of the command omits those attributes
whose names begin with <literal>@</literal> or <literal>$@</literal>.
In the second for, all datafile and variable attributes are displayed.
</para></listitem></varlistentry></variablelist>
<para>With the <literal>VECTOR</literal> keyword, <literal>DISPLAY</literal> lists all the currently
declared vectors.  If the <literal>SORTED</literal> keyword is given, the vectors are
listed in alphabetical order; otherwise, they are listed in textual
order of definition within the PSPP syntax file.
</para>
<para>For related commands, see <link linkend="DISPLAY-DOCUMENTS">DISPLAY DOCUMENTS</link> and <link linkend="DISPLAY-FILE-LABEL">DISPLAY
FILE LABEL</link>.
</para>
</sect1>
<sect1 label="11.2" id="NUMERIC">
<title>NUMERIC</title>
<indexterm role="vr"><primary>NUMERIC</primary></indexterm>

<para><literal>NUMERIC</literal> explicitly declares new numeric variables, optionally
setting their output formats.
</para>
<literallayout>NUMERIC <replaceable>var_list</replaceable> [(<replaceable>fmt_spec</replaceable>)] [/<replaceable>var_list</replaceable> [(<replaceable>fmt_spec</replaceable>)]]&#8230;
</literallayout>
<para>Specify the names of the new numeric variables as <replaceable>var_list</replaceable>.  If
you wish to set the variables&#8217; output formats, follow their names by
an output format specification in parentheses (see <link linkend="Input-and-Output-Formats">Input and Output
Formats</link>); otherwise, the default is F8.2.
</para>
<para>Variables created with <literal>NUMERIC</literal> are initialized to the
system-missing value.
</para>
</sect1>
<sect1 label="11.3" id="STRING">
<title>STRING</title>
<indexterm role="vr"><primary>STRING</primary></indexterm>

<para><literal>STRING</literal> creates new string variables.
</para>
<literallayout>STRING <replaceable>var_list</replaceable> (<replaceable>fmt_spec</replaceable>) [/<replaceable>var_list</replaceable> (<replaceable>fmt_spec</replaceable>)] [&#8230;].
</literallayout>
<para>Specify a list of names for the variable you want to create,
followed by the desired output format specification in
parentheses (see <link linkend="Input-and-Output-Formats">Input and Output Formats</link>).
Variable widths are
implicitly derived from the specified output formats.
The created variables will be initialized to spaces.
</para>
<para>If you want to create several variables with  distinct
output formats, you can either use two or more separate <literal>STRING</literal> commands,
or you can specify further variable list and format specification pairs, each separated
from the previous by a slash (&#8216;<literal>/</literal>&#8217;).
</para>
<para>The following example is one way to create three string variables; Two of the
variables have format A24 and the other A80:
</para><screen>STRING firstname lastname (A24) / address (A80).
</screen>
<para>Here is another way to achieve the same result:
</para><screen>STRING firstname lastname (A24).
STRING address (A80).
</screen>
<para>&#8230; and here is yet another way:
</para>
<screen>STRING firstname (A24).
STRING lastname (A24).
STRING address (A80).
</screen>
</sect1>
<sect1 label="11.4" id="RENAME-VARIABLES">
<title>RENAME VARIABLES</title>
<indexterm role="vr"><primary>RENAME VARIABLES</primary></indexterm>

<para><literal>RENAME VARIABLES</literal> changes the names of variables in the active
dataset.
</para>
<literallayout>RENAME VARIABLES (<replaceable>old_names</replaceable>=<replaceable>new_names</replaceable>)&#8230; .
</literallayout>
<para>Specify lists of the old variable names and new
variable names, separated by an equals sign (&#8216;<literal>=</literal>&#8217;), within
parentheses.  There must be the same number of old and new variable
names.  Each old variable is renamed to the corresponding new variable
name.  Multiple parenthesized groups of variables may be specified.
When the old and new variable names contain only a single variable name,
the parentheses are optional.
</para>
<para><literal>RENAME VARIABLES</literal> takes effect immediately.  It does not cause the data
to be read.
</para>
<para><literal>RENAME VARIABLES</literal> may not be specified following <literal>TEMPORARY</literal>
(see <link linkend="TEMPORARY">TEMPORARY</link>).
</para>
</sect1>
<sect1 label="11.5" id="SORT-VARIABLES">
<title>SORT VARIABLES</title>
<indexterm role="vr"><primary>SORT VARIABLES</primary></indexterm>

<para><literal>SORT VARIABLES</literal> reorders the variables in the active dataset&#8217;s dictionary
according to a chosen sort key.
</para>
<literallayout>SORT VARIABLES [BY]
    (NAME | TYPE | FORMAT | LABEL | VALUES | MISSING | MEASURE
     | ROLE | COLUMNS | ALIGNMENT | ATTRIBUTE <replaceable>name</replaceable>)
    [(D)].
</literallayout>
<para>The main specification is one of the following identifiers, which
determines how the variables are sorted:
</para>
<variablelist><varlistentry><term>NAME
</term><listitem><para>Sorts the variables according to their names, in a case-insensitive
fashion.  However, when variable names differ only in a number at the
end, they are sorted numerically.  For example, <literal>VAR5</literal> is sorted
before <literal>VAR400</literal> even though &#8216;<literal>4</literal>&#8217; precedes &#8216;<literal>5</literal>&#8217;.
</para>
</listitem></varlistentry><varlistentry><term>TYPE
</term><listitem><para>Sorts numeric variables before string variables, and shorter string
variables before longer ones.
</para>
</listitem></varlistentry><varlistentry><term>FORMAT
</term><listitem><para>Groups variables by print format; within a format, sorts narrower
formats before wider ones; with the same format and width, sorts fewer
decimal places before more decimal places.
See <link linkend="FORMATS">FORMATS</link>.
</para>
</listitem></varlistentry><varlistentry><term>LABEL
</term><listitem><para>Sorts variables without a variable label before those with one.
See <link linkend="VARIABLE-LABELS">VARIABLE LABELS</link>.
</para>
</listitem></varlistentry><varlistentry><term>VALUES
</term><listitem><para>Sorts variables without value labels before those with some.
See <link linkend="VALUE-LABELS">VALUE LABELS</link>.
</para>
</listitem></varlistentry><varlistentry><term>MISSING
</term><listitem><para>Sorts variables without missing values before those with some.
See <link linkend="MISSING-VALUES">MISSING VALUES</link>.
</para>
</listitem></varlistentry><varlistentry><term>MEASURE
</term><listitem><para>Sorts nominal variables first, followed by ordinal variables, followed
by scale variables.  See <link linkend="VARIABLE-LEVEL">VARIABLE LEVEL</link>.
</para>
</listitem></varlistentry><varlistentry><term>ROLE
</term><listitem><para>Groups variables according to their role.  See <link linkend="VARIABLE-ROLE">VARIABLE ROLE</link>.
</para>
</listitem></varlistentry><varlistentry><term>COLUMNS
</term><listitem><para>Sorts variables in ascending display width.  See <link linkend="VARIABLE-WIDTH">VARIABLE WIDTH</link>.
</para>
</listitem></varlistentry><varlistentry><term>ALIGNMENT
</term><listitem><para>Sorts variables according to their alignment, first left-aligned, then
right-aligned, then centered.  See <link linkend="VARIABLE-ALIGNMENT">VARIABLE ALIGNMENT</link>.
</para>
</listitem></varlistentry><varlistentry><term>ATTRIBUTE <replaceable>name</replaceable>
</term><listitem><para>Sorts variables according to the first value of their <replaceable>name</replaceable>
attribute.  Variables without attribute are sorted first.
See <link linkend="VARIABLE-ATTRIBUTE">VARIABLE ATTRIBUTE</link>.
</para></listitem></varlistentry></variablelist>
<para>Only one sort criterion can be specified.  The sort is &#8220;stable,&#8221; so
to sort on multiple criteria one may perform multiple sorts.  For
example, the following will sort primarily based on alignment, with
variables that have the same alignment ordered based on display width:
</para>
<screen>SORT VARIABLES BY COLUMNS.
SORT VARIABLES BY ALIGNMENT.
</screen>
<para>Specify <literal>(D)</literal> to reverse the sort order.
</para>
</sect1>
<sect1 label="11.6" id="DELETE-VARIABLES">
<title>DELETE VARIABLES</title>
<indexterm role="vr"><primary>DELETE VARIABLES</primary></indexterm>

<para><literal>DELETE VARIABLES</literal> deletes the specified variables from the dictionary.
</para>
<literallayout>DELETE VARIABLES <replaceable>var_list</replaceable>.
</literallayout>
<para><literal>DELETE VARIABLES</literal> should not be used after defining transformations
but before executing a procedure.  If it is used in such a context, it
causes the data to be read.  If it is used while <literal>TEMPORARY</literal> is in
effect, it causes the temporary transformations to become permanent.
</para>
<para><literal>DELETE VARIABLES</literal> may not be used to delete all variables from the
dictionary; use <literal>NEW FILE</literal> to do that (see <link linkend="NEW-FILE">NEW FILE</link>).
</para>
</sect1>
<sect1 label="11.7" id="VARIABLE-LABELS">
<title>VARIABLE LABELS</title>
<indexterm role="vr"><primary>VARIABLE LABELS</primary></indexterm>

<para>In addition to a variable&#8217;s name, each variable can have a
<firstterm>label</firstterm>.  Whereas a variable name is a concise, easy-to-type
mnemonic for the variable, a label may be longer and more descriptive.
</para>
<literallayout>VARIABLE LABELS
        <replaceable>variable</replaceable> &#8217;<replaceable>label</replaceable>&#8217;
        [<replaceable>variable</replaceable> &#8217;<replaceable>label</replaceable>&#8217;]&#8230;
</literallayout>
<para><literal>VARIABLE LABELS</literal> associates explanatory names
with variables.  This name, called a <firstterm>variable label</firstterm>, is displayed by
statistical procedures.
</para>
<para>Specify each variable followed by its label as a quoted string.
Variable-label pairs may be separated by an optional slash &#8216;<literal>/</literal>&#8217;.
</para>
<para>If a listed variable already has a label, the new one replaces it.
Specifying an empty string as the label, e.g.&#8216;<literal>''</literal>&#8217;, removes a
label.
</para>
</sect1>
<sect1 label="11.8" id="PRINT-FORMATS">
<title>PRINT FORMATS</title>
<indexterm role="vr"><primary>PRINT FORMATS</primary></indexterm>

<literallayout>PRINT FORMATS <replaceable>var_list</replaceable> (<replaceable>fmt_spec</replaceable>) [<replaceable>var_list</replaceable> (<replaceable>fmt_spec</replaceable>)]&#8230;.
</literallayout>
<para><literal>PRINT FORMATS</literal> sets the print formats for the specified
variables to the specified format specification.
</para>
<para>Its syntax is identical to that of <literal>FORMATS</literal> (see <link linkend="FORMATS">FORMATS</link>),
but <literal>PRINT FORMATS</literal> sets only print formats, not write formats.
</para>
</sect1>
<sect1 label="11.9" id="WRITE-FORMATS">
<title>WRITE FORMATS</title>
<indexterm role="vr"><primary>WRITE FORMATS</primary></indexterm>

<literallayout>WRITE FORMATS <replaceable>var_list</replaceable> (<replaceable>fmt_spec</replaceable>) [<replaceable>var_list</replaceable> (<replaceable>fmt_spec</replaceable>)]&#8230;.
</literallayout>
<para><literal>WRITE FORMATS</literal> sets the write formats for the specified variables
to the specified format specification.  Its syntax is identical to
that of <literal>FORMATS</literal> (see <link linkend="FORMATS">FORMATS</link>), but <literal>WRITE FORMATS</literal> sets only
write formats, not print formats.
</para>
</sect1>
<sect1 label="11.10" id="FORMATS">
<title>FORMATS</title>
<indexterm role="vr"><primary>FORMATS</primary></indexterm>

<literallayout>FORMATS <replaceable>var_list</replaceable> (<replaceable>fmt_spec</replaceable>) [<replaceable>var_list</replaceable> (<replaceable>fmt_spec</replaceable>)]&#8230;.
</literallayout>
<para><literal>FORMATS</literal> set both print and write formats for the specified
variables to the specified format specification.
See <link linkend="Input-and-Output-Formats">Input and Output Formats</link>.
</para>
<para>Specify a list of variables followed by a format specification in
parentheses.  The print and write formats of the specified variables
will be changed.  All of the variables listed together must have
the same type and, for string variables, the same width.
</para>
<para>Additional lists of variables and formats may be included following
the first one.
</para>
<para><literal>FORMATS</literal> takes effect immediately.  It is not affected by
conditional and looping structures such as <literal>DO IF</literal> or <literal>LOOP</literal>.
</para>
</sect1>
<sect1 label="11.11" id="VALUE-LABELS">
<title>VALUE LABELS</title>
<indexterm role="vr"><primary>VALUE LABELS</primary></indexterm>

<para>The values of a variable can be associated with an arbitrary text string.
In this way, a short value can stand for a longer, more descriptive label.
</para>
<para>Both numeric and string variables can be given labels.  For string
variables, the values are case-sensitive, so that, for example, a
capitalized value and its lowercase variant would have to be labeled
separately if both are present in the data.
</para>
<literallayout>VALUE LABELS
        /<replaceable>var_list</replaceable> <replaceable>value</replaceable> &#8217;<replaceable>label</replaceable>&#8217; [<replaceable>value</replaceable> &#8217;<replaceable>label</replaceable>&#8217;]&#8230;
</literallayout>
<para><literal>VALUE LABELS</literal> allows values of variables to be associated with labels.
</para>
<para>To set up value labels for one or more variables, specify the
variable names after a slash (&#8216;<literal>/</literal>&#8217;), followed by a list of values
and their associated labels, separated by spaces.
</para>
<para>Value labels in output are normally broken into lines automatically.
Put &#8216;<literal>\n</literal>&#8217; in a label string to force a line break at that point.
The label may still be broken into lines at additional points.
</para>
<para>Before <literal>VALUE LABELS</literal> is executed, any existing value labels
are cleared from the variables specified.  Use <literal>ADD VALUE LABELS</literal>
(see <link linkend="ADD-VALUE-LABELS">ADD VALUE LABELS</link>) to add value labels without clearing those
already present.
</para>
</sect1>
<sect1 label="11.12" id="ADD-VALUE-LABELS">
<title>ADD VALUE LABELS</title>
<indexterm role="vr"><primary>ADD VALUE LABELS</primary></indexterm>

<para><literal>ADD VALUE LABELS</literal> has the same syntax and purpose as <literal>VALUE
LABELS</literal> (see <link linkend="VALUE-LABELS">VALUE LABELS</link>), but it does not clear value
labels from the variables before adding the ones specified.
</para>
<literallayout>ADD VALUE LABELS
        /<replaceable>var_list</replaceable> <replaceable>value</replaceable> &#8217;<replaceable>label</replaceable>&#8217; [<replaceable>value</replaceable> &#8217;<replaceable>label</replaceable>&#8217;]&#8230;
</literallayout>

</sect1>
<sect1 label="11.13" id="MISSING-VALUES">
<title>MISSING VALUES</title>
<indexterm role="vr"><primary>MISSING VALUES</primary></indexterm>

<para>In many situations the data available for analysis is incomplete and a placeholder
must be used in place of a value to indicate that the value is unknown.  One way
that missing values are represented is through the $SYSMIS variable
(see <link linkend="System-Variables">System Variables</link>).  Another, more flexible way is through
<firstterm>user-missing values</firstterm> which are determined on a per variable basis.
</para>
<para>The <literal>MISSING VALUES</literal> command sets user-missing values for variables.
</para>
<literallayout>MISSING VALUES <replaceable>var_list</replaceable> (<replaceable>missing_values</replaceable>).

where <replaceable>missing_values</replaceable> takes one of the following forms:
        <replaceable>num1</replaceable>
        <replaceable>num1</replaceable>, <replaceable>num2</replaceable>
        <replaceable>num1</replaceable>, <replaceable>num2</replaceable>, <replaceable>num3</replaceable>
        <replaceable>num1</replaceable> THRU <replaceable>num2</replaceable>
        <replaceable>num1</replaceable> THRU <replaceable>num2</replaceable>, <replaceable>num3</replaceable>
        <replaceable>string1</replaceable>
        <replaceable>string1</replaceable>, <replaceable>string2</replaceable>
        <replaceable>string1</replaceable>, <replaceable>string2</replaceable>, <replaceable>string3</replaceable>
As part of a range, <literal>LO</literal> or <literal>LOWEST</literal> may take the place of <replaceable>num1</replaceable>;
<literal>HI</literal> or <literal>HIGHEST</literal> may take the place of <replaceable>num2</replaceable>.
</literallayout>
<para><literal>MISSING VALUES</literal> sets user-missing values for numeric and string
variables.  Long string variables may have missing values, but
characters after the first 8 bytes of the missing value must be
spaces.
</para>
<para>Specify a list of variables, followed by a list of their user-missing
values in parentheses.  Up to three discrete values may be given, or,
for numeric variables only, a range of values optionally accompanied by
a single discrete value.  Ranges may be open-ended on one end, indicated
through the use of the
keyword <literal>LO</literal> or <literal>LOWEST</literal> or <literal>HI</literal> or <literal>HIGHEST</literal>.
</para>
<para>The <literal>MISSING VALUES</literal> command takes effect immediately.  It is not
affected by conditional and looping constructs such as <literal>DO IF</literal> or
<literal>LOOP</literal>.
</para>
</sect1>
<sect1 label="11.14" id="VARIABLE-ATTRIBUTE">
<title>VARIABLE ATTRIBUTE</title>
<indexterm role="vr"><primary>VARIABLE ATTRIBUTE</primary></indexterm>

<para><literal>VARIABLE ATTRIBUTE</literal> adds, modifies, or removes user-defined
attributes associated with variables in the active dataset.  Custom
variable attributes are not interpreted by PSPP, but they are saved as
part of system files and may be used by other software that reads
them.
</para>
<literallayout>VARIABLE ATTRIBUTE
         VARIABLES=<replaceable>var_list</replaceable>
         ATTRIBUTE=<replaceable>name</replaceable>(&#8217;<replaceable>value</replaceable>&#8217;) [<replaceable>name</replaceable>(&#8217;<replaceable>value</replaceable>&#8217;)]&#8230;
         ATTRIBUTE=<replaceable>name</replaceable><emphasis role="bold">[</emphasis><replaceable>index</replaceable><emphasis role="bold">]</emphasis>(&#8217;<replaceable>value</replaceable>&#8217;) [<replaceable>name</replaceable><emphasis role="bold">[</emphasis><replaceable>index</replaceable><emphasis role="bold">]</emphasis>(&#8217;<replaceable>value</replaceable>&#8217;)]&#8230;
         DELETE=<replaceable>name</replaceable> [<replaceable>name</replaceable>]&#8230;
         DELETE=<replaceable>name</replaceable><emphasis role="bold">[</emphasis><replaceable>index</replaceable><emphasis role="bold">]</emphasis> [<replaceable>name</replaceable><emphasis role="bold">[</emphasis><replaceable>index</replaceable><emphasis role="bold">]</emphasis>]&#8230;
</literallayout>
<para>The required <literal>VARIABLES</literal> subcommand must come first.  Specify the
variables to which the following <literal>ATTRIBUTE</literal> or <literal>DELETE</literal> subcommand
should apply.
</para>
<para>Use the <literal>ATTRIBUTE</literal> subcommand to add or modify custom variable
attributes.  Specify the name of the attribute as an identifier
(see <link linkend="Tokens">Tokens</link>), followed by the desired value, in parentheses, as a
quoted string.  The specified attributes are then added or modified in
the variables specified on <literal>VARIABLES</literal>.  Attribute names that begin with
<literal>$</literal> are reserved for PSPP&#8217;s internal use, and attribute names
that begin with <literal>@</literal> or <literal>$@</literal> are not displayed by most PSPP
commands that display other attributes.  Other attribute names are not
treated specially.
</para>
<para>Attributes may also be organized into arrays.  To assign to an array
element, add an integer array index enclosed in square brackets
(<literal>[</literal> and <literal>]</literal>) between the attribute name and value.  Array
indexes start at 1, not 0.  An attribute array that has a single
element (number 1) is not distinguished from a non-array attribute.
</para>
<para>Use the <literal>DELETE</literal> subcommand to delete an attribute from the variable
specified on <literal>VARIABLES</literal>.  Specify an attribute name by itself to delete
an entire attribute, including all array elements for attribute
arrays.  Specify an attribute name followed by an array index in
square brackets to delete a single element of an attribute array.  In
the latter case, all the array elements numbered higher than the
deleted element are shifted down, filling the vacated position.
</para>
<para>To associate custom attributes with the entire active dataset, instead of
with particular variables, use <literal>DATAFILE ATTRIBUTE</literal> (see <link linkend="DATAFILE-ATTRIBUTE">DATAFILE ATTRIBUTE</link>) instead.
</para>
<para><literal>VARIABLE ATTRIBUTE</literal> takes effect immediately.  It is not affected
by conditional and looping structures such as <literal>DO IF</literal> or
<literal>LOOP</literal>.
</para>
</sect1>
<sect1 label="11.15" id="VARIABLE-ALIGNMENT">
<title>VARIABLE ALIGNMENT</title>
<indexterm role="vr"><primary>VARIABLE ALIGNMENT</primary></indexterm>

<para><literal>VARIABLE ALIGNMENT</literal> sets the alignment of variables for display editing
purposes.   It  does not affect the display of variables in the PSPP output.
</para>
<literallayout>VARIABLE ALIGNMENT
        <replaceable>var_list</replaceable> ( LEFT | RIGHT | CENTER )
        [ /<replaceable>var_list</replaceable> ( LEFT | RIGHT | CENTER ) ]
        .
        .
        .
        [ /<replaceable>var_list</replaceable> ( LEFT | RIGHT | CENTER ) ]
</literallayout>
</sect1>
<sect1 label="11.16" id="VARIABLE-WIDTH">
<title>VARIABLE WIDTH</title>
<indexterm role="vr"><primary>VARIABLE WIDTH</primary></indexterm>
<literallayout>VARIABLE WIDTH
        <replaceable>var_list</replaceable> (width)
        [ /<replaceable>var_list</replaceable> (width) ]
        .
        .
        .
        [ /<replaceable>var_list</replaceable> (width) ]
</literallayout>
<para><literal>VARIABLE WIDTH</literal> sets the column width of variables for display editing
purposes.   It does not affect the display of variables in the PSPP output.
</para>

</sect1>
<sect1 label="11.17" id="VARIABLE-LEVEL">
<title>VARIABLE LEVEL</title>
<indexterm role="vr"><primary>VARIABLE LEVEL</primary></indexterm>
<literallayout><literal>VARIABLE LEVEL</literal> <emphasis>variables</emphasis> <literal>(</literal>{<literal>SCALE</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>NOMINAL</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>ORDINAL</literal>}<literal>)</literal>&#8230;
</literallayout>
<para><literal>VARIABLE LEVEL</literal> sets the measurement level of <replaceable>variables</replaceable> as
specified.  See <link linkend="Attributes">Attributes</link>, for the definitions of the available
measurement levels.
</para>
</sect1>
<sect1 label="11.18" id="VARIABLE-ROLE">
<title>VARIABLE ROLE</title>
<indexterm role="vr"><primary>VARIABLE ROLE</primary></indexterm>
<literallayout>VARIABLE ROLE
        /<replaceable>role</replaceable> <replaceable>var_list</replaceable>
        [/<replaceable>role</replaceable> <replaceable>var_list</replaceable>]&#8230;
</literallayout>
<para><literal>VARIABLE ROLE</literal> sets the intended role of a variable for use in
dialog boxes in graphical user interfaces.  Each <replaceable>role</replaceable> specifies
one of the following roles for the variables that follow it:
</para>
<variablelist><varlistentry><term><literal>INPUT</literal>
</term><listitem><para>An input variable, such as an independent variable.
</para>
</listitem></varlistentry><varlistentry><term><literal>TARGET</literal>
</term><listitem><para>An output variable, such as a dependent variable.
</para>
</listitem></varlistentry><varlistentry><term><literal>BOTH</literal>
</term><listitem><para>A variable used for input and output.
</para>
</listitem></varlistentry><varlistentry><term><literal>NONE</literal>
</term><listitem><para>No role assigned.  (This is a variable&#8217;s default role.)
</para>
</listitem></varlistentry><varlistentry><term><literal>PARTITION</literal>
</term><listitem><para>Used to break the data into groups for testing.
</para>
</listitem></varlistentry><varlistentry><term><literal>SPLIT</literal>
</term><listitem><para>No meaning except for certain third party software.  (This role&#8217;s
meaning is unrelated to <literal>SPLIT FILE</literal>.)
</para></listitem></varlistentry></variablelist>
<para>The PSPPIRE GUI does not yet use variable roles as intended.
</para>
</sect1>
<sect1 label="11.19" id="VECTOR">
<title>VECTOR</title>
<indexterm role="vr"><primary>VECTOR</primary></indexterm>

<literallayout>Two possible syntaxes:
        VECTOR <replaceable>vec_name</replaceable>=<replaceable>var_list</replaceable>.
        VECTOR <replaceable>vec_name_list</replaceable>(<replaceable>count</replaceable> [<replaceable>format</replaceable>]).
</literallayout>
<para><literal>VECTOR</literal> allows a group of variables to be accessed as if they
were consecutive members of an array with a vector(index) notation.
</para>
<para>To make a vector out of a set of existing variables, specify a name
for the vector followed by an equals sign (&#8216;<literal>=</literal>&#8217;) and the variables
to put in the vector.  The variables must be all numeric or all
string, and string variables must have the same width.
</para>
<para>To make a vector and create variables at the same time, specify one or
more vector names followed by a count in parentheses.  This will
create variables named <literal><replaceable>vec</replaceable>1</literal> through
<literal><replaceable>vec</replaceable><replaceable>count</replaceable></literal>.  By default, the new variables are
numeric with format F8.2, but an alternate format may be specified
inside the parentheses before or after the count and separated from it
by white space or a comma.  With a string format such as A8, the
variables will be string variables; with a numeric format, they will
be numeric.  Variable names including the suffixes may not exceed 64
characters in length, and none of the variables may exist prior to
<literal>VECTOR</literal>.
</para>
<para>Vectors created with <literal>VECTOR</literal> disappear after any procedure or
procedure-like command is executed.  The variables contained in the
vectors remain, unless they are scratch variables (see <link linkend="Scratch-Variables">Scratch
Variables</link>).
</para>
<para>Variables within a vector may be referenced in expressions using
<literal>vector(index)</literal> syntax.
</para>
</sect1>
<sect1 label="11.20" id="MRSETS">
<title>MRSETS</title>
<indexterm role="vr"><primary>MRSETS</primary></indexterm>

<para><literal>MRSETS</literal> creates, modifies, deletes, and displays multiple
response sets.  A multiple response set is a set of variables that
represent multiple responses to a survey question.
</para>
<para>Multiple responses are represented in one of the two following ways:
</para>
<itemizedlist><listitem><para>A <firstterm>multiple dichotomy set</firstterm> is analogous to a survey question with
a set of checkboxes.  Each variable in the set is treated in a Boolean
fashion: one value (the &quot;counted value&quot;) means that the box was
checked, and any other value means that it was not.
</para>
</listitem><listitem><para>A <firstterm>multiple category set</firstterm> represents a survey question where the
respondent is instructed to list up to <replaceable>n</replaceable> choices.  Each variable
represents one of the responses.
</para></listitem></itemizedlist>
<literallayout>MRSETS
    /MDGROUP NAME=<replaceable>name</replaceable> VARIABLES=<replaceable>var_list</replaceable> VALUE=<replaceable>value</replaceable>
     [CATEGORYLABELS={VARLABELS,COUNTEDVALUES}]
     [{LABEL=&#8217;<replaceable>label</replaceable>&#8217;,LABELSOURCE=VARLABEL}]

    /MCGROUP NAME=<replaceable>name</replaceable> VARIABLES=<replaceable>var_list</replaceable> [LABEL=&#8217;<replaceable>label</replaceable>&#8217;]

    /DELETE NAME={[<replaceable>names</replaceable>],ALL}

    /DISPLAY NAME={[<replaceable>names</replaceable>],ALL}
</literallayout>

<para>Any number of subcommands may be specified in any order.
</para>
<para>The <literal>MDGROUP</literal> subcommand creates a new multiple dichotomy set or
replaces an existing multiple response set.  The <literal>NAME</literal>,
<literal>VARIABLES</literal>, and
<literal>VALUE</literal> specifications are required.  The others are optional:
</para>
<itemizedlist><listitem><para><replaceable>NAME</replaceable> specifies the name used in syntax for the new multiple dichotomy
set.  The name must begin with &#8216;<literal>$</literal>&#8217;; it must otherwise follow the
rules for identifiers (see <link linkend="Tokens">Tokens</link>).
</para>
</listitem><listitem><para><literal>VARIABLES</literal> specifies the variables that belong to the set.  At least
two variables must be specified.  The variables must be all string or
all numeric.
</para>
</listitem><listitem><para><literal>VALUE</literal> specifies the counted value.  If the variables are numeric, the
value must be an integer.  If the variables are strings, then the
value must be a string that is no longer than the shortest of the
variables in the set (ignoring trailing spaces).
</para>
</listitem><listitem><para><literal>CATEGORYLABELS</literal> optionally specifies the source of the labels for each
category in the set:
</para>
<itemizedlist><listitem><para>&#8722; <literal>VARLABELS</literal>, the default, uses variable labels or, for variables without
variable labels, variable names.  PSPP warns if two variables have the
same variable label, since these categories cannot be distinguished in
output.
</para>
</listitem><listitem><para>&#8722; <literal>COUNTEDVALUES</literal> instead uses each variable&#8217;s value label for the counted
value.  PSPP warns if two variables have the same value label for the
counted value or if one of the variables lacks a value label, since
such categories cannot be distinguished in output.
</para></listitem></itemizedlist>
</listitem><listitem><para><literal>LABEL</literal> optionally specifies a label for the multiple response set.  If
neither <literal>LABEL</literal> nor <literal>LABELSOURCE=VARLABEL</literal> is specified, the set is
unlabeled.
</para>
</listitem><listitem><para><literal>LABELSOURCE=VARLABEL</literal> draws the multiple response set&#8217;s label from the
first variable label among the variables in the set; if none of the
variables has a label, the name of the first variable is used.
<literal>LABELSOURCE=VARLABEL</literal> must be used with <literal>CATEGORYLABELS=COUNTEDVALUES</literal>.
It is mutually exclusive with <literal>LABEL</literal>.
</para></listitem></itemizedlist>
<para>The <literal>MCGROUP</literal> subcommand creates a new multiple category set or
replaces an existing multiple response set.  The <literal>NAME</literal> and <literal>VARIABLES</literal>
specifications are required, and <literal>LABEL</literal> is optional.  Their meanings
are as described above in <literal>MDGROUP</literal>.  PSPP warns if two variables in the
set have different value labels for a single value, since each of the
variables in the set should have the same possible categories.
</para>
<para>The <literal>DELETE</literal> subcommand deletes multiple response groups.  A list of
groups may be named within a set of required square brackets, or ALL
may be used to delete all groups.
</para>
<para>The <literal>DISPLAY</literal> subcommand displays information about defined multiple
response sets.  Its syntax is the same as the <literal>DELETE</literal> subcommand.
</para>
<para>Multiple response sets are saved to and read from system files by,
<emphasis>e.g.</emphasis>, the <literal>SAVE</literal> and <literal>GET</literal> command.  Otherwise, multiple
response sets are currently used only by third party software.
</para>
</sect1>
<sect1 label="11.21" id="LEAVE">
<title>LEAVE</title>
<indexterm role="vr"><primary>LEAVE</primary></indexterm>

<para><literal>LEAVE</literal> prevents the specified variables from being
reinitialized whenever a new case is processed.
</para>
<literallayout>LEAVE <replaceable>var_list</replaceable>.
</literallayout>
<para>Normally, when a data file is processed, every variable in the active
dataset is initialized to the system-missing value or spaces at the
beginning of processing for each case.  When a variable has been
specified on <literal>LEAVE</literal>, this is not the case.  Instead, that variable is
initialized to 0 (not system-missing) or spaces for the first case.
After that, it retains its value between cases.
</para>
<para>This becomes useful for counters.  For instance, in the example below
the variable <literal>SUM</literal> maintains a running total of the values in the <literal>ITEM</literal>
variable.
</para>
<screen>DATA LIST /ITEM 1-3.
COMPUTE SUM=SUM+ITEM.
PRINT /ITEM SUM.
LEAVE SUM
BEGIN DATA.
123
404
555
999
END DATA.
</screen>
<para>Partial output from this example:
</para>
<screen>123   123.00
404   527.00
555  1082.00
999  2081.00
</screen>
<para>It is best to use <literal>LEAVE</literal> command immediately before invoking a
procedure command, because the left status of variables is reset by
certain transformations&#8212;for instance, <literal>COMPUTE</literal> and <literal>IF</literal>.
Left status is also reset by all procedure invocations.
</para>
<!-- PSPP - a program for statistical analysis. -->
<!-- Copyright (C) 2017, 2020 Free Software Foundation, Inc. -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.3 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<!-- A copy of the license is included in the section entitled "GNU -->
<!-- Free Documentation License". -->
<!-- -->
</sect1>
</chapter>
<chapter label="12" id="Data-Manipulation">
<title>Data transformations</title>
<indexterm role="cp"><primary>transformations</primary></indexterm>

<para>The PSPP procedures examined in this chapter manipulate data and
prepare the active dataset for later analyses.  They do not produce output,
as a rule.
</para>

<sect1 label="12.1" id="AGGREGATE">
<title>AGGREGATE</title>
<indexterm role="vr"><primary>AGGREGATE</primary></indexterm>

<literallayout>AGGREGATE
        [OUTFILE={*,&#8217;<replaceable>file_name</replaceable>&#8217;,<replaceable>file_handle</replaceable>} [MODE={REPLACE,ADDVARIABLES}]]
        [/MISSING=COLUMNWISE]
        [/PRESORTED]
        [/DOCUMENT]
        [/BREAK=<replaceable>var_list</replaceable>]
        /<replaceable>dest_var</replaceable>[&#8217;<replaceable>label</replaceable>&#8217;]&#8230;=<replaceable>agr_func</replaceable>(<replaceable>src_vars</replaceable>[, <replaceable>args</replaceable>]&#8230;)&#8230;
</literallayout>
<para><literal>AGGREGATE</literal> summarizes groups of cases into single cases.
It divides cases into groups that have the same values for one or more
variables called <firstterm>break variables</firstterm>.  Several functions are available
for summarizing case contents.
</para>
<para>The <literal>AGGREGATE</literal> syntax consists of subcommands to control its
behavior, all of which are optional, followed by one or more
destination variable assigments, each of which uses an aggregation
function to define how it is calculated.
</para>
<para>The <literal>OUTFILE</literal> subcommand, which must be first, names the
destination for <literal>AGGREGATE</literal> output.  It may name a system file by
file name or file handle (see <link linkend="File-Handles">File Handles</link>), a dataset by its name
(see <link linkend="Datasets">Datasets</link>), or &#8216;<literal>*</literal>&#8217; to replace the active dataset.
<literal>AGGREGATE</literal> writes its output to this file.
</para>
<para>With <literal>OUTFILE=*</literal> only, <literal>MODE</literal> may be specified immediately
afterward with the value <literal>ADDVARIABLES</literal> or <literal>REPLACE</literal>:
</para>
<itemizedlist><listitem><para>With <literal>REPLACE</literal>, the default, the active dataset is replaced by a new dataset
which contains just the break variables and the destination varibles.
The new file contains as many cases as there are
unique combinations of the break variables.
</para>
</listitem><listitem><para>With <literal>ADDVARIABLES</literal>, the destination variables are added to those in
the existing active dataset.
Cases that have the same combination of values in their break
variables receive identical values for the destination variables.
The number of cases in the active dataset remains unchanged.
The data must be
sorted on the break variables, that is, <literal>ADDVARIABLES</literal> implies <literal>PRESORTED</literal>
</para></listitem></itemizedlist>
<para>If <literal>OUTFILE</literal> is omitted, <literal>AGGREGATE</literal> acts as if
<literal>OUTFILE=* MODE=ADDVARIABLES</literal> were specified.
</para>
<para>By default, <literal>AGGREGATE</literal> first sorts the data on the break variables.
If the active dataset is already sorted
or grouped by the break variables, specify
<literal>PRESORTED</literal> to save time.
With <literal>MODE=ADDVARIABLES</literal>, the data must be pre-sorted.
</para>
<para>Specify <literal>DOCUMENT</literal> to copy the documents from the active dataset into the
aggregate file (see <link linkend="DOCUMENT">DOCUMENT</link>).  Otherwise, the aggregate file does
not contain any documents, even if the aggregate file replaces the
active dataset.
</para>
<para>Normally, <literal>AGGREGATE</literal> produces a non-missing value whenever there
is enough non-missing data for the aggregation function in use, that
is, just one non-missing value or, for the <literal>SD</literal> and <literal>SD.</literal>
aggregation functions, two non-missing values.  Specify
<literal>/MISSING=COLUMNWISE</literal> to make <literal>AGGREGATE</literal> output a missing
value when one or more of the input values are missing.
</para>
<para>The <literal>BREAK</literal> subcommand is optionally but usually present.  On
<literal>BREAK</literal>, list the variables used to divide the active dataset
into groups to be summarized.
</para>
<para><literal>AGGREGATE</literal> is particular about the order of subcommands.
<literal>OUTFILE</literal> must be first, followed by <literal>MISSING</literal>.
<literal>PRESORTED</literal> and <literal>DOCUMENT</literal> follow <literal>MISSING</literal>, in
either order, followed by <literal>BREAK</literal>, then followed by aggregation
variable specifications.
</para>
<para>At least one set of aggregation variables is required.  Each set
comprises a list of aggregation variables, an equals sign (&#8216;<literal>=</literal>&#8217;),
the name of an aggregation function (see the list below), and a list
of source variables in parentheses.  A few aggregation functions do
not accept source variables, and some aggregation functions expect
additional arguments after the source variable names.
</para>
<para><literal>AGGREGATE</literal> typically creates aggregation variables with no
variable label, value labels, or missing values.  Their default print
and write formats depend on the aggregation function used, with
details given in the table below.  A variable label for an aggregation
variable may be specified just after the variable&#8217;s name in the
aggregation variable list.
</para>
<para>Each set must have exactly as many source variables as aggregation
variables.  Each aggregation variable receives the results of applying
the specified aggregation function to the corresponding source
variable.
</para>
<para>The following aggregation functions may be applied only to numeric
variables:
</para>
<variablelist><varlistentry><term><literal>MEAN(<replaceable>var_name</replaceable>&#8230;)</literal>
</term><listitem><para>Arithmetic mean.  Limited to numeric values.  The default format is
F8.2.
</para>
</listitem></varlistentry><varlistentry><term><literal>MEDIAN(<replaceable>var_name</replaceable>&#8230;)</literal>
</term><listitem><para>The median value.  Limited to numeric values.  The default format is F8.2.
</para>
</listitem></varlistentry><varlistentry><term><literal>SD(<replaceable>var_name</replaceable>&#8230;)</literal>
</term><listitem><para>Standard deviation of the mean.  Limited to numeric values.  The
default format is F8.2.
</para>
</listitem></varlistentry><varlistentry><term><literal>SUM(<replaceable>var_name</replaceable>&#8230;)</literal>
</term><listitem><para>Sum.  Limited to numeric values.  The default format is F8.2.
</para></listitem></varlistentry></variablelist>
<para>These aggregation functions may be applied to numeric and string variables:
</para>
<variablelist><varlistentry><term><literal>CGT(<replaceable>var_name</replaceable>&#8230;, <replaceable>value</replaceable>)</literal>
</term><term><literal>CLT(<replaceable>var_name</replaceable>&#8230;, <replaceable>value</replaceable>)</literal>
</term><term><literal>CIN(<replaceable>var_name</replaceable>&#8230;, <replaceable>low</replaceable>, <replaceable>high</replaceable>)</literal>
</term><term><literal>COUT(<replaceable>var_name</replaceable>&#8230;, <replaceable>low</replaceable>, <replaceable>high</replaceable>)</literal>
</term><listitem><para>Total weight of cases greater than or less than <replaceable>value</replaceable> or inside
or outside the closed range [<replaceable>low</replaceable>,<replaceable>high</replaceable>], respectively.  The
default format is F5.3.
</para>
</listitem></varlistentry><varlistentry><term><literal>FGT(<replaceable>var_name</replaceable>&#8230;, <replaceable>value</replaceable>)</literal>
</term><term><literal>FLT(<replaceable>var_name</replaceable>&#8230;, <replaceable>value</replaceable>)</literal>
</term><term><literal>FIN(<replaceable>var_name</replaceable>&#8230;, <replaceable>low</replaceable>, <replaceable>high</replaceable>)</literal>
</term><term><literal>FOUT(<replaceable>var_name</replaceable>&#8230;, <replaceable>low</replaceable>, <replaceable>high</replaceable>)</literal>
</term><listitem><para>Fraction of values greater than or less than <replaceable>value</replaceable> or inside or
outside the closed range [<replaceable>low</replaceable>,<replaceable>high</replaceable>], respectively.  The
default format is F5.3.
</para>
</listitem></varlistentry><varlistentry><term><literal>FIRST(<replaceable>var_name</replaceable>&#8230;)</literal>
</term><term><literal>LAST(<replaceable>var_name</replaceable>&#8230;)</literal>
</term><listitem><para>First or last non-missing value, respectively, in break group.  The
aggregation variable
receives the complete dictionary information from the source variable.
The sort performed by <literal>AGGREGATE</literal> (and by <literal>SORT CASES</literal>) is stable.
This means that
the first (or last) case with particular values for the break variables before
sorting is also the first (or last) case in that break group after sorting.
</para>
</listitem></varlistentry><varlistentry><term><literal>MIN(<replaceable>var_name</replaceable>&#8230;)</literal>
</term><term><literal>MAX(<replaceable>var_name</replaceable>&#8230;)</literal>
</term><listitem><para>Minimum or maximum value, respectively.  The aggregation variable
receives the complete dictionary information from the source variable.
</para>
</listitem></varlistentry><varlistentry><term><literal>N(<replaceable>var_name</replaceable>&#8230;)</literal>
</term><term><literal>NMISS(<replaceable>var_name</replaceable>&#8230;)</literal>
</term><listitem><para>Total weight of non-missing or missing values, respectively.  The
default format is F7.0 if weighting is not enabled, F8.2 if it is
(see <link linkend="WEIGHT">WEIGHT</link>).
</para>
</listitem></varlistentry><varlistentry><term><literal>NU(<replaceable>var_name</replaceable>&#8230;)</literal>
</term><term><literal>NUMISS(<replaceable>var_name</replaceable>&#8230;)</literal>
</term><listitem><para>Count of non-missing or missing values, respectively, ignoring case
weights.  The default format is F7.0.
</para>
</listitem></varlistentry><varlistentry><term><literal>PGT(<replaceable>var_name</replaceable>&#8230;, <replaceable>value</replaceable>)</literal>
</term><term><literal>PLT(<replaceable>var_name</replaceable>&#8230;, <replaceable>value</replaceable>)</literal>
</term><term><literal>PIN(<replaceable>var_name</replaceable>&#8230;, <replaceable>low</replaceable>, <replaceable>high</replaceable>)</literal>
</term><term><literal>POUT(<replaceable>var_name</replaceable>&#8230;, <replaceable>low</replaceable>, <replaceable>high</replaceable>)</literal>
</term><listitem><para>Percentage between 0 and 100 of values greater than or less than
<replaceable>VALUE</replaceable> or inside or outside the closed range
[<replaceable>low</replaceable>,<replaceable>high</replaceable>], respectively.  The default format is F5.1.
</para></listitem></varlistentry></variablelist>
<para>These aggregation functions do not accept source variables:
</para>
<variablelist><varlistentry><term><literal>N</literal>
</term><listitem><para>Total weight of cases aggregated to form this group.  The default
format is F7.0 if weighting is not enabled, F8.2 if it is
(see <link linkend="WEIGHT">WEIGHT</link>).
</para>
</listitem></varlistentry><varlistentry><term><literal>NU</literal>
</term><listitem><para>Count of cases aggregated to form this group, ignoring case weights.
The default format is F7.0.
</para></listitem></varlistentry></variablelist>
<para>Aggregation functions compare string values in terms of internal
character codes.
On most modern computers, this is  <acronym>ASCII</acronym> or a superset thereof.
</para>
<para>The aggregation functions listed above exclude all user-missing values
from calculations.  To include user-missing values, insert a period
(&#8216;<literal>.</literal>&#8217;) at the end of the function name.  (<emphasis>e.g.</emphasis> &#8216;<literal>SUM.</literal>&#8217;).
(Be aware that specifying such a function as the last token on a line
causes the period to be interpreted as the end of the command.)
</para>
<para><literal>AGGREGATE</literal> both ignores and cancels the current <literal>SPLIT FILE</literal>
settings (see <link linkend="SPLIT-FILE">SPLIT FILE</link>).
</para>
<sect2 label="12.1.1">
<title>Aggregate Example</title>

<para>The <filename>personnel.sav</filename> dataset provides the occupations and salaries of
many individuals.  For many purposes however such detailed information is
not interesting, but often the aggregated statistics of each occupation are
of interest.  In <link linkend="aggregate_003aex">aggregate:ex</link> the <literal>AGGREGATE</literal> command is used
to calculate the mean, the median and the standard deviation of each
occupation.
</para>
<anchor id="aggregate_003aex"/>
<sidebar><screen>GET FILE=&quot;personnel.sav&quot;.
AGGREGATE OUTFILE=* MODE=REPLACE
        /BREAK=occupation
        /occ_mean_salary=MEAN(salary)
        /occ_median_salary=MEDIAN(salary)
        /occ_std_dev_salary=SD(salary).
LIST.
</screen></sidebar>
<para>Since we chose the &#8216;<literal>MODE=REPLACE</literal>&#8217; option, in <link linkend="aggregate_003ares">aggregate:res</link> cases
for the individual persons are no longer present.  They have each been replaced
by a single case per aggregated value.
</para>
<anchor id="aggregate_003ares"/>
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                                Data List
+------------------+---------------+-----------------+------------------+
|    occupation    |occ_mean_salary|occ_median_salary|occ_std_dev_salary|
+------------------+---------------+-----------------+------------------+
|Artist            |       37836.18|         34712.50|           7631.48|
|Baker             |       45075.20|         45075.20|           4411.21|
|Barrister         |       39504.00|         39504.00|                 .|
|Carpenter         |       39349.11|         36190.04|           7453.40|
|Cleaner           |       41142.50|         39647.49|          14378.98|
|Cook              |       40357.79|         43194.00|          11064.51|
|Manager           |       46452.14|         45657.56|           6901.69|
|Mathematician     |       34531.06|         34763.06|           5267.68|
|Painter           |       45063.55|         45063.55|          15159.67|
|Payload Specialist|       34355.72|         34355.72|                 .|
|Plumber           |       40413.91|         40410.00|           4726.05|
|Scientist         |       36687.07|         36803.83|          10873.54|
|Scrientist        |       42530.65|         42530.65|                 .|
|Tailor            |       34586.79|         34586.79|           3728.98|
+------------------+---------------+-----------------+------------------+
</screen>
<para>Note that some values for the standard deviation are blank.
This is because there is only one case with the respective
occupation.
</para>
</sect2>
</sect1>
<sect1 label="12.2" id="AUTORECODE">
<title>AUTORECODE</title>
<indexterm role="vr"><primary>AUTORECODE</primary></indexterm>

<literallayout>AUTORECODE VARIABLES=<replaceable>src_vars</replaceable> INTO <replaceable>dest_vars</replaceable>
        [ /DESCENDING ]
        [ /PRINT ]
        [ /GROUP ]
        [ /BLANK = {VALID, MISSING} ]
</literallayout>
<para>The <literal>AUTORECODE</literal> procedure considers the <replaceable>n</replaceable> values that a variable
takes on and maps them onto values 1&#8230;<replaceable>n</replaceable> on a new numeric
variable.
</para>
<para>Subcommand <literal>VARIABLES</literal> is the only required subcommand and must come
first.  Specify <literal>VARIABLES</literal>, an equals sign (&#8216;<literal>=</literal>&#8217;), a list of source
variables, <literal>INTO</literal>, and a list of target variables.  There must the same
number of source and target variables.  The target variables must not
already exist.
</para>
<para><literal>AUTORECODE</literal> ordinarily assigns each increasing non-missing value
of a source variable (for a string, this is based on character code
comparisons) to consecutive values of its target variable.  For
example, the smallest non-missing value of the source variable is
recoded to value 1, the next smallest to 2, and so on.  If the source
variable has user-missing values, they are recoded to
consecutive values just above the non-missing values.  For example, if
a source variables has seven distinct non-missing values, then the
smallest missing value would be recoded to 8, the next smallest to 9,
and so on.
</para>
<para>Use <literal>DESCENDING</literal> to reverse the sort order for non-missing
values, so that the largest non-missing value is recoded to 1, the
second-largest to 2, and so on.  Even with <literal>DESCENDING</literal>,
user-missing values are still recoded in ascending order just above
the non-missing values.
</para>
<para>The system-missing value is always recoded into the system-missing
variable in target variables.
</para>
<para>If a source value has a value label, then that value label is retained
for the new value in the target variable.  Otherwise, the source value
itself becomes each new value&#8217;s label.
</para>
<para>Variable labels are copied from the source to target variables.
</para>
<para><literal>PRINT</literal> is currently ignored.
</para>
<para>The <literal>GROUP</literal> subcommand is relevant only if more than one variable is to be
recoded.   It causes a single mapping between source and target values to
be used, instead of one map per variable.  With <literal>GROUP</literal>,
user-missing values are taken from the first source variable that has
any user-missing values.
</para>
<para>If <literal>/BLANK=MISSING</literal> is given, then string variables which contain only
whitespace are recoded as SYSMIS.  If <literal>/BLANK=VALID</literal> is specified then they
are allocated a value like any other.  <literal>/BLANK</literal> is not relevant
to numeric values. <literal>/BLANK=VALID</literal> is the default.
</para>
<para><literal>AUTORECODE</literal> is a procedure.  It causes the data to be read.  It
ignores <literal>TEMPORARY</literal> (see <link linkend="TEMPORARY">TEMPORARY</link>), so that &#8220;temporary&#8221;
transformations become permanent.
</para>

<sect2 label="12.2.1">
<title>Autorecode Example</title>

<para>In the file <filename>personnel.sav</filename>, the variable <emphasis role="bold">occupation</emphasis> is a string
variable.   Except for data of a purely commentary nature, string variables
are generally a bad idea.  One reason is that data entry errors are easily
overlooked.  This has happened in <filename>personnel.sav</filename>; one entry which should
read &#8220;Scientist&#8221; has been mistyped as &#8220;Scrientist&#8221;.  In <link linkend="autorecode_003aex">autorecode:ex</link>
first, this error is corrected by the <literal>DO IF</literal> clause,
<footnote><para>One must use care when correcting such data input errors rather than
msimply marking them as missing.  For example, if an occupation has been entered
&#8220;Barister&#8221;, did the person mean &#8220;Barrister&#8221; or did she mean &#8220;Barista&#8221;?</para></footnote>
then we use <literal>AUTORECODE</literal> to
create a new numeric variable which takes recoded values of <emphasis role="bold">occupation</emphasis>.
Finally, we remove the old variable and rename the new variable to
the name of the old variable.
</para>
<anchor id="autorecode_003aex"/>
<sidebar><screen>get file='personnel.sav'.

* Correct a typing error in the original file.
do if occupation = &quot;Scrientist&quot;.
 compute occupation = &quot;Scientist&quot;.
end if.

autorecode
	variables = occupation into occ
	/blank = missing.

* Delete the old variable.
delete variables occupation.

* Rename the new variable to the old variable's name.
rename variables (occ = occupation).

* Inspect the new variable.
display dictionary /variables=occupation.

</screen></sidebar>

<anchor id="autorecode_003ascr"/>
<sidebar></sidebar>
<para>Notice in <link linkend="autorecode_003ares">autorecode:res</link>, how  the new variable has been automatically
allocated value labels which correspond to the strings of the old variable.
This means that in future analyses the descriptive strings are reported instead
of the numeric values.
</para>
<anchor id="autorecode_003ares"/>
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                                   Variables
+----------+--------+--------------+-----+-----+---------+----------+---------+
|          |        |  Measurement |     |     |         |   Print  |  Write  |
|Name      |Position|     Level    | Role|Width|Alignment|  Format  |  Format |
+----------+--------+--------------+-----+-----+---------+----------+---------+
|occupation|       6|Unknown       |Input|    8|Right    |F2.0      |F2.0     |
+----------+--------+--------------+-----+-----+---------+----------+---------+

            Value Labels
+---------------+------------------+
|Variable Value |       Label      |
+---------------+------------------+
|occupation 1   |Artist            |
|           2   |Baker             |
|           3   |Barrister         |
|           4   |Carpenter         |
|           5   |Cleaner           |
|           6   |Cook              |
|           7   |Manager           |
|           8   |Mathematician     |
|           9   |Painter           |
|           10  |Payload Specialist|
|           11  |Plumber           |
|           12  |Scientist         |
|           13  |Tailor            |
+---------------+------------------+
</screen>

</sect2>
</sect1>
<sect1 label="12.3" id="COMPUTE">
<title>COMPUTE</title>
<indexterm role="vr"><primary>COMPUTE</primary></indexterm>

<literallayout>COMPUTE <replaceable>variable</replaceable> = <replaceable>expression</replaceable>.
</literallayout><para>or
</para><literallayout>COMPUTE vector(<replaceable>index</replaceable>) = <replaceable>expression</replaceable>.
</literallayout>
<para><literal>COMPUTE</literal> assigns the value of an expression to a target
variable.  For each case, the expression is evaluated and its value
assigned to the target variable.  Numeric and string
variables may be assigned.  When a string expression&#8217;s width differs
from the target variable&#8217;s width, the string result of the expression
is truncated or padded with spaces on the right as necessary.  The
expression and variable types must match.
</para>
<para>For numeric variables only, the target variable need not already
exist.  Numeric variables created by <literal>COMPUTE</literal> are assigned an
<literal>F8.2</literal> output format.  String variables must be declared before
they can be used as targets for <literal>COMPUTE</literal>.
</para>
<para>The target variable may be specified as an element of a vector
(see <link linkend="VECTOR">VECTOR</link>).  In this case, an expression <replaceable>index</replaceable> must be
specified in parentheses following the vector name.  The expression <replaceable>index</replaceable>
must evaluate to a numeric value that, after rounding down
to the nearest integer, is a valid index for the named vector.
</para>
<para>Using <literal>COMPUTE</literal> to assign to a variable specified on <literal>LEAVE</literal>
(see <link linkend="LEAVE">LEAVE</link>) resets the variable&#8217;s left state.  Therefore,
<literal>LEAVE</literal> should be specified following <literal>COMPUTE</literal>, not before.
</para>
<para><literal>COMPUTE</literal> is a transformation.  It does not cause the active dataset to be
read.
</para>
<para>When <literal>COMPUTE</literal> is specified following <literal>TEMPORARY</literal>
(see <link linkend="TEMPORARY">TEMPORARY</link>), the <literal>LAG</literal> function may not be used
(see <link linkend="LAG">LAG</link>).
</para>
<sect2 label="12.3.1">
<title>Compute Examples</title>

<para>The dataset <filename>physiology.sav</filename> contains the height and weight of persons.
For some purposes, neither height nor weight alone is of interest.
Epidemiologists are often more interested in the <firstterm>body mass index</firstterm> which
can sometimes be used as a predictor for clinical conditions.
The body mass index is defined as the weight of the person in kilograms divided
by the square of the person&#8217;s height in metres.
<footnote><para>Since BMI is a quantity with a ratio scale and has units, the term &#8220;index&#8221;
is a misnomer, but that is what it is called.</para></footnote>
</para>
<anchor id="bmi_003aex"/>
<sidebar><screen>get file='physiology.sav'.

* height is in mm so we must divide by 1000 to get metres.
compute bmi = weight / (height/1000)**2.
variable label bmi &quot;Body Mass Index&quot;.

descriptives /weight height bmi.
</screen></sidebar>
<para><link linkend="bmi_003aex">bmi:ex</link> shows how you can use <literal>COMPUTE</literal> to generate a new variable called
<emphasis role="bold">bmi</emphasis> and have every case&#8217;s value calculated from the existing values of
<emphasis role="bold">weight</emphasis> and <emphasis role="bold">height</emphasis>.
It also shows how you can add a label to this new variable (see <link linkend="VARIABLE-LABELS">VARIABLE LABELS</link>),
so that a more descriptive label appears in subsequent analyses, and this can be seen
in the ouput from the <literal>DESCRIPTIVES</literal> command in <link linkend="bmi_003ares">bmi:res</link>.
</para>
<anchor id="bmi_003ascr"/>
<sidebar></sidebar>
<para>The expression which follows the &#8216;<literal>=</literal>&#8217; sign can be as complicated as necessary.
See <link linkend="Expressions">Expressions</link> for a precise description of the language accepted.
Normally it is easiest to enter the code directly, however there is a dialog box
available if desired.  This is illustrated in <link linkend="bmi_003ascr">bmi:scr</link>.
One advantage is that it offers a list of mathematical
functions which can be selected and pasted into the expression.
</para>
<anchor id="bmi_003ares"/>
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                  Descriptive Statistics
+---------------------+--+-------+-------+-------+-------+
|                     | N|  Mean |Std Dev|Minimum|Maximum|
+---------------------+--+-------+-------+-------+-------+
|Weight in kilograms  |40|  72.12|  26.70|  -55.6|   92.1|
|Height in millimeters|40|1677.12| 262.87|    179|   1903|
|Body Mass Index      |40|  67.46| 274.08| -21.62|1756.82|
|Valid N (listwise)   |40|       |       |       |       |
|Missing N (listwise) | 0|       |       |       |       |
+---------------------+--+-------+-------+-------+-------+
</screen>


</sect2>
</sect1>
<sect1 label="12.4" id="COUNT">
<title>COUNT</title>
<indexterm role="vr"><primary>COUNT</primary></indexterm>

<literallayout>COUNT <replaceable>var_name</replaceable> = <replaceable>var</replaceable>&#8230; (<replaceable>value</replaceable>&#8230;)
    [/<replaceable>var_name</replaceable> = <replaceable>var</replaceable>&#8230; (<replaceable>value</replaceable>&#8230;)]&#8230;

Each <replaceable>value</replaceable> takes one of the following forms:
        <replaceable>number</replaceable>
        <replaceable>string</replaceable>
        <replaceable>num1</replaceable> THRU <replaceable>num2</replaceable>
        MISSING
        SYSMIS
where <replaceable>num1</replaceable> is a numeric expression or the words <literal>LO</literal>  or <literal>LOWEST</literal>
      and <replaceable>num2</replaceable> is a numeric expression  or <literal>HI</literal> or <literal>HIGHEST</literal>.
</literallayout>
<para><literal>COUNT</literal> creates or replaces a numeric <firstterm>target</firstterm> variable that
counts the occurrence of a <firstterm>criterion</firstterm> value or set of values over
one or more <firstterm>test</firstterm> variables for each case.
</para>
<para>The target variable values are always nonnegative integers.  They are
never missing.  The target variable is assigned an F8.2 output format.
See <link linkend="Input-and-Output-Formats">Input and Output Formats</link>.  Any variables, including
string variables, may be test variables.
</para>
<para>User-missing values of test variables are treated just like any other
values.  They are <emphasis role="bold">not</emphasis> treated as system-missing values.
User-missing values that are criterion values or inside ranges of
criterion values are counted as any other values.  However (for numeric
variables), keyword <literal>MISSING</literal> may be used to refer to all system-
and user-missing values.
</para>
<para><literal>COUNT</literal> target variables are assigned values in the order
specified.  In the command <literal>COUNT <replaceable>A</replaceable>=<replaceable>A</replaceable> <replaceable>B</replaceable>(1) /<replaceable>B</replaceable>=<replaceable>A</replaceable> <replaceable>B</replaceable>(2).</literal>, the
following actions occur:
</para>
<itemizedlist><listitem><para>&#8722; The number of occurrences of 1 between <replaceable>A</replaceable> and <replaceable>B</replaceable> is counted.
</para>
</listitem><listitem><para>&#8722; <replaceable>A</replaceable> is assigned this value.
</para>
</listitem><listitem><para>&#8722; The number of occurrences of 1 between <replaceable>B</replaceable> and the <emphasis role="bold">new</emphasis>
value of <replaceable>A</replaceable> is counted.
</para>
</listitem><listitem><para>&#8722; <replaceable>B</replaceable> is assigned this value.
</para></listitem></itemizedlist>
<para>Despite this ordering, all <literal>COUNT</literal> criterion variables must exist
before the procedure is executed&#8212;they may not be created as target
variables earlier in the command!  Break such a command into two
separate commands.
</para>
<sect2 label="12.4.1">
<title>Count Examples</title>

<para>In the survey results in dataset <filename>hotel.sav</filename> a manager wishes
to know how many respondents answered with low valued answers to questions
<emphasis role="bold">v1</emphasis>, <emphasis role="bold">v2</emphasis> and <emphasis role="bold">v3</emphasis>.  This can be found using the code
in <link linkend="count_003aex">count:ex</link>.  Specifically, this code creates a new variable, and
populates it with the number of values in <emphasis role="bold">v1</emphasis>&#8211;<emphasis role="bold">v2</emphasis> which
are 2 or lower.
</para>
<anchor id="count_003aex"/>
<sidebar><screen>get file=&quot;hotel.sav&quot;.

count low_counts = v1 v2 v3 (low thru 2).

list /variables v1 v2 v3 low_counts.</screen></sidebar>
<para>In <link linkend="count_003aex">count:ex</link> the <literal>COUNT</literal> transformation creates a new variable, <emphasis role="bold">low_counts</emphasis> and
its values are shown using the <literal>LIST</literal> command.
</para>
<para>If using the graphic user interface, a two step process must be used to set
up the <literal>COUNT</literal> transformation.  The first dialog box (<link linkend="count_003ascr">count:scr</link>) provides for the
variables to be chosen.
Then, one must click on the button marked &#8220;Define Values...&#8221; to reveal
the dialog box for selecting the values to count.
</para>
<anchor id="count_003ascr"/>
<sidebar></sidebar>
<para>In this dialog box, you must select the values you wish to count
&#8212; in this case all values up to and including 2 &#8212; as shown in <link linkend="count_002ddefine_003ascr">count-define:scr</link>
and click &#8220;Add&#8221;.  As many ranges or may be added as you desire.
When all desired ranges have been added click &#8220;Continue&#8221;.
</para>
<anchor id="count_002ddefine_003ascr"/>
<sidebar></sidebar>
<para>In <link linkend="count_003ares">count:res</link> we can see the values of <emphasis role="bold">low_counts</emphasis> after the <literal>COUNT</literal>
transformation has completed.  The first value is 1, because there is only one
variable amoung <emphasis role="bold">v1</emphasis>, <emphasis role="bold">v2</emphasis> and <emphasis role="bold">3</emphasis> which has a value of 2 or less.
The second value is 2, because both <emphasis role="bold">v1</emphasis> and <emphasis role="bold">v2</emphasis> are 2 or less.
</para>
<anchor id="count_003ares"/>
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>      Data List
+--+--+--+----------+
|v1|v2|v3|low_counts|
+--+--+--+----------+
| 4| 2| 3|      1.00|
| 1| 1| 4|      2.00|
| 4| 2| 2|      2.00|
| 3| 1| 3|      1.00|
| 5| 3| 1|      1.00|
| 2| 2| 5|      2.00|
| 3| 2| 4|      1.00|
| 1| 4| 5|      1.00|
| 3| 2| 3|      1.00|
| 2| 5| 4|      1.00|
| 4| 2| 2|      2.00|
| 2| 1| 4|      2.00|
| 1| 2| 5|      2.00|
| 2| 3| 3|      1.00|
| 4| 1| 1|      2.00|
| 1| 1| 5|      2.00|
| 1| 5| 5|      1.00|
+--+--+--+----------+
</screen>

</sect2>
</sect1>
<sect1 label="12.5" id="FLIP">
<title>FLIP</title>
<indexterm role="vr"><primary>FLIP</primary></indexterm>

<literallayout>FLIP /VARIABLES=<replaceable>var_list</replaceable> /NEWNAMES=<replaceable>var_name</replaceable>.
</literallayout>
<para><literal>FLIP</literal> transposes rows and columns in the active dataset.  It
causes cases to be swapped with variables, and vice versa.
</para>
<para>All variables in the transposed active dataset are numeric.  String
variables take on the system-missing value in the transposed file.
</para>
<para><literal>N</literal> subcommands are required.  If specified, the <literal>VARIABLES</literal> subcommand
selects variables to be transformed into cases, and variables not
specified are discarded.  If the <literal>VARIABLES</literal> subcommand is omitted, all
variables are selected for transposition.
</para>
<para>The variables specified by <literal>NEWNAMES</literal>, which must be a
string variable, is
used to give names to the variables created by <literal>FLIP</literal>.  Only the
first 8 characters of the variable are used.  If
<literal>NEWNAMES</literal> is not
specified then the default is a variable named <emphasis role="bold">CASE_LBL</emphasis>, if it exists.
If it does not then the variables created by <literal>FLIP</literal> are named VAR000
through VAR999, then VAR1000, VAR1001, and so on.
</para>
<para>When a <literal>NEWNAMES</literal> variable is available, the names must be canonicalized
before becoming variable names.  Invalid characters are replaced by
letter &#8216;<literal>V</literal>&#8217; in the first position, or by &#8216;<literal>_</literal>&#8217; in subsequent
positions.  If the name thus generated is not unique, then numeric
extensions are added, starting with 1, until a unique name is found or
there are no remaining possibilities.  If the latter occurs then the
<literal>FLIP</literal> operation aborts.
</para>
<para>The resultant dictionary contains a <emphasis role="bold">CASE_LBL</emphasis> variable, a string
variable of width 8, which stores the names of the variables in the
dictionary before the transposition.  Variables names longer than 8
characters are truncated.  If <literal>FLIP</literal> is called again on
this dataset, the <emphasis role="bold">CASE_LBL</emphasis> variable can be passed to the <literal>NEWNAMES</literal>
subcommand to recreate the original variable names.
</para>
<para><literal>FLIP</literal> honors <literal>N OF CASES</literal> (see <link linkend="N-OF-CASES">N OF CASES</link>).  It ignores
<literal>TEMPORARY</literal> (see <link linkend="TEMPORARY">TEMPORARY</link>), so that &#8220;temporary&#8221;
transformations become permanent.
</para>
<sect2 label="12.5.1">
<title>Flip Examples</title>


<para>In <link linkend="flip_003aex">flip:ex</link>, data has been entered using <literal>DATA LIST</literal> (see <link linkend="DATA-LIST">DATA LIST</link>)
such that the first variable in the dataset is a string variable containing
a description of the other data for the case.
Clearly this is not a convenient arrangement for performing statistical analyses,
so it would have been better to think a little more carefully about how the data
should have been arranged.
However often the data is provided by some third party source, and you have
no control over the form.
Fortunately, we can use <literal>FLIP</literal> to exchange the variables
and cases in the active dataset.
</para>
<anchor id="flip_003aex"/>
<sidebar><screen>data list notable list /heading (a16) v1 v2 v3 v4 v5 v6
begin data.
date-of-birth 1970 1989 2001 1966 1976 1982
sex 1 0 0 1 0 1
score 10 10 9 3 8 9
end data.

echo 'Before FLIP:'.
display variables.
list.

flip /variables = all /newnames = heading.

echo 'After FLIP:'.
display variables.
list.</screen></sidebar>
<para>As you can see in <link linkend="flip_003ares">flip:res</link> before the <literal>FLIP</literal> command has run there
are seven variables (six containing data and one for the heading) and three cases.
Afterwards there are four variables (one per case, plus the <emphasis role="bold">CASE_LBL</emphasis> variable)
and six cases.
You can delete the <emphasis role="bold">CASE_LBL</emphasis> variable (see <link linkend="DELETE-VARIABLES">DELETE VARIABLES</link>) if you don&#8217;t need it.
</para>
<anchor id="flip_003ares"/>
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>Before FLIP:

                  Variables
+-------+--------+------------+------------+
|Name   |Position|Print Format|Write Format|
+-------+--------+------------+------------+
|heading|       1|A16         |A16         |
|v1     |       2|F8.2        |F8.2        |
|v2     |       3|F8.2        |F8.2        |
|v3     |       4|F8.2        |F8.2        |
|v4     |       5|F8.2        |F8.2        |
|v5     |       6|F8.2        |F8.2        |
|v6     |       7|F8.2        |F8.2        |
+-------+--------+------------+------------+

                           Data List
+-------------+-------+-------+-------+-------+-------+-------+
|   heading   |   v1  |   v2  |   v3  |   v4  |   v5  |   v6  |
+-------------+-------+-------+-------+-------+-------+-------+
|date-of-birth|1970.00|1989.00|2001.00|1966.00|1976.00|1982.00|
|sex          |   1.00|    .00|    .00|   1.00|    .00|   1.00|
|score        |  10.00|  10.00|   9.00|   3.00|   8.00|   9.00|
+-------------+-------+-------+-------+-------+-------+-------+

After FLIP:

                     Variables
+-------------+--------+------------+------------+
|Name         |Position|Print Format|Write Format|
+-------------+--------+------------+------------+
|CASE_LBL     |       1|A8          |A8          |
|date_of_birth|       2|F8.2        |F8.2        |
|sex          |       3|F8.2        |F8.2        |
|score        |       4|F8.2        |F8.2        |
+-------------+--------+------------+------------+

             Data List
+--------+-------------+----+-----+
|CASE_LBL|date_of_birth| sex|score|
+--------+-------------+----+-----+
|v1      |      1970.00|1.00|10.00|
|v2      |      1989.00| .00|10.00|
|v3      |      2001.00| .00| 9.00|
|v4      |      1966.00|1.00| 3.00|
|v5      |      1976.00| .00| 8.00|
|v6      |      1982.00|1.00| 9.00|
+--------+-------------+----+-----+
</screen>

</sect2>
</sect1>
<sect1 label="12.6" id="IF">
<title>IF</title>
<indexterm role="vr"><primary>IF</primary></indexterm>

<literallayout>IF <replaceable>condition</replaceable> <replaceable>variable</replaceable>=<replaceable>expression</replaceable>.
</literallayout><para>or
</para><literallayout>IF <replaceable>condition</replaceable> vector(<replaceable>index</replaceable>)=<replaceable>expression</replaceable>.
</literallayout>
<para>The <literal>IF</literal> transformation conditionally assigns the value of a target
expression to a target variable, based on the truth of a test
expression.
</para>
<para>Specify a boolean-valued expression (see <link linkend="Expressions">Expressions</link>) to be tested
following the <literal>IF</literal> keyword.  This expression is evaluated for each case.
If the value is true, then the value of the expression is computed and
assigned to the specified variable.  If the value is false or missing,
nothing is done.  Numeric and string variables may be
assigned.  When a string expression&#8217;s width differs from the target
variable&#8217;s width, the string result of the expression is truncated or
padded with spaces on the right as necessary.  The expression and
variable types must match.
</para>
<para>The target variable may be specified as an element of a vector
(see <link linkend="VECTOR">VECTOR</link>).  In this case, a vector index expression must be
specified in parentheses following the vector name.  The index
expression must evaluate to a numeric value that, after rounding down
to the nearest integer, is a valid index for the named vector.
</para>
<para>Using <literal>IF</literal> to assign to a variable specified on <literal>LEAVE</literal>
(see <link linkend="LEAVE">LEAVE</link>) resets the variable&#8217;s left state.  Therefore,
<literal>LEAVE</literal> should be specified following <literal>IF</literal>, not before.
</para>
<para>When <literal>IF</literal> is specified following <literal>TEMPORARY</literal>
(see <link linkend="TEMPORARY">TEMPORARY</link>), the <literal>LAG</literal> function may not be used
(see <link linkend="LAG">LAG</link>).
</para>
</sect1>
<sect1 label="12.7" id="RECODE">
<title>RECODE</title>
<indexterm role="vr"><primary>RECODE</primary></indexterm>

<para>The <literal>RECODE</literal> command is used to transform existing values into other,
user specified values.
The general form is:
</para>
<literallayout>RECODE <replaceable>src_vars</replaceable>
        (<replaceable>src_value</replaceable> <replaceable>src_value</replaceable> &#8230; = <replaceable>dest_value</replaceable>)
        (<replaceable>src_value</replaceable> <replaceable>src_value</replaceable> &#8230; = <replaceable>dest_value</replaceable>)
        (<replaceable>src_value</replaceable> <replaceable>src_value</replaceable> &#8230; = <replaceable>dest_value</replaceable>) &#8230;
         [INTO <replaceable>dest_vars</replaceable>].
</literallayout>
<para>Following the <literal>RECODE</literal> keyword itself comes <replaceable>src_vars</replaceable> which is a list
of variables whose values are to be transformed.
These variables may be string variables or they may be numeric.
However the list must be homogeneous; you may not mix string variables and
numeric variables in the same recoding.
</para>
<para>After the list of source variables, there should be one or more <firstterm>mappings</firstterm>.
Each mapping is enclosed in parentheses, and contains the source values and
a destination value separated by a single &#8216;<literal>=</literal>&#8217;.
The source values are used to specify the values in the dataset which
need to change, and the destination value specifies the new value
to which they should be changed.
Each <replaceable>src_value</replaceable> may take one of the following forms:
</para><variablelist><varlistentry><term><replaceable>number</replaceable>
</term><listitem><para>If the source variables are numeric then <replaceable>src_value</replaceable> may be a literal
number.
</para></listitem></varlistentry><varlistentry><term><replaceable>string</replaceable>
</term><listitem><para>If the source variables are string variables then <replaceable>src_value</replaceable> may be a
literal string (like all strings, enclosed in single or double quotes).
</para></listitem></varlistentry><varlistentry><term><replaceable>num1</replaceable> THRU <replaceable>num2</replaceable>
</term><listitem><para>This form is valid only when the source variables are numeric.
It specifies all values in the range between <replaceable>num1</replaceable> and <replaceable>num2</replaceable>,
including both endpoints of the range.  By convention, <replaceable>num1</replaceable>
should be less than <replaceable>num2</replaceable>.
Open-ended ranges may be specified using &#8216;<literal>LO</literal>&#8217; or &#8216;<literal>LOWEST</literal>&#8217;
for <replaceable>num1</replaceable>
or &#8216;<literal>HI</literal>&#8217; or &#8216;<literal>HIGHEST</literal>&#8217; for <replaceable>num2</replaceable>.
</para></listitem></varlistentry><varlistentry><term>&#8216;<literal>MISSING</literal>&#8217;
</term><listitem><para>The literal keyword &#8216;<literal>MISSING</literal>&#8217; matches both system missing and user
missing values.
It is valid for both numeric and string variables.
</para></listitem></varlistentry><varlistentry><term>&#8216;<literal>SYSMIS</literal>&#8217;
</term><listitem><para>The literal keyword &#8216;<literal>SYSMIS</literal>&#8217; matches system missing
values.
It is valid for both numeric variables only.
</para></listitem></varlistentry><varlistentry><term>&#8216;<literal>ELSE</literal>&#8217;
</term><listitem><para>The &#8216;<literal>ELSE</literal>&#8217; keyword may be used to match any values which are
not matched by any other <replaceable>src_value</replaceable> appearing in the command.
If this keyword appears, it should be used in the last mapping of the
command.
</para></listitem></varlistentry></variablelist>
<para>After the source variables comes an &#8216;<literal>=</literal>&#8217; and then the <replaceable>dest_value</replaceable>.
The <replaceable>dest_value</replaceable> may take any of the following forms:
</para><variablelist><varlistentry><term><replaceable>number</replaceable>
</term><listitem><para>A literal numeric value to which the source values should be changed.
This implies the destination variable must be numeric.
</para></listitem></varlistentry><varlistentry><term><replaceable>string</replaceable>
</term><listitem><para>A literal string value (enclosed in quotation marks) to which the source
values should be changed.
This implies the destination variable must be a string variable.
</para></listitem></varlistentry><varlistentry><term>&#8216;<literal>SYSMIS</literal>&#8217;
</term><listitem><para>The keyword &#8216;<literal>SYSMIS</literal>&#8217; changes the value to the system missing value.
This implies the destination variable must be numeric.
</para></listitem></varlistentry><varlistentry><term>&#8216;<literal>COPY</literal>&#8217;
</term><listitem><para>The special keyword &#8216;<literal>COPY</literal>&#8217; means that the source value should not be
modified, but
copied directly to the destination value.
This is meaningful only if &#8216;<literal>INTO <replaceable>dest_vars</replaceable></literal>&#8217; is specified.
</para></listitem></varlistentry></variablelist>
<para>Mappings are considered from left to right.
Therefore, if a value is matched by a <replaceable>src_value</replaceable> from more than
one mapping, the first (leftmost) mapping which matches is considered.
Any subsequent matches are ignored.
</para>
<para>The clause &#8216;<literal>INTO <replaceable>dest_vars</replaceable></literal>&#8217; is optional.
The behaviour of the command is slightly different depending on whether it
appears or not.
</para>
<para>If &#8216;<literal>INTO <replaceable>dest_vars</replaceable></literal>&#8217; does not appear, then values are recoded
&#8220;in place&#8221;.
This means that the recoded values are written back to the
source variables from whence the original values came.
In this case, the <replaceable>dest_value</replaceable> for every mapping must imply a value which
has the same type as the <replaceable>src_value</replaceable>.
For example, if the source value is a string value, it is not permissible for
<replaceable>dest_value</replaceable> to be &#8216;<literal>SYSMIS</literal>&#8217; or another forms which implies a numeric
result.
It is also not permissible for <replaceable>dest_value</replaceable> to be  longer than the width
of the source variable.
</para>
<para>The following example two numeric variables <replaceable>x</replaceable> and <replaceable>y</replaceable> are recoded
in place.
Zero is recoded to 99, the values 1 to 10 inclusive are unchanged,
values 1000 and higher are recoded to the system-missing value and all other
values are changed to 999:
</para><screen>recode <replaceable>x</replaceable> <replaceable>y</replaceable>
        (0 = 99)
        (1 THRU 10 = COPY)
        (1000 THRU HIGHEST = SYSMIS)
        (ELSE = 999).
</screen>
<para>If &#8216;<literal>INTO <replaceable>dest_vars</replaceable></literal>&#8217; is given, then recoded values are written
into the variables specified in <replaceable>dest_vars</replaceable>, which must therefore
 contain a list of valid variable names.
The number of variables in <replaceable>dest_vars</replaceable> must be the same as the number
of variables in <replaceable>src_vars</replaceable>
and the respective order of the variables in <replaceable>dest_vars</replaceable> corresponds to
the order of <replaceable>src_vars</replaceable>.
That is to say, the recoded value whose
original value came from the <replaceable>n</replaceable>th variable in <replaceable>src_vars</replaceable> is
placed into the <replaceable>n</replaceable>th variable in <replaceable>dest_vars</replaceable>.
The source variables are unchanged.
If any mapping implies a string as its destination value, then the respective
destination variable must already exist, or
have been declared using <literal>STRING</literal> or another transformation.
Numeric variables however are automatically created if they don&#8217;t already
exist.
The following example deals with two source variables, <replaceable>a</replaceable> and <replaceable>b</replaceable>
which contain string values.  Hence there are two destination variables
<replaceable>v1</replaceable> and <replaceable>v2</replaceable>.
Any cases where <replaceable>a</replaceable> or <replaceable>b</replaceable> contain the values &#8216;<literal>apple</literal>&#8217;,
&#8216;<literal>pear</literal>&#8217; or &#8216;<literal>pomegranate</literal>&#8217; result in <replaceable>v1</replaceable> or <replaceable>v2</replaceable> being
filled with the string &#8216;<literal>fruit</literal>&#8217; whilst cases with
&#8216;<literal>tomato</literal>&#8217;, &#8216;<literal>lettuce</literal>&#8217; or &#8216;<literal>carrot</literal>&#8217; result in &#8216;<literal>vegetable</literal>&#8217;.
Any other values produce the result &#8216;<literal>unknown</literal>&#8217;:
</para><screen>string <replaceable>v1</replaceable> (a20).
string <replaceable>v2</replaceable> (a20).

recode <replaceable>a</replaceable> <replaceable>b</replaceable>
        (&quot;apple&quot; &quot;pear&quot; &quot;pomegranate&quot; = &quot;fruit&quot;)
        (&quot;tomato&quot; &quot;lettuce&quot; &quot;carrot&quot; = &quot;vegetable&quot;)
        (ELSE = &quot;unknown&quot;)
        into <replaceable>v1</replaceable> <replaceable>v2</replaceable>.
</screen>
<para>There is one very special mapping, not mentioned above.
If the source variable is a string variable
then a mapping may be specified as &#8216;<literal>(CONVERT)</literal>&#8217;.
This mapping, if it appears must be the last mapping given and
the &#8216;<literal>INTO <replaceable>dest_vars</replaceable></literal>&#8217; clause must also be given and
must not refer to a string variable.
&#8216;<literal>CONVERT</literal>&#8217; causes a number specified as a string to
be converted to a numeric value.
For example it converts the string &#8216;<literal>&quot;3&quot;</literal>&#8217; into the numeric
value 3 (note that it does not convert &#8216;<literal>three</literal>&#8217; into 3).
If the string cannot be parsed as a number, then the system-missing value
is assigned instead.
In the following example, cases where the value of <replaceable>x</replaceable> (a string variable)
is the empty string, are recoded to 999 and all others are converted to the
numeric equivalent of the input value.  The results are placed into the
numeric variable <replaceable>y</replaceable>:
</para><screen>recode <replaceable>x</replaceable>
       (&quot;&quot; = 999)
        (convert)
        into <replaceable>y</replaceable>.
</screen>
<para>It is possible to specify multiple recodings on a single command.
Introduce additional recodings with a slash (&#8216;<literal>/</literal>&#8217;) to
separate them from the previous recodings:
</para><screen>recode
        <replaceable>a</replaceable>  (2 = 22) (else = 99)
        /<replaceable>b</replaceable> (1 = 3) into <replaceable>z</replaceable>
        .
</screen><para>Here we have two recodings. The first affects the source variable
<replaceable>a</replaceable> and recodes in-place the value 2 into 22 and all other values to 99.
The second recoding copies the values of <replaceable>b</replaceable> into the variable <replaceable>z</replaceable>,
changing any instances of 1 into 3.
</para>
</sect1>
<sect1 label="12.8" id="SORT-CASES">
<title>SORT CASES</title>
<indexterm role="vr"><primary>SORT CASES</primary></indexterm>

<literallayout>SORT CASES BY <replaceable>var_list</replaceable>[({D|A}] [ <replaceable>var_list</replaceable>[({D|A}] ] ...
</literallayout>
<para><literal>SORT CASES</literal> sorts the active dataset by the values of one or more
variables.
</para>
<para>Specify <literal>BY</literal> and a list of variables to sort by.  By default, variables
are sorted in ascending order.  To override sort order, specify <literal>(D)</literal> or
<literal>(DOWN)</literal> after a list of variables to get descending order, or <literal>(A)</literal>
or <literal>(UP)</literal>
for ascending order.  These apply to all the listed variables
up until the preceding <literal>(A)</literal>, <literal>(D)</literal>, <literal>(UP)</literal> or <literal>(DOWN)</literal>.
</para>
<para>The sort algorithms used by <literal>SORT CASES</literal> are stable.  This means
records which have equal values of the sort variables have the
same relative order before and after sorting.  Thus,
re-sorting an already sorted file does not affect the ordering of
cases.
</para>
<para><literal>SORT CASES</literal> is a procedure.  It causes the data to be read.
</para>
<para><literal>SORT CASES</literal> attempts to sort the entire active dataset in main memory.
If workspace is exhausted, it falls back to a merge sort algorithm which
creates numerous temporary files.
</para>
<para><literal>SORT CASES</literal> may not be specified following <literal>TEMPORARY</literal>.
</para>
<sect2 label="12.8.1">
<title>Sorting Example</title>

<para>In <link linkend="sort_002dcases_003aex">sort-cases:ex</link> the data from the file <filename>physiology.sav</filename> is sorted
by two variables, <emphasis>viz</emphasis> <emphasis role="bold">sex</emphasis> in descending order and <emphasis role="bold">temperature</emphasis> in
ascending order.
</para>
<anchor id="sort_002dcases_003aex"/>
<sidebar><screen>get file='physiology.sav'.
sort cases by sex (D) temperature(A).
list.
</screen></sidebar>
<para>In <link linkend="sort_002dcases_003ares">sort-cases:res</link> you can see that all the cases with a <emphasis role="bold">sex</emphasis> of
&#8216;<literal>1</literal>&#8217; (female) appear before those with a sex of &#8216;<literal>0</literal>&#8217; (male).
This is because they have been sorted in descending order.
Within each sex, the data is sorted on the <emphasis role="bold">temperature</emphasis> variable,
this time in ascending order.
</para>
<anchor id="sort_002dcases_003ares"/>
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>           Data List
+---+------+------+-----------+
|sex|height|weight|temperature|
+---+------+------+-----------+
|  1|  1606|  56.1|      34.56|
|  1|   179|  56.3|      35.15|
|  1|  1609|  55.4|      35.46|
|  1|  1606|  56.0|      36.06|
|  1|  1607|  56.3|      36.26|
|  1|  1604|  56.0|      36.57|
|  1|  1604|  56.6|      36.81|
|  1|  1606|  56.3|      36.88|
|  1|  1604|  57.8|      37.32|
|  1|  1598|  55.6|      37.37|
|  1|  1607|  55.9|      37.84|
|  1|  1605|  54.5|      37.86|
|  1|  1603|  56.1|      38.80|
|  1|  1604|  58.1|      38.85|
|  1|  1605|  57.7|      38.98|
|  1|  1709|  55.6|      39.45|
|  1|  1604| -55.6|      39.72|
|  1|  1601|  55.9|      39.90|
|  0|  1799|  90.3|      32.59|
|  0|  1799|  89.0|      33.61|
|  0|  1799|  90.6|      34.04|
|  0|  1801|  90.5|      34.42|
|  0|  1802|  87.7|      35.03|
|  0|  1793|  90.1|      35.11|
|  0|  1801|  92.1|      35.98|
|  0|  1800|  89.5|      36.10|
|  0|  1645|  92.1|      36.68|
|  0|  1698|  90.2|      36.94|
|  0|  1800|  89.6|      37.02|
|  0|  1800|  88.9|      37.03|
|  0|  1801|  88.9|      37.12|
|  0|  1799|  90.4|      37.33|
|  0|  1903|  91.5|      37.52|
|  0|  1799|  90.9|      37.53|
|  0|  1800|  91.0|      37.60|
|  0|  1799|  90.4|      37.68|
|  0|  1801|  91.7|      38.98|
|  0|  1801|  90.9|      39.03|
|  0|  1799|  89.3|      39.77|
|  0|  1884|  88.6|      39.97|
+---+------+------+-----------+
</screen>
<para>Note that <literal>SORT CASES</literal>, like all other transformations, affects only the active file.
It does not have any effect upon the <filename>physiology.sav</filename> file itself. For that, you
would have to rewrite the file using the <literal>SAVE</literal> command (see <link linkend="SAVE">SAVE</link>).
</para>
<para>When using the graphic user interface, it is often simpler to perform a sort
directly from the data view.
To do this, switch to the data view.  Select the column corresponding to the
variable by which you want to sort and click button 1 and then click button 3.
A popup menu will appear like that shown in <link linkend="sort_002dsimple_003ascr">sort-simple:scr</link>.  Select
either &#8220;Sort Ascending&#8221; or &#8220;Sort Descending&#8221; from this menu.
</para>
<anchor id="sort_002dsimple_003ascr"/>
<sidebar></sidebar>
<para>However, sometimes you will want to sort on two or more variables, and that is
not possible using this method.  In this case, you must either use some code or
the &#8220;Sort Cases&#8221; dialog from the Data menu.  <link linkend="sort_003ascr">sort:scr</link> shows the dialog
box set up to perform a sort on both <emphasis role="bold">sex</emphasis> and <emphasis role="bold">height</emphasis>.
Note that the order in which you enter the variables is important.  In this case,
the data will be first sorted on <emphasis role="bold">sex</emphasis>, and then all cases for which <emphasis role="bold">sex</emphasis>
is the same will then be sorted by <emphasis role="bold">height</emphasis>.
</para>
<anchor id="sort_003ascr"/>
<sidebar></sidebar><!-- PSPP - a program for statistical analysis. -->
<!-- Copyright (C) 2017, 2020 Free Software Foundation, Inc. -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.3 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<!-- A copy of the license is included in the section entitled "GNU -->
<!-- Free Documentation License". -->
<!-- -->
</sect2>
</sect1>
</chapter>
<chapter label="13" id="Data-Selection">
<title>Selecting data for analysis</title>

<para>This chapter documents PSPP commands that temporarily or permanently
select data records from the active dataset for analysis.
</para>

<sect1 label="13.1" id="FILTER">
<title>FILTER</title>
<indexterm role="vr"><primary>FILTER</primary></indexterm>

<literallayout>FILTER BY <replaceable>var_name</replaceable>.
FILTER OFF.
</literallayout>
<para><literal>FILTER</literal> allows a boolean-valued variable to be used to select
cases from the data stream for processing.
</para>
<para>To set up filtering, specify <literal>BY</literal> and a variable name.  Keyword
BY is optional but recommended.  Cases which have a zero or system- or
user-missing value are excluded from analysis, but not deleted from the
data stream.  Cases with other values are analyzed.
To filter based on a different condition, use
transformations such as <literal>COMPUTE</literal> or <literal>RECODE</literal> to compute a
filter variable of the required form, then specify that variable on
<literal>FILTER</literal>.
</para>
<para><literal>FILTER OFF</literal> turns off case filtering.
</para>
<para>Filtering takes place immediately before cases pass to a procedure for
analysis.  Only one filter variable may be active at a time.  Normally,
case filtering continues until it is explicitly turned off with <literal>FILTER
OFF</literal>.  However, if <literal>FILTER</literal> is placed after <literal>TEMPORARY</literal>, it filters only
the next procedure or procedure-like command.
</para>
</sect1>
<sect1 label="13.2" id="N-OF-CASES">
<title>N OF CASES</title>
<indexterm role="vr"><primary>N OF CASES</primary></indexterm>

<literallayout>N [OF CASES] <replaceable>num_of_cases</replaceable> [ESTIMATED].
</literallayout>
<para><literal>N OF CASES</literal> limits the number of cases processed by any
procedures that follow it in the command stream.  <literal>N OF CASES
100</literal>, for example, tells PSPP to disregard all cases after the first
100.
</para>
<para>When <literal>N OF CASES</literal> is specified after <literal>TEMPORARY</literal>, it affects
only the next procedure (see <link linkend="TEMPORARY">TEMPORARY</link>).  Otherwise, cases beyond
the limit specified are not processed by any later procedure.
</para>
<para>If the limit specified on <literal>N OF CASES</literal> is greater than the number
of cases in the active dataset, it has no effect.
</para>
<para>When <literal>N OF CASES</literal> is used along with <literal>SAMPLE</literal> or <literal>SELECT
IF</literal>, the case limit is applied to the cases obtained after sampling or
case selection, regardless of how <literal>N OF CASES</literal> is placed relative
to <literal>SAMPLE</literal> or <literal>SELECT IF</literal> in the command file.  Thus, the
commands <literal>N OF CASES 100</literal> and <literal>SAMPLE .5</literal> both randomly
sample approximately half of the active dataset&#8217;s cases, then select the
first 100 of those sampled, regardless of their order in the command
file.
</para>
<para><literal>N OF CASES</literal> with the <literal>ESTIMATED</literal> keyword gives an estimated
number of cases before <literal>DATA LIST</literal> or another command to read in
data.  <literal>ESTIMATED</literal> never limits the number of cases processed by
procedures.  PSPP currently does not make use of case count estimates.
</para>
</sect1>
<sect1 label="13.3" id="SAMPLE">
<title>SAMPLE</title>
<indexterm role="vr"><primary>SAMPLE</primary></indexterm>

<literallayout>SAMPLE <replaceable>num1</replaceable> [FROM <replaceable>num2</replaceable>].
</literallayout>
<para><literal>SAMPLE</literal> randomly samples a proportion of the cases in the active
file.  Unless it follows <literal>TEMPORARY</literal>, it operates as a
transformation, permanently removing cases from the active dataset.
</para>
<para>The proportion to sample can be expressed as a single number between 0
and 1.  If <replaceable>k</replaceable> is the number specified, and <replaceable>N</replaceable> is the number
of currently-selected cases in the active dataset, then after
<literal>SAMPLE <replaceable>k</replaceable>.</literal>, approximately <replaceable>k</replaceable>*<replaceable>N</replaceable> cases are
selected.
</para>
<para>The proportion to sample can also be specified in the style <literal>SAMPLE
<replaceable>m</replaceable> FROM <replaceable>N</replaceable></literal>.  With this style, cases are selected as follows:
</para>
<orderedlist numeration="arabic"><listitem><para>If <replaceable>N</replaceable> is equal to the number of currently-selected cases in the
active dataset, exactly <replaceable>m</replaceable> cases are selected.
</para>
</listitem><listitem><para>If <replaceable>N</replaceable> is greater than the number of currently-selected cases in the
active dataset, an equivalent proportion of cases are selected.
</para>
</listitem><listitem><para>If <replaceable>N</replaceable> is less than the number of currently-selected cases in the
active, exactly <replaceable>m</replaceable> cases are selected <emphasis>from the first
<replaceable>N</replaceable> cases in the active dataset.</emphasis>
</para></listitem></orderedlist>
<para><literal>SAMPLE</literal> and <literal>SELECT IF</literal> are performed in
the order specified by the syntax file.
</para>
<para><literal>SAMPLE</literal> is always performed before <literal>N OF CASES</literal>, regardless
of ordering in the syntax file (see <link linkend="N-OF-CASES">N OF CASES</link>).
</para>
<para>The same values for <literal>SAMPLE</literal> may result in different samples.  To
obtain the same sample, use the <literal>SET</literal> command to set the random
number seed to the same value before each <literal>SAMPLE</literal>.  Different
samples may still result when the file is processed on systems with
differing endianness or floating-point formats.  By default, the
random number seed is based on the system time.
</para>
</sect1>
<sect1 label="13.4" id="SELECT-IF">
<title>SELECT IF</title>
<indexterm role="vr"><primary>SELECT IF</primary></indexterm>

<literallayout>SELECT IF <replaceable>expression</replaceable>.
</literallayout>
<para><literal>SELECT IF</literal> selects cases for analysis based on the value of
<replaceable>expression</replaceable>.  Cases not selected are permanently eliminated
from the active dataset, unless <literal>TEMPORARY</literal> is in effect
(see <link linkend="TEMPORARY">TEMPORARY</link>).
</para>
<para>Specify a boolean expression (see <link linkend="Expressions">Expressions</link>).  If the value of the
expression is true for a particular case, the case is analyzed.  If
the expression has a false or missing value, then the case is
deleted from the data stream.
</para>
<para>Place <literal>SELECT IF</literal> as early in the command file as
possible.  Cases that are deleted early can be processed more
efficiently in time and space.
Once cases have been deleted from the active dataset using <literal>SELECT IF</literal> they
cannot be re-instated.
If you want to be able to re-instate cases, then use <literal>FILTER</literal> (see <link linkend="FILTER">FILTER</link>)
instead.
</para>
<para>When <literal>SELECT IF</literal> is specified following <literal>TEMPORARY</literal>
(see <link linkend="TEMPORARY">TEMPORARY</link>), the <literal>LAG</literal> function may not be used
(see <link linkend="LAG">LAG</link>).
</para>
<sect2 label="13.4.1">
<title>Example Select-If</title>

<para>A shop steward is interested in the salaries of younger personnel in a firm.
The file <filename>personnel.sav</filename> provides the salaries of all the workers and their
dates of birth.  The syntax in <link linkend="select_002dif_003aex">select-if:ex</link> shows how <literal>SELECT IF</literal> can
be used to limit analysis only to those persons born after December 31, 1999.
</para>
<anchor id="select_002dif_003aex"/>
<sidebar><screen>get file = 'personnel.sav'.

echo 'Salaries of all personnel'.
descriptives salary.

echo 'Salaries of personnel born after December 31 1999'.
select if dob &gt; date.dmy (31,12,1999).
descriptives salary.
</screen></sidebar>
<para>From <link linkend="select_002dif_003ares">select-if:res</link> one can see that there are 56 persons listed in the dataset,
and 17 of them were born after December 31, 1999.
</para>
<anchor id="select_002dif_003ares"/>
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>Salaries of all personnel

                    Descriptive Statistics
+------------------------+--+--------+-------+-------+-------+
|                        | N|  Mean  |Std Dev|Minimum|Maximum|
+------------------------+--+--------+-------+-------+-------+
|Annual salary before tax|56|40028.97|8721.17|$23,451|$57,044|
|Valid N (listwise)      |56|        |       |       |       |
|Missing N (listwise)    | 0|        |       |       |       |
+------------------------+--+--------+-------+-------+-------+

Salaries of personnel born after December 31 1999

                    Descriptive Statistics
+------------------------+--+--------+-------+-------+-------+
|                        | N|  Mean  |Std Dev|Minimum|Maximum|
+------------------------+--+--------+-------+-------+-------+
|Annual salary before tax|17|31828.59|4454.80|$23,451|$39,504|
|Valid N (listwise)      |17|        |       |       |       |
|Missing N (listwise)    | 0|        |       |       |       |
+------------------------+--+--------+-------+-------+-------+
</screen>
<para>Note that the <filename>personnel.sav</filename> file from which the data were read is unaffected.
The transformation affects only the active file.
</para>
</sect2>
</sect1>
<sect1 label="13.5" id="SPLIT-FILE">
<title>SPLIT FILE</title>
<indexterm role="vr"><primary>SPLIT FILE</primary></indexterm>

<literallayout>SPLIT FILE [{LAYERED, SEPARATE}] BY <replaceable>var_list</replaceable>.
SPLIT FILE OFF.
</literallayout>
<para><literal>SPLIT FILE</literal> allows multiple sets of data present in one data
file to be analyzed separately using single statistical procedure
commands.
</para>
<para>Specify a list of variable names to analyze multiple sets of
data separately.  Groups of adjacent cases having the same values for these
variables are analyzed by statistical procedure commands as one group.
An independent analysis is carried out for each group of cases, and the
variable values for the group are printed along with the analysis.
</para>
<para>When a list of variable names is specified, one of the keywords
<literal>LAYERED</literal> or <literal>SEPARATE</literal> may also be specified.  With
<literal>LAYERED</literal>, which is the default, the separate analyses for each
group are presented together in a single table.  With
<literal>SEPARATE</literal>, each analysis is presented in a separate table.
Not all procedures honor the distinction.
</para>
<para>Groups are formed only by <emphasis>adjacent</emphasis> cases.  To create a split
using a variable where like values are not adjacent in the working file,
first sort the data by that variable (see <link linkend="SORT-CASES">SORT CASES</link>).
</para>
<para>Specify <literal>OFF</literal> to disable <literal>SPLIT FILE</literal> and resume analysis of the
entire active dataset as a single group of data.
</para>
<para>When <literal>SPLIT FILE</literal> is specified after <literal>TEMPORARY</literal>, it affects only
the next procedure (see <link linkend="TEMPORARY">TEMPORARY</link>).
</para>
<sect2 label="13.5.1">
<title>Example Split</title>

<para>The file <filename>horticulture.sav</filename> contains data describing the <emphasis role="bold">yield</emphasis>
of a number of horticultural specimens which have been subjected to
various <emphasis role="bold">treatment</emphasis>s.   If we wanted to investigate linear statistics
of the <emphasis role="bold">yeild</emphasis>, one way to do this is using the <literal>DESCRIPTIVES</literal> (see <link linkend="DESCRIPTIVES">DESCRIPTIVES</link>).
However, it is reasonable to expect the mean to be different depending
on the <emphasis role="bold">treatment</emphasis>.   So we might want to perform three separate
procedures &#8212; one for each treatment.
<footnote><para>There are other, possibly better, ways to achieve a similar result
using the <literal>MEANS</literal> or <literal>EXAMINE</literal> commands.</para></footnote>
<link linkend="split_003aex">split:ex</link> shows how this can be done automatically using
the <literal>SPLIT FILE</literal> command.
</para>
<anchor id="split_003aex"/>
<sidebar><screen>get file='horticulture.sav'.

* Ensure cases are sorted before splitting.
sort cases by treatment.

split file by treatment.

* Run descriptives on the yield variable
descriptives /variable = yield.
</screen></sidebar>
<para>In <link linkend="split_003ares">split:res</link> you can see that the table of descriptive statistics
appears 3 times &#8212; once for each value of <emphasis role="bold">treatment</emphasis>.
In this example &#8216;<literal>N</literal>&#8217;, the number of observations are identical in
all splits.  This is because that experiment was deliberately designed
that way.  However in general one can expect a different &#8216;<literal>N</literal>&#8217; for each
split.
</para>
<anchor id="split_003ares"/>
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>    Split Values
+---------+-------+
|Variable | Value |
+---------+-------+
|treatment|control|
+---------+-------+

                 Descriptive Statistics
+--------------------+--+-----+-------+-------+-------+
|                    | N| Mean|Std Dev|Minimum|Maximum|
+--------------------+--+-----+-------+-------+-------+
|yield               |30|51.23|   8.28|  37.86|  68.59|
|Valid N (listwise)  |30|     |       |       |       |
|Missing N (listwise)| 0|     |       |       |       |
+--------------------+--+-----+-------+-------+-------+

      Split Values
+---------+------------+
|Variable |    Value   |
+---------+------------+
|treatment|conventional|
+---------+------------+

                 Descriptive Statistics
+--------------------+--+-----+-------+-------+-------+
|                    | N| Mean|Std Dev|Minimum|Maximum|
+--------------------+--+-----+-------+-------+-------+
|yield               |30|53.57|   8.92|  36.30|  70.66|
|Valid N (listwise)  |30|     |       |       |       |
|Missing N (listwise)| 0|     |       |       |       |
+--------------------+--+-----+-------+-------+-------+

      Split Values
+---------+-----------+
|Variable |   Value   |
+---------+-----------+
|treatment|traditional|
+---------+-----------+

                 Descriptive Statistics
+--------------------+--+-----+-------+-------+-------+
|                    | N| Mean|Std Dev|Minimum|Maximum|
+--------------------+--+-----+-------+-------+-------+
|yield               |30|56.87|   8.88|  39.08|  75.93|
|Valid N (listwise)  |30|     |       |       |       |
|Missing N (listwise)| 0|     |       |       |       |
+--------------------+--+-----+-------+-------+-------+
</screen>
<para>Unless <literal>TEMPORARY</literal> was used, after a split has been defined for
a dataset it remains active until explicitly disabled.
In the graphical user interface, the active split variable (if any) is
displayed in the status bar (see <link linkend="split_002dstatus_002dbar_003ascr">split-status-bar:scr</link>.
If a dataset is saved to a system file (see <link linkend="SAVE">SAVE</link>) whilst a split
is active, the split stastus is stored in the file and will be
automatically loaded when that file is loaded.
</para>
<anchor id="split_002dstatus_002dbar_003ascr"/>
<sidebar></sidebar>

</sect2>
</sect1>
<sect1 label="13.6" id="TEMPORARY">
<title>TEMPORARY</title>
<indexterm role="vr"><primary>TEMPORARY</primary></indexterm>

<literallayout>TEMPORARY.
</literallayout>
<para><literal>TEMPORARY</literal> is used to make the effects of transformations
following its execution temporary.  These transformations
affect only the execution of the next procedure or procedure-like
command.  Their effects are not be saved to the active dataset.
</para>
<para>The only specification on <literal>TEMPORARY</literal> is the command name.
</para>
<para><literal>TEMPORARY</literal> may not appear within a <literal>DO IF</literal> or <literal>LOOP</literal>
construct.  It may appear only once between procedures and
procedure-like commands.
</para>
<para>Scratch variables cannot be used following <literal>TEMPORARY</literal>.
</para>
<sect2 label="13.6.1">
<title>Example Temporary</title>

<para>In <link linkend="temporary_003aex">temporary:ex</link> there are two <literal>COMPUTE</literal> transformation.  One
of them immediatly follows a <literal>TEMPORARY</literal> command, and therefore has
effect only for the next procedure, which in this case is the first
<literal>DESCRIPTIVES</literal> command.
</para>
<anchor id="temporary_003aex"/>
<sidebar><screen>data list notable /x 1-2.
begin data.
 2
 4
10
15
20
24
end data.

compute x=x/2.

temporary.
compute x=x+3.

descriptives x.
descriptives x.
</screen></sidebar>
<para>The data read by the first <literal>DESCRIPTIVES</literal> procedure are 4, 5, 8,
10.5, 13, 15.  The data read by the second <literal>DESCRIPTIVES</literal> procedure are 1, 2,
5, 7.5, 10, 12.   This is because the second <literal>COMPUTE</literal> transformation
has no effect on the second <literal>DESCRIPTIVES</literal> procedure.   You can check these
figures in <link linkend="temporary_003ares">temporary:res</link>.
</para>
<anchor id="temporary_003ares"/>
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                Descriptive Statistics
+--------------------+-+----+-------+-------+-------+
|                    |N|Mean|Std Dev|Minimum|Maximum|
+--------------------+-+----+-------+-------+-------+
|x                   |6|9.25|   4.38|      4|     15|
|Valid N (listwise)  |6|    |       |       |       |
|Missing N (listwise)|0|    |       |       |       |
+--------------------+-+----+-------+-------+-------+

                Descriptive Statistics
+--------------------+-+----+-------+-------+-------+
|                    |N|Mean|Std Dev|Minimum|Maximum|
+--------------------+-+----+-------+-------+-------+
|x                   |6|6.25|   4.38|      1|     12|
|Valid N (listwise)  |6|    |       |       |       |
|Missing N (listwise)|0|    |       |       |       |
+--------------------+-+----+-------+-------+-------+
</screen>

</sect2>
</sect1>
<sect1 label="13.7" id="WEIGHT">
<title>WEIGHT</title>
<indexterm role="vr"><primary>WEIGHT</primary></indexterm>

<literallayout>WEIGHT BY <replaceable>var_name</replaceable>.
WEIGHT OFF.
</literallayout>
<para><literal>WEIGHT</literal> assigns cases varying weights,
changing the frequency distribution of the active dataset.  Execution of
<literal>WEIGHT</literal> is delayed until data have been read.
</para>
<para>If a variable name is specified, <literal>WEIGHT</literal> causes the values of that
variable to be used as weighting factors for subsequent statistical
procedures.  Use of keyword <literal>BY</literal> is optional but recommended.  Weighting
variables must be numeric.  Scratch variables may not be used for
weighting (see <link linkend="Scratch-Variables">Scratch Variables</link>).
</para>
<para>When <literal>OFF</literal> is specified, subsequent statistical procedures weight all
cases equally.
</para>
<para>A positive integer weighting factor <replaceable>w</replaceable> on a case yields the
same statistical output as would replicating the case <replaceable>w</replaceable> times.
A weighting factor of 0 is treated for statistical purposes as if the
case did not exist in the input.  Weighting values need not be
integers, but negative and system-missing values for the weighting
variable are interpreted as weighting factors of 0.  User-missing
values are not treated specially.
</para>
<para>When <literal>WEIGHT</literal> is specified after <literal>TEMPORARY</literal>, it affects only
the next procedure (see <link linkend="TEMPORARY">TEMPORARY</link>).
</para>
<para><literal>WEIGHT</literal> does not cause cases in the active dataset to be
replicated in memory.
</para>

<sect2 label="13.7.1">
<title>Example Weights</title>

<para>One could define a  dataset containing an inventory of stock items.
It would be reasonable to use a string variable for a description of the
item, and a numeric variable for the number in stock, like in <link linkend="weight_003aex">weight:ex</link>.
</para>
<anchor id="weight_003aex"/>
<sidebar><screen>data list notable list /item (a16) quantity (f8.0).
begin   data
nuts    345
screws  10034
washers 32012
bolts   876
end data.

echo 'Unweighted frequency table'.
frequencies /variables = item /format=dfreq.

weight by quantity.

echo 'Weighted frequency table'.
frequencies /variables = item /format=dfreq.
</screen></sidebar>
<para>One analysis which most surely would be of interest is
the relative amounts or each item in stock.
However without setting a weight variable, <literal>FREQUENCIES</literal>
(see <link linkend="FREQUENCIES">FREQUENCIES</link>) does not tell us what we want to know, since
there is only one case for each stock item. <link linkend="weight_003ares">weight:res</link> shows the
difference between the weighted and unweighted frequency tables.
</para>
<anchor id="weight_003ares"/>
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>Unweighted frequency table

                               item
+-------------+---------+-------+-------------+------------------+
|             |Frequency|Percent|Valid Percent|Cumulative Percent|
+-------------+---------+-------+-------------+------------------+
|Valid bolts  |        1|  25.0%|        25.0%|             25.0%|
|      nuts   |        1|  25.0%|        25.0%|             50.0%|
|      screws |        1|  25.0%|        25.0%|             75.0%|
|      washers|        1|  25.0%|        25.0%|            100.0%|
+-------------+---------+-------+-------------+------------------+
|Total        |        4| 100.0%|             |                  |
+-------------+---------+-------+-------------+------------------+

Weighted frequency table

                               item
+-------------+---------+-------+-------------+------------------+
|             |Frequency|Percent|Valid Percent|Cumulative Percent|
+-------------+---------+-------+-------------+------------------+
|Valid washers|    32012|  74.0%|        74.0%|             74.0%|
|      screws |    10034|  23.2%|        23.2%|             97.2%|
|      bolts  |      876|   2.0%|         2.0%|             99.2%|
|      nuts   |      345|    .8%|          .8%|            100.0%|
+-------------+---------+-------+-------------+------------------+
|Total        |    43267| 100.0%|             |                  |
+-------------+---------+-------+-------------+------------------+
</screen><!-- PSPP - a program for statistical analysis. -->
<!-- Copyright (C) 2017, 2020 Free Software Foundation, Inc. -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.3 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<!-- A copy of the license is included in the section entitled "GNU -->
<!-- Free Documentation License". -->
<!-- -->

</sect2>
</sect1>
</chapter>
<chapter label="14" id="Conditionals-and-Looping">
<title>Conditional and Looping Constructs</title>
<indexterm role="cp"><primary>conditionals</primary></indexterm>
<indexterm role="cp"><primary>loops</primary></indexterm>
<indexterm role="cp"><primary>flow of control</primary></indexterm>
<indexterm role="cp"><primary>control flow</primary></indexterm>

<para>This chapter documents PSPP commands used for conditional execution,
looping, and flow of control.
</para>

<sect1 label="14.1" id="BREAK">
<title>BREAK</title>
<indexterm role="vr"><primary>BREAK</primary></indexterm>

<literallayout>BREAK.
</literallayout>
<para><literal>BREAK</literal> terminates execution of the innermost currently executing
<literal>LOOP</literal> construct.
</para>
<para><literal>BREAK</literal> is allowed only inside <literal>LOOP</literal>&#8230;<literal>END LOOP</literal>.
See <link linkend="LOOP">LOOP</link>, for more details.
</para>
</sect1>
<sect1 label="14.2" id="DEFINE">
<title>DEFINE</title>
<indexterm role="vr"><primary>DEFINE</primary></indexterm>
<indexterm role="cp"><primary>macro</primary></indexterm>

<sect2 label="14.2.1" id="Macro-Overview">
<title>Overview</title>

<literallayout><literal>DEFINE</literal> <emphasis>macro_name</emphasis><literal>(</literal>[<emphasis>argument</emphasis>[<literal>/</literal><emphasis>argument</emphasis>]&#8230;]<literal>)</literal>
&#8230;<emphasis>body</emphasis>&#8230;
<literal>!ENDDEFINE.</literal>
</literallayout>
<para>Each <emphasis>argument</emphasis> takes the following form:
</para><literallayout>{<emphasis>!arg_name</emphasis><literal>=</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>!POSITIONAL</literal>}
[<literal>!DEFAULT(</literal><emphasis>default</emphasis><literal>)</literal>]
[<literal>!NOEXPAND</literal>]
{<literal>!TOKENS(</literal><emphasis>count</emphasis><literal>)</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>!CHAREND('</literal><emphasis>token</emphasis><literal>')</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>!ENCLOSE('</literal><emphasis>start</emphasis><literal>' <inlineequation><mathphrase>|</mathphrase></inlineequation> '</literal><emphasis>end</emphasis><literal>')</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>!CMDEND</literal>}
</literallayout>
<para>The following directives may be used within <emphasis>body</emphasis>:
</para><screen>!OFFEXPAND
!ONEXPAND
</screen>
<para>The following functions may be used within the body:
</para><literallayout><literal>!BLANKS(</literal><emphasis>count</emphasis><literal>)</literal>
<literal>!CONCAT(</literal><emphasis>arg</emphasis>&#8230;<literal>)</literal>
<literal>!EVAL(</literal><emphasis>arg</emphasis><literal>)</literal>
<literal>!HEAD(</literal><emphasis>arg</emphasis><literal>)</literal>
<literal>!INDEX(</literal><emphasis>haystack</emphasis><literal>,</literal> <emphasis>needle</emphasis><literal>)</literal>
<literal>!LENGTH(</literal><emphasis>arg</emphasis><literal>)</literal>
<literal>!NULL</literal>
<literal>!QUOTE(</literal><emphasis>arg</emphasis><literal>)</literal>
<literal>!SUBSTR(</literal><emphasis>arg</emphasis><literal>,</literal> <emphasis>start</emphasis>[<literal>,</literal> <emphasis>count</emphasis>]<literal>)</literal>
<literal>!TAIL(</literal><emphasis>arg</emphasis><literal>)</literal>
<literal>!UNQUOTE(</literal><emphasis>arg</emphasis><literal>)</literal>
<literal>!UPCASE(</literal><emphasis>arg</emphasis><literal>)</literal>
</literallayout>
<para>The body may also include the following constructs:
</para><literallayout><literal>!IF (</literal><emphasis>condition</emphasis><literal>) !THEN</literal> <emphasis>true-expansion</emphasis> <literal>!ENDIF</literal>
<literal>!IF (</literal><emphasis>condition</emphasis><literal>) !THEN</literal> <emphasis>true-expansion</emphasis> <literal>!ELSE</literal> <emphasis>false-expansion</emphasis> <literal>!ENDIF</literal>

<literal>!DO</literal> <emphasis>!var</emphasis> <literal>=</literal> <emphasis>start</emphasis> <literal>!TO</literal> <emphasis>end</emphasis> [<literal>!BY</literal> <emphasis>step</emphasis>]
  <emphasis>body</emphasis>
<literal>!DOEND</literal>
<literal>!DO</literal> <emphasis>!var</emphasis> <literal>!IN</literal> <literal>(</literal><emphasis>expression</emphasis><literal>)</literal>
  <emphasis>body</emphasis>
<literal>!DOEND</literal>

<literal>!LET</literal> <emphasis>!var</emphasis> <literal>=</literal> <emphasis>expression</emphasis>
</literallayout>
</sect2>
<sect2 label="14.2.2" id="Macro-Introduction">
<title>Introduction</title>

<para>The DEFINE command creates a <firstterm>macro</firstterm>, which is a name for a
fragment of PSPP syntax called the macro&#8217;s <firstterm>body</firstterm>.  Following the
DEFINE command, syntax may <firstterm>call</firstterm> the macro by name any number of
times.  Each call substitutes, or <firstterm>expands</firstterm>, the macro&#8217;s body in
place of the call, as if the body had been written in its place.
</para>
<para>The following syntax defines a macro named <literal>!vars</literal> that expands
to the variable names <literal>v1 v2 v3</literal>.  The macro&#8217;s name begins with
&#8216;<literal>!</literal>&#8217;, which is optional for macro names.  The <literal>()</literal> following
the macro name are required:
</para>
<screen>DEFINE !vars()
v1 v2 v3
!ENDDEFINE.
</screen>
<para>Here are two ways that <literal>!vars</literal> might be called given the
preceding definition:
</para>
<screen>DESCRIPTIVES !vars.
FREQUENCIES /VARIABLES=!vars.
</screen>
<para>With macro expansion, the above calls are equivalent to the following:
</para>
<screen>DESCRIPTIVES v1 v2 v3.
FREQUENCIES /VARIABLES=v1 v2 v3.
</screen>
<para>The <literal>!vars</literal> macro expands to a fixed body.  Macros may have more
sophisticated contents:
</para>
<itemizedlist><listitem><para>Macro <firstterm>arguments</firstterm> that are substituted into the body whenever they
are named.  The values of a macro&#8217;s arguments are specified each time
it is called.  See <link linkend="Macro-Arguments">Macro Arguments</link>.
</para>
</listitem><listitem><para>Macro <firstterm>functions</firstterm>, expanded when the macro is called.  See <link linkend="Macro-Functions">Macro
Functions</link>.
</para>
</listitem><listitem><para><literal>!IF</literal> constructs, for conditional expansion.  See <link linkend="Macro-Conditional-Expansion">Macro
Conditional Expansion</link>.
</para>
</listitem><listitem><para>Two forms of <literal>!DO</literal> construct, for looping over a numerical range
or a collection of tokens.  See <link linkend="Macro-Loops">Macro Loops</link>.
</para>
</listitem><listitem><para><literal>!LET</literal> constructs, for assigning to macro variables.  See <link linkend="Macro-Variable-Assignment">Macro
Variable Assignment</link>.
</para></listitem></itemizedlist>
<para>Many identifiers associated with macros begin with &#8216;<literal>!</literal>&#8217;, a
character not normally allowed in identifiers.  These identifiers are
reserved only for use with macros, which helps keep them from being
confused with other kinds of identifiers.
</para>
<para>The following sections provide more details on macro syntax and
semantics.
</para>
</sect2>
<sect2 label="14.2.3" id="Macro-Bodies">
<title>Macro Bodies</title>

<para>As previously shown, a macro body may contain a fragment of a PSPP
command (such as a variable name).  A macro body may also contain full
PSPP commands.  In the latter case, the macro body should also contain
the command terminators.
</para>
<para>Most PSPP commands may occur within a macro.  The <literal>DEFINE</literal>
command itself is one exception, because the inner <literal>!ENDDEFINE</literal>
ends the outer macro definition.  For compatibility, <literal>BEGIN
DATA</literal>&#8230;<literal>END DATA.</literal> should not be used within a macro.
</para>
<para>The body of a macro may call another macro.  The following shows one
way that could work:
</para>
<screen>DEFINE !commands()
DESCRIPTIVES !vars.
FREQUENCIES /VARIABLES=!vars.
!ENDDEFINE.

* Initially define the 'vars' macro to analyze v1...v3.
DEFINE !vars() v1 v2 v3 !ENDDEFINE.
!commands

* Redefine 'vars' macro to analyze different variables.
DEFINE !vars() v4 v5 !ENDDEFINE.
!commands
</screen>
<para>The <literal>!commands</literal> macro would be easier to use if it took the
variables to analyze as an argument rather than through another macro.
The following section shows how to do that.
</para>
</sect2>
<sect2 label="14.2.4" id="Macro-Arguments">
<title>Macro Arguments</title>

<para>This section explains how to use macro arguments.  As an initial
example, the following syntax defines a macro named <literal>!analyze</literal>
that takes all the syntax up to the first command terminator as an
argument:
</para>
<screen>DEFINE !analyze(!POSITIONAL !CMDEND)
DESCRIPTIVES !1.
FREQUENCIES /VARIABLES=!1.
!ENDDEFINE.
</screen>
<para>When <literal>!analyze</literal> is called, it expands to a pair of analysis
commands with each <literal>!1</literal> in the body replaced by the argument.
That is, these calls:
</para>
<screen>!analyze v1 v2 v3.
!analyze v4 v5.
</screen>
<para>act like the following:
</para>
<screen>DESCRIPTIVES v1 v2 v3.
FREQUENCIES /VARIABLES=v1 v2 v3.
DESCRIPTIVES v4 v5.
FREQUENCIES /VARIABLES=v4 v5.
</screen>
<para>Macros may take any number of arguments, described within the
parentheses in the DEFINE command.  Arguments come in two varieties
based on how their values are specified when the macro is called:
</para>
<itemizedlist><listitem><para>A <firstterm>positional</firstterm> argument has a required value that follows the
macro&#8217;s name.  Use the <literal>!POSITIONAL</literal> keyword to declare a
positional argument.
</para>
<para>When a macro is called, the positional argument values appear in the
same order as their definitions, before any keyword argument values.
</para>
<para>References to a positional argument in a macro body are numbered:
<literal>!1</literal> is the first positional argument, <literal>!2</literal> the second, and
so on.  In addition, <literal>!*</literal> expands to all of the positional
arguments&#8217; values, separated by spaces.
</para>
<para>The following example uses a positional argument:
</para>
<screen>DEFINE !analyze(!POSITIONAL !CMDEND)
DESCRIPTIVES !1.
FREQUENCIES /VARIABLES=!1.
!ENDDEFINE.

!analyze v1 v2 v3.
!analyze v4 v5.
</screen>
</listitem><listitem><para>A <firstterm>keyword</firstterm> argument has a name.  In the macro call, its value is
specified with the syntax <literal><emphasis>name</emphasis>=<emphasis>value</emphasis></literal>.  The names allow
keyword argument values to take any order in the call.
</para>
<para>In declaration and calls, a keyword argument&#8217;s name may not begin with
&#8216;<literal>!</literal>&#8217;, but references to it in the macro body do start with a
leading &#8216;<literal>!</literal>&#8217;.
</para>
<para>The following example uses a keyword argument that defaults to ALL if
the argument is not assigned a value:
</para>
<screen>DEFINE !analyze_kw(vars=!DEFAULT(ALL) !CMDEND)
DESCRIPTIVES !vars.
FREQUENCIES /VARIABLES=!vars.
!ENDDEFINE.

!analyze_kw vars=v1 v2 v3.  /* Analyze specified variables.
!analyze_kw.                /* Analyze all variables.
</screen></listitem></itemizedlist>
<para>If a macro has both positional and keyword arguments, then the
positional arguments must come first in the DEFINE command, and their
values also come first in macro calls.  A keyword argument may be
omitted by leaving its keyword out of the call, and a positional
argument may be omitted by putting a command terminator where it would
appear.  (The latter case also omits any following positional
arguments and all keyword arguments, if there are any.)  When an
argument is omitted, a default value is used: either the value
specified in <literal>!DEFAULT(<emphasis>value</emphasis>)</literal>, or an empty value otherwise.
</para>
<para>Each argument declaration specifies the form of its value:
</para>
<variablelist><varlistentry><term><literal>!TOKENS(<emphasis>count</emphasis>)</literal>
</term><listitem><para>Exactly <replaceable>count</replaceable> tokens, e.g. <literal>!TOKENS(1)</literal> for a single
token.  Each identifier, number, quoted string, operator, or
punctuator is a token.  See <link linkend="Tokens">Tokens</link>, for a complete definition.
</para>
<para>The following variant of <literal>!analyze_kw</literal> accepts only a single
variable name (or <literal>ALL</literal>) as its argument:
</para>
<screen>DEFINE !analyze_one_var(!POSITIONAL !TOKENS(1))
DESCRIPTIVES !1.
FREQUENCIES /VARIABLES=!1.
!ENDDEFINE.

!analyze_one_var v1.
</screen>
</listitem></varlistentry><varlistentry><term><literal>!CHAREND('<replaceable>token</replaceable>')</literal>
</term><listitem><para>Any number of tokens up to <replaceable>token</replaceable>, which should be an operator or
punctuator token such as &#8216;<literal>/</literal>&#8217; or &#8216;<literal>+</literal>&#8217;.  The <replaceable>token</replaceable> does
not become part of the value.
</para>
<para>With the following variant of <literal>!analyze_kw</literal>, the variables must
be following by &#8216;<literal>/</literal>&#8217;:
</para>
<screen>DEFINE !analyze_parens(vars=!CHARNED('/'))
DESCRIPTIVES !vars.
FREQUENCIES /VARIABLES=!vars.
!ENDDEFINE.

!analyze_parens vars=v1 v2 v3/.
</screen>
</listitem></varlistentry><varlistentry><term><literal>!ENCLOSE('<replaceable>start</replaceable>','<replaceable>end</replaceable>')</literal>
</term><listitem><para>Any number of tokens enclosed between <replaceable>start</replaceable> and <replaceable>end</replaceable>, which
should each be operator or punctuator tokens.  For example, use
<literal>!ENCLOSE('(',')')</literal> for a value enclosed within parentheses.
(Such a value could never have right parentheses inside it, even
paired with left parentheses.)  The start and end tokens are not part
of the value.
</para>
<para>With the following variant of <literal>!analyze_kw</literal>, the variables must
be specified within parentheses:
</para>
<screen>DEFINE !analyze_parens(vars=!ENCLOSE('(',')'))
DESCRIPTIVES !vars.
FREQUENCIES /VARIABLES=!vars.
!ENDDEFINE.

!analyze_parens vars=(v1 v2 v3).
</screen>
</listitem></varlistentry><varlistentry><term><literal>!CMDEND</literal>
</term><listitem><para>Any number of tokens up to the end of the command.  This should be
used only for the last positional parameter, since it consumes all of
the tokens in the command calling the macro.
</para>
<para>The following variant of <literal>!analyze_kw</literal> takes all the variable
names up to the end of the command as its argument:
</para>
<screen>DEFINE !analyze_kw(vars=!CMDEND)
DESCRIPTIVES !vars.
FREQUENCIES /VARIABLES=!vars.
!ENDDEFINE.

!analyze_kw vars=v1 v2 v3.
</screen></listitem></varlistentry></variablelist>
<para>By default, when an argument&#8217;s value contains a macro call, the call
is expanded each time the argument appears in the macro&#8217;s body.  The
<literal>!NOEXPAND</literal> keyword in an argument declaration suppresses this
expansion.  See <link linkend="Controlling-Macro-Expansion">Controlling Macro Expansion</link>.
</para>
</sect2>
<sect2 label="14.2.5" id="Controlling-Macro-Expansion">
<title>Controlling Macro Expansion</title>

<para>Multiple factors control whether macro calls are expanded in different
situations.  At the highest level, <literal>SET MEXPAND</literal> controls whether
macro calls are expanded.  By default, it is enabled.  See <link linkend="SET-MEXPAND">SET
MEXPAND</link>, for details.
</para>
<para>A macro body may contain macro calls.  By default, these are expanded.
If a macro body contains <literal>!OFFEXPAND</literal> or <literal>!ONEXPAND</literal>
directives, then <literal>!OFFEXPAND</literal> disables expansion of macro calls
until the following <literal>!ONEXPAND</literal>.
</para>
<para>A macro argument&#8217;s value may contain a macro call.  These macro calls
are expanded, unless the argument was declared with the
<literal>!NOEXPAND</literal> keyword.
</para>
<para>The argument to a macro function is a special context that does not
expand macro calls.  For example, if <literal>!vars</literal> is the name of a
macro, then <literal>!LENGTH(!vars)</literal> expands to 5, as does
<literal>!LENGTH(!1)</literal> if positional argument 1 has value <literal>!vars</literal>.
To expand macros in these cases, use the <literal>!EVAL</literal> macro function,
e.g. <literal>!LENGTH(!EVAL(!vars))</literal> or <literal>!LENGTH(!EVAL(!1))</literal>.
See <link linkend="Macro-Functions">Macro Functions</link>, for details.
</para>
<para>These rules apply to macro calls, not to uses within a macro body of
macro functions, macro arguments, and macro variables created by
<literal>!DO</literal> or <literal>!LET</literal>, which are always expanded.
</para>
<para><literal>SET MEXPAND</literal> may appear within the body of a macro, but it will
not affect expansion of the macro that it appears in.  Use
<literal>!OFFEXPAND</literal> and <literal>!ONEXPAND</literal> instead.
</para>
</sect2>
<sect2 label="14.2.6" id="Macro-Functions">
<title>Macro Functions</title>

<para>Macro bodies may manipulate syntax using macro functions.  Macro
functions accept tokens as arguments and expand to sequences of
characters.
</para>
<para>The arguments to macro functions have a restricted form.  They may
only be a single token (such as an identifier or a string), a macro
argument, or a call to a macro function.  Thus, the following are
valid macro arguments:
</para><screen>x    5.0    x    !1    &quot;5 + 6&quot;    !CONCAT(x,y)
</screen><para>and the following are not:
</para><screen>x y    5+6
</screen>
<para>Macro functions expand to sequences of characters.  When these
character strings are processed further as character strings, e.g.
with <literal>!LENGTH</literal>, any character string is valid.  When they are
interpreted as PSPP syntax, e.g. when the expansion becomes part of
a command, they need to be valid for that purpose.  For example,
<literal>!UNQUOTE(&quot;It's&quot;)</literal> will yield an error if the expansion
<literal>It's</literal> becomes part of a PSPP command, because it contains
unbalanced single quotes, but <literal>!LENGTH(!UNQUOTE(&quot;It's&quot;))</literal> expands
to 4.
</para>
<para>The following macro functions are available.  Each function&#8217;s
documentation includes examples in the form <literal><replaceable>call</replaceable>
&#8614; <replaceable>expansion</replaceable></literal>.
</para>
<synopsis><indexterm role="fn"><primary>!BLANKS</primary></indexterm><phrase role="category"><emphasis role="bold">Macro Function</emphasis>:</phrase> <function>!BLANKS</function> (<emphasis role="arg">count</emphasis>)</synopsis>
<blockquote><para>Expands to <replaceable>count</replaceable> unquoted spaces, where <replaceable>count</replaceable> is a
nonnegative integer.  Outside quotes, any positive number of spaces
are equivalent; for a quoted string of spaces, use
<literal>!QUOTE(!BLANKS(<replaceable>count</replaceable>))</literal>.
</para>
<para>In the examples below, &#8216;<literal>_</literal>&#8217; stands in for a space to make the
results visible.
</para>
<!-- Keep these examples in sync with the test for !BLANKS in -->
<!-- tests/language/commands/define.at: -->
<screen>!BLANKS(0)                  &#8614; empty
!BLANKS(1)                  &#8614; _
!BLANKS(2)                  &#8614; __
!QUOTE(!BLANKS(5))          &#8614; '_____'
</screen></blockquote>
<synopsis><indexterm role="fn"><primary>!CONCAT</primary></indexterm><phrase role="category"><emphasis role="bold">Macro Function</emphasis>:</phrase> <function>!CONCAT</function> (<emphasis role="arg">arg</emphasis><emphasis role="arg">&#8230;</emphasis>)</synopsis>
<blockquote><para>Expands to the concatenation of all of the arguments.  Before
concatenation, each quoted string argument is unquoted, as if
<literal>!UNQUOTE</literal> were applied.  This allows for &#8220;token pasting&#8221;,
combining two (or more) tokens into a single one:
</para>
<!-- Keep these examples in sync with the test for !CONCAT in -->
<!-- tests/language/commands/define.at: -->
<screen>!CONCAT(x, y)                &#8614; xy
!CONCAT('x', 'y')            &#8614; xy
!CONCAT(12, 34)              &#8614; 1234
!CONCAT(!NULL, 123)          &#8614; 123
</screen>
<para><literal>!CONCAT</literal> is often used for constructing a series of similar
variable names from a prefix followed by a number and perhaps a
suffix.  For example:
</para>
<!-- Keep these examples in sync with the test for !CONCAT in -->
<!-- tests/language/commands/define.at: -->
<screen>!CONCAT(x, 0)                &#8614; x0
!CONCAT(x, 0, y)             &#8614; x0y
</screen>
<para>An identifier token must begin with a letter (or &#8216;<literal>#</literal>&#8217; or
&#8216;<literal>@</literal>&#8217;), which means that attempting to use a number as the first
part of an identifier will produce a pair of distinct tokens rather
than a single one.  For example:
</para>
<!-- Keep these examples in sync with the test for !CONCAT in -->
<!-- tests/language/commands/define.at: -->
<screen>!CONCAT(0, x)                &#8614; 0 x
!CONCAT(0, x, y)             &#8614; 0 xy
</screen></blockquote>
<synopsis><indexterm role="fn"><primary>!EVAL</primary></indexterm><phrase role="category"><emphasis role="bold">Macro Function</emphasis>:</phrase> <function>!EVAL</function> (<emphasis role="arg">arg</emphasis>)</synopsis>
<blockquote><para>Expands macro calls in <replaceable>arg</replaceable>.  This is especially useful if
<replaceable>arg</replaceable> is the name of a macro or a macro argument that expands to
one, because arguments to macro functions are not expanded by default
(see <link linkend="Controlling-Macro-Expansion">Controlling Macro Expansion</link>).
</para>
<para>The following examples assume that <literal>!vars</literal> is a macro that
expands to <literal>a b c</literal>:
</para>
<screen>!vars                        &#8614; a b c
!QUOTE(!vars)                &#8614; '!vars'
!EVAL(!vars)                 &#8614; a b c
!QUOTE(!EVAL(!vars))         &#8614; 'a b c'
</screen>
<para>These examples additionally assume that argument <literal>!1</literal> has value
<literal>!vars</literal>:
</para>
<screen>!1                           &#8614; a b c
!QUOTE(!1)                   &#8614; '!vars'
!EVAL(!1)                    &#8614; a b c
!QUOTE(!EVAL(!1))            &#8614; 'a b c'
</screen></blockquote>
<synopsis><indexterm role="fn"><primary>!HEAD</primary></indexterm><phrase role="category"><emphasis role="bold">Macro Function</emphasis>:</phrase> <function>!HEAD</function> (<emphasis role="arg">arg</emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>!TAIL</primary></indexterm><phrase role="category"><emphasis role="bold">Macro Function</emphasis>:</phrase> <function>!TAIL</function> (<emphasis role="arg">arg</emphasis>)</synopsis>
<blockquote><para><literal>!HEAD</literal> expands to just the first token in an unquoted version of
<replaceable>arg</replaceable>, and <literal>!TAIL</literal> to all the tokens after the first.
</para>
<screen>!HEAD('a b c')               &#8614; a
!HEAD('a')                   &#8614; a
!HEAD(!NULL)                 &#8614; empty
!HEAD('')                    &#8614; empty

!TAIL('a b c')               &#8614; b c
!TAIL('a')                   &#8614; empty
!TAIL(!NULL)                 &#8614; empty
!TAIL('')                    &#8614; empty
</screen></blockquote>
<synopsis><indexterm role="fn"><primary>!INDEX</primary></indexterm><phrase role="category"><emphasis role="bold">Macro Function</emphasis>:</phrase> <function>!INDEX</function> (<emphasis role="arg">haystack</emphasis>, <emphasis role="arg">needle</emphasis>)</synopsis>
<blockquote><para>Looks for <replaceable>needle</replaceable> in <replaceable>haystack</replaceable>.  If it is present, expands
to the 1-based index of its first occurrence; if not, expands to 0.
</para>
<screen>!INDEX(banana, an)           &#8614; 2
!INDEX(banana, nan)          &#8614; 3
!INDEX(banana, apple)        &#8614; 0
!INDEX(&quot;banana&quot;, nan)        &#8614; 4
!INDEX(&quot;banana&quot;, &quot;nan&quot;)      &#8614; 0
!INDEX(!UNQUOTE(&quot;banana&quot;), !UNQUOTE(&quot;nan&quot;)) &#8614; 3
</screen></blockquote>
<synopsis><indexterm role="fn"><primary>!LENGTH</primary></indexterm><phrase role="category"><emphasis role="bold">Macro Function</emphasis>:</phrase> <function>!LENGTH</function> (<emphasis role="arg">arg</emphasis>)</synopsis>
<blockquote><para>Expands to a number token representing the number of characters in
<replaceable>arg</replaceable>.
</para>
<screen>!LENGTH(123)                 &#8614; 3
!LENGTH(123.00)              &#8614; 6
!LENGTH( 123 )               &#8614; 3
!LENGTH(&quot;123&quot;)               &#8614; 5
!LENGTH(xyzzy)               &#8614; 5
!LENGTH(&quot;xyzzy&quot;)             &#8614; 7
!LENGTH(&quot;xy&quot;&quot;zzy&quot;)           &#8614; 9
!LENGTH(!UNQUOTE(&quot;xyzzy&quot;))   &#8614; 5
!LENGTH(!UNQUOTE(&quot;xy&quot;&quot;zzy&quot;)) &#8614; 6
!LENGTH(!1)                  &#8614; 5 if <literal>!1</literal> is <literal>a b c</literal>
!LENGTH(!1)                  &#8614; 0 if <literal>!1</literal> is empty
!LENGTH(!NULL)               &#8614; 0
</screen></blockquote>
<synopsis><indexterm role="fn"><primary>!NULL</primary></indexterm><phrase role="category"><emphasis role="bold">Macro Function</emphasis>:</phrase> <function>!NULL</function></synopsis>
<blockquote><para>Expands to an empty character sequence.
</para>
<!-- Keep these examples in sync with the test for !NULL in -->
<!-- tests/language/commands/define.at: -->
<screen>!NULL                        &#8614; empty
!QUOTE(!NULL)                &#8614; ''
</screen></blockquote>
<synopsis><indexterm role="fn"><primary>!QUOTE</primary></indexterm><phrase role="category"><emphasis role="bold">Macro Function</emphasis>:</phrase> <function>!QUOTE</function> (<emphasis role="arg">arg</emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>!UNQUOTE</primary></indexterm><phrase role="category"><emphasis role="bold">Macro Function</emphasis>:</phrase> <function>!UNQUOTE</function> (<emphasis role="arg">arg</emphasis>)</synopsis>
<blockquote><para>The <literal>!QUOTE</literal> function expands to its argument surrounded by
apostrophes, doubling any apostrophes inside the argument to make sure
that it is valid PSPP syntax for a string.  If the argument was
already a quoted string, <literal>!QUOTE</literal> expands to it unchanged.
</para>
<para>Given a quoted string argument, the <literal>!UNQUOTED</literal> function expands
to the string&#8217;s contents, with the quotes removed and any doubled
quote marks reduced to singletons.  If the argument was not a quoted
string, <literal>!UNQUOTE</literal> expands to the argument unchanged.
</para>
<!-- Keep these examples in sync with the test for !QUOTE and !UNQUOTE in -->
<!-- tests/language/commands/define.at: -->
<screen>!QUOTE(123.0)                &#8614; '123.0'
!QUOTE( 123 )                &#8614; '123'
!QUOTE('a b c')              &#8614; 'a b c'
!QUOTE(&quot;a b c&quot;)              &#8614; &quot;a b c&quot;
!QUOTE(!1)                   &#8614; 'a ''b'' c' if <literal>!1</literal> is <literal>a 'b' c</literal>

!UNQUOTE(123.0)              &#8614; 123.0
!UNQUOTE( 123 )              &#8614; 123
!UNQUOTE('a b c')            &#8614; a b c
!UNQUOTE(&quot;a b c&quot;)            &#8614; a b c
!UNQUOTE(!1)                 &#8614; a 'b' c if <literal>!1</literal> is <literal>a 'b' c</literal>

!QUOTE(!UNQUOTE(123.0))      &#8614; '123.0'
!QUOTE(!UNQUOTE( 123 ))      &#8614; '123'
!QUOTE(!UNQUOTE('a b c'))    &#8614; 'a b c'
!QUOTE(!UNQUOTE(&quot;a b c&quot;))    &#8614; 'a b c'
!QUOTE(!UNQUOTE(!1))         &#8614; 'a ''b'' c' if <literal>!1</literal> is <literal>a 'b' c</literal>
</screen></blockquote>
<synopsis><indexterm role="fn"><primary>!SUBSTR</primary></indexterm><phrase role="category"><emphasis role="bold">Macro Function</emphasis>:</phrase> <function>!SUBSTR</function> (<emphasis role="arg">arg</emphasis>, <emphasis role="arg">start</emphasis>[, <emphasis role="arg">count</emphasis>])</synopsis>
<blockquote><para>Expands to a substring of <replaceable>arg</replaceable> starting from 1-based position
<replaceable>start</replaceable>.  If <replaceable>count</replaceable> is given, it limits the number of
characters in the expansion; if it is omitted, then the expansion
extends to the end of <replaceable>arg</replaceable>.
</para>
<screen>!SUBSTR(banana, 3)           &#8614; nana
!SUBSTR(banana, 3, 3)        &#8614; nan
!SUBSTR(&quot;banana&quot;, 1, 3)         &#8614; error (<literal>&quot;ba</literal> is not a valid token)
!SUBSTR(!UNQUOTE(&quot;banana&quot;), 3) &#8614; nana
!SUBSTR(&quot;banana&quot;, 3, 3)      &#8614; ana

!SUBSTR(banana, 3, 0)        &#8614; empty
!SUBSTR(banana, 3, 10)       &#8614; nana
!SUBSTR(banana, 10, 3)       &#8614; empty
</screen></blockquote>
<synopsis><indexterm role="fn"><primary>!UPCASE</primary></indexterm><phrase role="category"><emphasis role="bold">Macro Function</emphasis>:</phrase> <function>!UPCASE</function> (<emphasis role="arg">arg</emphasis>)</synopsis>
<blockquote><para>Expands to an unquoted version of <replaceable>arg</replaceable> with all letters converted
to uppercase.
</para>
<screen>!UPCASE(freckle)             &#8614; FRECKLE
!UPCASE('freckle')           &#8614; FRECKLE
!UPCASE('a b c')             &#8614; A B C
!UPCASE('A B C')             &#8614; A B C
</screen></blockquote>
</sect2>
<sect2 label="14.2.7" id="Macro-Expressions">
<title>Macro Expressions</title>

<para>Macro expressions are used in conditional expansion and loops, which
are described in the following sections.  A macro expression may use
the following operators, listed in descending order of operator
precedence:
</para>
<variablelist><varlistentry><term><literal>()</literal>
</term><listitem><para>Parentheses override the default operator precedence.
</para>
</listitem></varlistentry><varlistentry><term><literal>!EQ !NE !GT !LT !GE !LE = ~= &lt;&gt; &gt; &lt; &gt;= &lt;=</literal>
</term><listitem><para>Relational operators compare their operands and yield a Boolean
result, either &#8216;<literal>0</literal>&#8217; for false or &#8216;<literal>1</literal>&#8217; for true.
</para>
<para>These operators always compare their operands as strings.  This can be
surprising when the strings are numbers because, e.g., <literal>1 &lt;
1.0</literal> and <literal>10 &lt; 2</literal> both evaluate to &#8216;<literal>1</literal>&#8217; (true).
</para>
<para>Comparisons are case sensitive, so that <literal>a = A</literal> evaluates to
&#8216;<literal>0</literal>&#8217; (false).
</para>
</listitem></varlistentry><varlistentry><term><literal>!NOT ~</literal>
</term><term><literal>!AND &amp;</literal>
</term><term><literal>!OR |</literal>
</term><listitem><para>Logical operators interpret their operands as Boolean values, where
quoted or unquoted &#8216;<literal>0</literal>&#8217; is false and anything else is true, and
yield a Boolean result, either &#8216;<literal>0</literal>&#8217; for false or &#8216;<literal>1</literal>&#8217; for
true.
</para></listitem></varlistentry></variablelist>
<para>Macro expressions do not include any arithmetic operators.
</para>
<para>An operand in an expression may be a single token (including a macro
argument name) or a macro function invocation.  Either way, the
expression evaluator unquotes the operand, so that <literal>1 = '1'</literal> is
true.
</para>
</sect2>
<sect2 label="14.2.8" id="Macro-Conditional-Expansion">
<title>Macro Conditional Expansion</title>

<para>The <literal>!IF</literal> construct may be used inside a macro body to allow for
conditional expansion.  It takes the following forms:
</para>
<screen>!IF (<replaceable>expression</replaceable>) !THEN <replaceable>true-expansion</replaceable> !IFEND
!IF (<replaceable>expression</replaceable>) !THEN <replaceable>true-expansion</replaceable> !ELSE <replaceable>false-expansion</replaceable> !IFEND
</screen>
<para>When <replaceable>expression</replaceable> evaluates to true, the macro processor expands
<replaceable>true-expansion</replaceable>; otherwise, it expands <replaceable>false-expansion</replaceable>, if
it is present.  The macro processor considers quoted or unquoted
&#8216;<literal>0</literal>&#8217; to be false, and anything else to be true.
</para>
</sect2>
<sect2 label="14.2.9" id="Macro-Loops">
<title>Macro Loops</title>

<para>The body of a macro may include two forms of loops: loops over
numerical ranges and loops over tokens.  Both forms expand a <firstterm>loop
body</firstterm> multiple times, each time setting a named <firstterm>loop variable</firstterm> to
a different value.  The loop body typically expands the loop variable
at least once.
</para>
<para>The MITERATE setting (see <link linkend="SET-MITERATE">SET MITERATE</link>) limits the number of
iterations in a loop.  This is a safety measure to ensure that macro
expansion terminates.  PSPP issues a warning when the MITERATE limit
is exceeded.
</para>
<bridgehead renderas="sect3">Loops Over Ranges</bridgehead>

<screen>!DO <replaceable>!var</replaceable> = <replaceable>start</replaceable> !TO <replaceable>end</replaceable> [!BY <replaceable>step</replaceable>]
  <replaceable>body</replaceable>
!DOEND
</screen>
<para>A loop over a numerical range has the form shown above.  <replaceable>start</replaceable>,
<replaceable>end</replaceable>, and <replaceable>step</replaceable> (if included) must be expressions with
numeric values.  The macro processor accepts both integers and real
numbers.  The macro processor expands <replaceable>body</replaceable> for each numeric
value from <replaceable>start</replaceable> to <replaceable>end</replaceable>, inclusive.
</para>
<para>The default value for <replaceable>step</replaceable> is 1.  If <replaceable>step</replaceable> is positive and
<inlineequation><mathphrase><replaceable>first</replaceable> &gt; <replaceable>last</replaceable></mathphrase></inlineequation>, or if <replaceable>step</replaceable> is negative and
<inlineequation><mathphrase><replaceable>first</replaceable> &lt; <replaceable>last</replaceable></mathphrase></inlineequation>, then the macro processor doesn&#8217;t
expand the body at all.  <replaceable>step</replaceable> may not be zero.
</para>
<bridgehead renderas="sect3">Loops Over Tokens</bridgehead>

<screen>!DO <replaceable>!var</replaceable> !IN (<replaceable>expression</replaceable>)
  <replaceable>body</replaceable>
!DOEND
</screen>
<para>A loop over tokens takes the form shown above.  The macro processor
evaluates <replaceable>expression</replaceable> and expands <replaceable>body</replaceable> once per token in
the result, substituting the token for <replaceable>!var</replaceable> each time it
appears.
</para>
</sect2>
<sect2 label="14.2.10" id="Macro-Variable-Assignment">
<title>Macro Variable Assignment</title>

<para>The <literal>!LET</literal> construct evaluates an expression and assigns the
result to a macro variable.  It may create a new macro variable or
change the value of one created by a previous <literal>!LET</literal> or
<literal>!DO</literal>, but it may not change the value of a macro argument.
<literal>!LET</literal> has the following form:
</para>
<screen>!LET <replaceable>!var</replaceable> = <replaceable>expression</replaceable>
</screen>
<para>If <replaceable>expression</replaceable> is more than one token, it must be enclosed in
parentheses.
</para>
</sect2>
<sect2 label="14.2.11" id="Macro-Settings">
<title>Macro Settings</title>

<para>Some macro behavior is controlled through the SET command
(see <link linkend="SET">SET</link>).  This section describes these settings.
</para>
<para>Any SET command that changes these settings within a macro body only
takes effect following the macro.  This is because PSPP expands a
macro&#8217;s entire body at once, so that the SET command inside the body
only executes afterwards.
</para>
<para>The MEXPAND setting (see <link linkend="SET-MEXPAND">SET MEXPAND</link>) controls whether macros will
be expanded at all.  By default, macro expansion is on.  To avoid
expansion of macros called within a macro body, use <literal>!OFFEXPAND</literal>
and <literal>!ONEXPAND</literal> (see <link linkend="Controlling-Macro-Expansion">Controlling Macro Expansion</link>).
</para>
<para>When MPRINT (see <link linkend="SET-MPRINT">SET MPRINT</link>) is turned on, PSPP outputs an
expansion of each macro called.  This feature can be useful for
debugging macro definitions.  For reading the expanded version, note
that macro expansion removes comments and standardizes white space.
</para>
<para>MNEST (see <link linkend="SET-MNEST">SET MNEST</link>) limits the depth of expansion of macro
calls, that is, the nesting level of macro expansion.  The default is
50.  This is mainly useful to avoid infinite expansion in the case of
a macro that calls itself.
</para>
<para>MITERATE (see <link linkend="SET-MITERATE">SET MITERATE</link>) limits the number of iterations in a
<literal>!DO</literal> construct.  The default is 1000.
</para>
</sect2>
<sect2 label="14.2.12" id="Macro-Notes">
<title>Additional Notes</title>

<sect3 label="14.2.12.1">
<title>Calling Macros from Macros</title>

<para>If the body of macro A includes a call to macro B, the call can use
macro arguments (including <literal>!*</literal>) and macro variables as part of
arguments to B.  For <literal>!TOKENS</literal> arguments, the argument or
variable name counts as one token regardless of the number that it
expands into; for <literal>!CHAREND</literal> and <literal>!ENCLOSE</literal> arguments, the
delimiters come only from the call, not the expansions; and
<literal>!CMDEND</literal> ends at the calling command, not any end of command
within an argument or variable.
</para>
<para>Macro functions are not supported as part of the arguments in a macro
call.  To get the same effect, use <literal>!LET</literal> to define a macro
variable, then pass the macro variable to the macro.
</para>
<para>When macro A calls macro B, the order of their <literal>DEFINE</literal> commands
doesn&#8217;t matter, as long as macro B has been defined when A is called.
</para>
</sect3>
<sect3 label="14.2.12.2">
<title>Command Terminators</title>

<para>Macros and command terminators require care.  Macros honor the syntax
differences between interactive and batch syntax (see <link linkend="Syntax-Variants">Syntax
Variants</link>), which means that the interpretation of a macro can vary
depending on the syntax mode in use.  We assume here that interactive
mode is in use, in which &#8216;<literal>.</literal>&#8217; at the end of a line is the
primary way to end a command.
</para>
<para>The <literal>DEFINE</literal> command needs to end with &#8216;<literal>.</literal>&#8217; following the
<literal>!ENDDEFINE</literal>.  The macro body may contain &#8216;<literal>.</literal>&#8217; if it is
intended to expand to whole commands, but using &#8216;<literal>.</literal>&#8217; within a
macro body that expands to just syntax fragments (such as a list of
variables) will cause syntax errors.
</para>
<para>Macro directives such as <literal>!IF</literal> and <literal>!DO</literal> do not end with
&#8216;<literal>.</literal>&#8217;.
</para>
</sect3>
<sect3 label="14.2.12.3">
<title>Expansion Contexts</title>

<para>Macros do not expand within comments, whether introduced within a line
by <literal>/*</literal> or as a separate COMMENT or &#8216;<literal>*</literal>&#8217; commands
(see <link linkend="COMMENT">COMMENT</link>).  (SPSS does expand macros in COMMENT and &#8216;<literal>*</literal>&#8217;.)
</para>
<para>Macros do not expand within quoted strings.
</para>
<para>Macros are expanded in the <literal>TITLE</literal> and <literal>SUBTITLE</literal> commands
as long as their arguments are not quoted strings.
</para>
</sect3>
<sect3 label="14.2.12.4">
<title>PRESERVE and RESTORE</title>

<para>Some macro bodies might use the SET command to change certain
settings.  When this is the case, consider using the PRESERVE and
RESTORE commands to save and then restore these settings.
See <link linkend="PRESERVE-and-RESTORE">PRESERVE and RESTORE</link>.
</para>
</sect3>
</sect2>
</sect1>
<sect1 label="14.3" id="DO-IF">
<title>DO IF</title>
<indexterm role="vr"><primary>DO IF</primary></indexterm>

<literallayout>DO IF condition.
        &#8230;
[ELSE IF condition.
        &#8230;
]&#8230;
[ELSE.
        &#8230;]
END IF.
</literallayout>
<para><literal>DO IF</literal> allows one of several sets of transformations to be
executed, depending on user-specified conditions.
</para>
<para>If the specified boolean expression evaluates as true, then the block
of code following <literal>DO IF</literal> is executed.  If it evaluates as
missing, then
none of the code blocks is executed.  If it is false, then
the boolean expression on the first <literal>ELSE IF</literal>, if present, is tested in
turn, with the same rules applied.  If all expressions evaluate to
false, then the <literal>ELSE</literal> code block is executed, if it is present.
</para>
<para>When <literal>DO IF</literal> or <literal>ELSE IF</literal> is specified following <literal>TEMPORARY</literal>
(see <link linkend="TEMPORARY">TEMPORARY</link>), the <literal>LAG</literal> function may not be used
(see <link linkend="LAG">LAG</link>).
</para>
</sect1>
<sect1 label="14.4" id="DO-REPEAT">
<title>DO REPEAT</title>
<indexterm role="vr"><primary>DO REPEAT</primary></indexterm>

<literallayout>DO REPEAT dummy_name=expansion&#8230;.
        &#8230;
END REPEAT [PRINT].

expansion takes one of the following forms:
        var_list
        num_or_range&#8230;
        &#8217;string&#8217;&#8230;
        ALL

num_or_range takes one of the following forms:
        number
        num1 TO num2
</literallayout>
<para><literal>DO REPEAT</literal> repeats a block of code, textually substituting
different variables, numbers, or strings into the block with each
repetition.
</para>
<para>Specify a dummy variable name followed by an equals sign (&#8216;<literal>=</literal>&#8217;)
and the list of replacements.  Replacements can be a list of existing
or new variables, numbers, strings, or <literal>ALL</literal> to specify all
existing variables.  When numbers are specified, runs of increasing
integers may be indicated as <literal><replaceable>num1</replaceable> TO <replaceable>num2</replaceable></literal>, so that
&#8216;<literal>1 TO 5</literal>&#8217; is short for &#8216;<literal>1 2 3 4 5</literal>&#8217;.
</para>
<para>Multiple dummy variables can be specified.  Each
variable must have the same number of replacements.
</para>
<para>The code within <literal>DO REPEAT</literal> is repeated as many times as there are
replacements for each variable.  The first time, the first value for
each dummy variable is substituted; the second time, the second value
for each dummy variable is substituted; and so on.
</para>
<para>Dummy variable substitutions work like macros.  They take place
anywhere in a line that the dummy variable name occurs.  This includes
command and subcommand names, so command and subcommand names that
appear in the code block should not be used as dummy variable
identifiers.  Dummy variable substitutions do not occur inside quoted
strings, comments, unquoted strings (such as the text on the
<literal>TITLE</literal> or <literal>DOCUMENT</literal> command), or inside <literal>BEGIN
DATA</literal>&#8230;<literal>END DATA</literal>.
</para>
<para>Substitution occurs only on whole words, so that, for example, a dummy
variable PRINT would not be substituted into the word PRINTOUT.
</para>
<para>New variable names used as replacements are not automatically created
as variables, but only if used in the code block in a context that
would create them, <emphasis>e.g.</emphasis> on a <literal>NUMERIC</literal> or <literal>STRING</literal> command
or on the left side of a <literal>COMPUTE</literal> assignment.
</para>
<para>Any command may appear within <literal>DO REPEAT</literal>, including nested <literal>DO REPEAT</literal>
commands.  If <literal>INCLUDE</literal> or <literal>INSERT</literal> appears within <literal>DO REPEAT</literal>,
the substitutions do not apply to the included file.
</para>
<para>If <literal>PRINT</literal> is specified on <literal>END REPEAT</literal>, the commands after
substitutions are made should be printed to the listing file, prefixed
by a plus sign (&#8216;<literal>+</literal>&#8217;).  This feature is not yet implemented.
</para>
</sect1>
<sect1 label="14.5" id="LOOP">
<title>LOOP</title>
<indexterm role="vr"><primary>LOOP</primary></indexterm>

<literallayout>LOOP [<replaceable>index_var</replaceable>=<replaceable>start</replaceable> TO <replaceable>end</replaceable> [BY <replaceable>incr</replaceable>]] [IF <replaceable>condition</replaceable>].
        &#8230;
END LOOP [IF <replaceable>condition</replaceable>].
</literallayout>
<para><literal>LOOP</literal> iterates a group of commands.  A number of
termination options are offered.
</para>
<para>Specify index_var to make that variable count from one value to
another by a particular increment.  <replaceable>index_var</replaceable> must be a pre-existing
numeric variable.  <replaceable>start</replaceable>, <replaceable>end</replaceable>, and <replaceable>incr</replaceable> are numeric expressions
(see <link linkend="Expressions">Expressions</link>.)
</para>
<para>During the first iteration, <replaceable>index_var</replaceable> is set to the value of <replaceable>start</replaceable>.
During each successive iteration, <replaceable>index_var</replaceable> is increased by the value of
<replaceable>incr</replaceable>.  If <replaceable>end</replaceable> &gt; <replaceable>start</replaceable>, then the loop terminates
when <replaceable>index_var</replaceable> &gt; <replaceable>end</replaceable>;
otherwise it terminates when <replaceable>index_var</replaceable> &lt; <replaceable>end</replaceable>.  If <replaceable>incr</replaceable> is not specified
then it defaults to +1 or -1 as appropriate.
</para>
<para>If <replaceable>end</replaceable> &gt; <replaceable>start</replaceable> and <replaceable>incr</replaceable> &lt; 0, or if <replaceable>end</replaceable> &lt; <replaceable>start</replaceable> and
 <replaceable>incr</replaceable> &gt; 0, then the
loop is never executed.  <replaceable>index_var</replaceable> is nevertheless set to the value of
start.
</para>
<para>Modifying <replaceable>index_var</replaceable> within the loop is allowed, but it has no effect on
the value of <replaceable>index_var</replaceable> in the next iteration.
</para>
<para>Specify a boolean expression for the condition on <literal>LOOP</literal> to
cause the loop to be executed only if the condition is true.  If the
condition is false or missing before the loop contents are executed the
first time, the loop contents are not executed at all.
</para>
<para>If index and condition clauses are both present on <literal>LOOP</literal>, the
index variable is always set before the condition is evaluated.  Thus,
a condition that makes use of the index variable will always see the
index value to be used in the next execution of the body.
</para>
<para>Specify a boolean expression for the condition on <literal>END LOOP</literal> to cause
the loop to terminate if the condition is true after the enclosed
code block is executed.  The condition is evaluated at the end of the
loop, not at the beginning, so that the body of a loop with only a
condition on <literal>END LOOP</literal> will always execute at least once.
</para>
<para>If the index clause is not present, then the global <literal>MXLOOPS</literal>
setting, which defaults to 40, limits the number of iterations
(see <link linkend="SET-MXLOOPS">SET MXLOOPS</link>).
</para>
<para><literal>BREAK</literal> also terminates <literal>LOOP</literal> execution (see <link linkend="BREAK">BREAK</link>).
</para>
<para>Loop index variables are by default reset to system-missing from one
case to another, not left, unless a scratch variable is used as index.
When loops are nested, this is usually undesired behavior, which can
be corrected with <literal>LEAVE</literal> (see <link linkend="LEAVE">LEAVE</link>) or by using a scratch
variable as the loop index.
</para>
<para>When <literal>LOOP</literal> or <literal>END LOOP</literal> is specified following <literal>TEMPORARY</literal>
(see <link linkend="TEMPORARY">TEMPORARY</link>), the <literal>LAG</literal> function may not be used
(see <link linkend="LAG">LAG</link>).
<!-- PSPP - a program for statistical analysis. -->
<!-- Copyright (C) 2017, 2020 Free Software Foundation, Inc. -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.3 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<!-- A copy of the license is included in the section entitled "GNU -->
<!-- Free Documentation License". -->
<!-- -->
</para></sect1>
</chapter>
<chapter label="15" id="Statistics">
<title>Statistics</title>

<para>This chapter documents the statistical procedures that PSPP supports so
far.
</para>

<sect1 label="15.1" id="DESCRIPTIVES">
<title>DESCRIPTIVES</title>

<indexterm role="vr"><primary>DESCRIPTIVES</primary></indexterm>
<literallayout>DESCRIPTIVES
        /VARIABLES=<replaceable>var_list</replaceable>
        /MISSING={VARIABLE,LISTWISE} {INCLUDE,NOINCLUDE}
        /FORMAT={LABELS,NOLABELS} {NOINDEX,INDEX} {LINE,SERIAL}
        /SAVE
        /STATISTICS={ALL,MEAN,SEMEAN,STDDEV,VARIANCE,KURTOSIS,
                     SKEWNESS,RANGE,MINIMUM,MAXIMUM,SUM,DEFAULT,
                     SESKEWNESS,SEKURTOSIS}
        /SORT={NONE,MEAN,SEMEAN,STDDEV,VARIANCE,KURTOSIS,SKEWNESS,
               RANGE,MINIMUM,MAXIMUM,SUM,SESKEWNESS,SEKURTOSIS,NAME}
              {A,D}
</literallayout>
<para>The <literal>DESCRIPTIVES</literal> procedure reads the active dataset and outputs
linear descriptive statistics requested by the user.  In addition, it can optionally
compute Z-scores.
</para>
<para>The <literal>VARIABLES</literal> subcommand, which is required, specifies the list of
variables to be analyzed.  Keyword <literal>VARIABLES</literal> is optional.
</para>
<para>All other subcommands are optional:
</para>
<para>The <literal>MISSING</literal> subcommand determines the handling of missing variables.  If
<literal>INCLUDE</literal> is set, then user-missing values are included in the
calculations.  If <literal>NOINCLUDE</literal> is set, which is the default, user-missing
values are excluded.  If <literal>VARIABLE</literal> is set, then missing values are
excluded on a variable by variable basis; if <literal>LISTWISE</literal> is set, then
the entire case is excluded whenever any value in that case has a
system-missing or, if <literal>INCLUDE</literal> is set, user-missing value.
</para>
<para>The <literal>FORMAT</literal> subcommand has no effect.  It is accepted for
backward compatibility.
</para>
<para>The <literal>SAVE</literal> subcommand causes <literal>DESCRIPTIVES</literal> to calculate Z scores for all
the specified variables.  The Z scores are saved to new variables.
Variable names are generated by trying first the original variable name
with Z prepended and truncated to a maximum of 8 characters, then the
names ZSC000 through ZSC999, STDZ00 through STDZ09, ZZZZ00 through
ZZZZ09, ZQZQ00 through ZQZQ09, in that sequence.  In addition, Z score
variable names can be specified explicitly on <literal>VARIABLES</literal> in the variable
list by enclosing them in parentheses after each variable.
When Z scores are calculated, PSPP ignores <literal>TEMPORARY</literal>,
treating temporary transformations as permanent.
</para>
<para>The <literal>STATISTICS</literal> subcommand specifies the statistics to be displayed:
</para>
<variablelist><varlistentry><term><literal><literal>ALL</literal></literal>
</term><listitem><para>All of the statistics below.
</para></listitem></varlistentry><varlistentry><term><literal><literal>MEAN</literal></literal>
</term><listitem><para>Arithmetic mean.
</para></listitem></varlistentry><varlistentry><term><literal><literal>SEMEAN</literal></literal>
</term><listitem><para>Standard error of the mean.
</para></listitem></varlistentry><varlistentry><term><literal><literal>STDDEV</literal></literal>
</term><listitem><para>Standard deviation.
</para></listitem></varlistentry><varlistentry><term><literal><literal>VARIANCE</literal></literal>
</term><listitem><para>Variance.
</para></listitem></varlistentry><varlistentry><term><literal><literal>KURTOSIS</literal></literal>
</term><listitem><para>Kurtosis and standard error of the kurtosis.
</para></listitem></varlistentry><varlistentry><term><literal><literal>SKEWNESS</literal></literal>
</term><listitem><para>Skewness and standard error of the skewness.
</para></listitem></varlistentry><varlistentry><term><literal><literal>RANGE</literal></literal>
</term><listitem><para>Range.
</para></listitem></varlistentry><varlistentry><term><literal>MINIMUM</literal>
</term><listitem><para>Minimum value.
</para></listitem></varlistentry><varlistentry><term><literal>MAXIMUM</literal>
</term><listitem><para>Maximum value.
</para></listitem></varlistentry><varlistentry><term><literal>SUM</literal>
</term><listitem><para>Sum.
</para></listitem></varlistentry><varlistentry><term><literal>DEFAULT</literal>
</term><listitem><para>Mean, standard deviation of the mean, minimum, maximum.
</para></listitem></varlistentry><varlistentry><term><literal>SEKURTOSIS</literal>
</term><listitem><para>Standard error of the kurtosis.
</para></listitem></varlistentry><varlistentry><term><literal>SESKEWNESS</literal>
</term><listitem><para>Standard error of the skewness.
</para></listitem></varlistentry></variablelist>
<para>The <literal>SORT</literal> subcommand specifies how the statistics should be sorted.  Most
of the possible values should be self-explanatory.  <literal>NAME</literal> causes the
statistics to be sorted by name.  By default, the statistics are listed
in the order that they are specified on the <literal>VARIABLES</literal> subcommand.
The <literal>A</literal> and <literal>D</literal> settings request an ascending or descending
sort order, respectively.
</para>
<sect2 label="15.1.1">
<title>Descriptives Example</title>

<para>The <filename>physiology.sav</filename> file contains various physiological data for a sample
of persons.   Running the <literal>DESCRIPTIVES</literal> command on the variables <emphasis role="bold">height</emphasis>
and <emphasis role="bold">temperature</emphasis> with the default options allows one to see simple linear
statistics for these two variables.  In <link linkend="descriptives_003aex">descriptives:ex</link>, these variables
are specfied on the <literal>VARIABLES</literal> subcommand and the <literal>SAVE</literal> option
has been used, to request that Z scores be calculated.
</para>
<para>After the command has completed, this example runs <literal>DESCRIPTIVES</literal> again, this
time on the <emphasis role="bold">zheight</emphasis> and <emphasis role="bold">ztemperature</emphasis> variables,
which are the two normalized (Z-score) variables generated by the
first <literal>DESCRIPTIVES</literal> command.
</para>
<anchor id="descriptives_003aex"/>
<sidebar><screen>get file='physiology.sav'.

descriptives
        /variables = height temperature
        /save.

descriptives
        /variables = zheight ztemperature.
</screen></sidebar>
<anchor id="descriptives_003ascr"/>
<sidebar></sidebar>
<para>In <link linkend="descriptives_003ares">descriptives:res</link>, we can see that there are 40 valid data for each of the variables
and no missing values.   The mean average of the height and temperature is 16677.12
and 37.02 respectively.  The descriptive statistics for temperature seem reasonable.
However there is a very high standard deviation for <emphasis role="bold">height</emphasis> and a suspiciously
low minimum.  This is due to a data entry error in the
data (see <link linkend="Identifying-incorrect-data">Identifying incorrect data</link>).
</para>
<para>In the second Descriptive Statistics command, one can see that the mean and standard
deviation of both Z score variables is 0 and 1 respectively.  All Z score statistics
should have these properties since they are normalized versions of the original scores.
</para>
<anchor id="descriptives_003ares"/>
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>              Mapping of Variables to Z-scores
+--------------------------------------------+------------+
|                   Source                   |   Target   |
+--------------------------------------------+------------+
|Height in millimeters                       |Zheight     |
|Internal body temperature in degrees Celcius|Ztemperature|
+--------------------------------------------+------------+

                             Descriptive Statistics
+------------------------------------------+--+-------+-------+-------+-------+
|                                          | N|  Mean |Std Dev|Minimum|Maximum|
+------------------------------------------+--+-------+-------+-------+-------+
|Height in millimeters                     |40|1677.12| 262.87|    179|   1903|
|Internal body temperature in degrees      |40|  37.02|   1.82|  32.59|  39.97|
|Celcius                                   |  |       |       |       |       |
|Valid N (listwise)                        |40|       |       |       |       |
|Missing N (listwise)                      | 0|       |       |       |       |
+------------------------------------------+--+-------+-------+-------+-------+

                             Descriptive Statistics
+-----------------------------------------+--+---------+------+-------+-------+
|                                         |  |         |  Std |       |       |
|                                         | N|   Mean  |  Dev |Minimum|Maximum|
+-----------------------------------------+--+---------+------+-------+-------+
|Z-score of Height in millimeters         |40|1.93E-015|  1.00|  -5.70|    .86|
|Z-score of Internal body temperature in  |40|1.37E-015|  1.00|  -2.44|   1.62|
|degrees Celcius                          |  |         |      |       |       |
|Valid N (listwise)                       |40|         |      |       |       |
|Missing N (listwise)                     | 0|         |      |       |       |
+-----------------------------------------+--+---------+------+-------+-------+
</screen>
</sect2>
</sect1>
<sect1 label="15.2" id="FREQUENCIES">
<title>FREQUENCIES</title>

<indexterm role="vr"><primary>FREQUENCIES</primary></indexterm>
<literallayout>FREQUENCIES
        /VARIABLES=<replaceable>var_list</replaceable>
        /FORMAT={TABLE,NOTABLE,LIMIT(<replaceable>limit</replaceable>)}
                {AVALUE,DVALUE,AFREQ,DFREQ}
        /MISSING={EXCLUDE,INCLUDE}
        /STATISTICS={DEFAULT,MEAN,SEMEAN,MEDIAN,MODE,STDDEV,VARIANCE,
                     KURTOSIS,SKEWNESS,RANGE,MINIMUM,MAXIMUM,SUM,
                     SESKEWNESS,SEKURTOSIS,ALL,NONE}
        /NTILES=<replaceable>ntiles</replaceable>
        /PERCENTILES=percent&#8230;
        /HISTOGRAM=[MINIMUM(<replaceable>x_min</replaceable>)] [MAXIMUM(<replaceable>x_max</replaceable>)]
                   [{FREQ[(<replaceable>y_max</replaceable>)],PERCENT[(<replaceable>y_max</replaceable>)]}] [{NONORMAL,NORMAL}]
        /PIECHART=[MINIMUM(<replaceable>x_min</replaceable>)] [MAXIMUM(<replaceable>x_max</replaceable>)]
                  [{FREQ,PERCENT}] [{NOMISSING,MISSING}]
        /BARCHART=[MINIMUM(<replaceable>x_min</replaceable>)] [MAXIMUM(<replaceable>x_max</replaceable>)]
                  [{FREQ,PERCENT}]
        /ORDER={ANALYSIS,VARIABLE}


(These options are not currently implemented.)
        /HBAR=&#8230;
        /GROUPED=&#8230;
</literallayout>
<para>The <literal>FREQUENCIES</literal> procedure outputs frequency tables for specified
variables.
<literal>FREQUENCIES</literal> can also calculate and display descriptive statistics
(including median and mode) and percentiles, and various graphical representations
of the frequency distribution.
</para>
<para>The <literal>VARIABLES</literal> subcommand is the only required subcommand.  Specify the
variables to be analyzed.
</para>
<para>The <literal>FORMAT</literal> subcommand controls the output format.  It has several
possible settings:
</para>
<itemizedlist><listitem><para><literal></literal> <literal>TABLE</literal>, the default, causes a frequency table to be output for every
variable specified.  <literal>NOTABLE</literal> prevents them from being output.  <literal>LIMIT</literal>
with a numeric argument causes them to be output except when there are
more than the specified number of values in the table.
</para>
</listitem><listitem><para><literal></literal> Normally frequency tables are sorted in ascending order by value.  This
is <literal>AVALUE</literal>.  <literal>DVALUE</literal> tables are sorted in descending order by value.
<literal>AFREQ</literal> and <literal>DFREQ</literal> tables are sorted in ascending and descending order,
respectively, by frequency count.
</para></listitem></itemizedlist>
<para>The <literal>MISSING</literal> subcommand controls the handling of user-missing values.
When <literal>EXCLUDE</literal>, the default, is set, user-missing values are not included
in frequency tables or statistics.  When <literal>INCLUDE</literal> is set, user-missing
are included.  System-missing values are never included in statistics,
but are listed in frequency tables.
</para>
<para>The available <literal>STATISTICS</literal> are the same as available
in <literal>DESCRIPTIVES</literal> (see <link linkend="DESCRIPTIVES">DESCRIPTIVES</link>), with the addition
of <literal>MEDIAN</literal>, the data&#8217;s median
value, and MODE, the mode.  (If there are multiple modes, the smallest
value is reported.)  By default, the mean, standard deviation of the
mean, minimum, and maximum are reported for each variable.
</para>
<indexterm role="cp"><primary>percentiles</primary></indexterm>
<para><literal>PERCENTILES</literal> causes the specified percentiles to be reported.
The percentiles should  be presented at a list of numbers between 0
and 100 inclusive.
The <literal>NTILES</literal> subcommand causes the percentiles to be reported at the
boundaries of the data set divided into the specified number of ranges.
For instance, <literal>/NTILES=4</literal> would cause quartiles to be reported.
</para>
<indexterm role="cp"><primary>histogram</primary></indexterm>
<para>The <literal>HISTOGRAM</literal> subcommand causes the output to include a histogram for
each specified numeric variable.  The X axis by default ranges from
the minimum to the maximum value observed in the data, but the <literal>MINIMUM</literal>
and <literal>MAXIMUM</literal> keywords can set an explicit range.
<footnote><para>The number of
bins is chosen according to the Freedman-Diaconis rule:
<inlineequation><mathphrase>2 \times IQR(x)n^{-1/3}</mathphrase></inlineequation>, where <inlineequation><mathphrase>IQR(x)</mathphrase></inlineequation> is the interquartile range of <inlineequation><mathphrase>x</mathphrase></inlineequation>
and <inlineequation><mathphrase>n</mathphrase></inlineequation> is the number of samples.    Note that
<literal>EXAMINE</literal> uses a different algorithm to determine bin sizes.</para></footnote>
Histograms are not created for string variables.
</para>
<para>Specify <literal>NORMAL</literal> to superimpose a normal curve on the
histogram.
</para>
<indexterm role="cp"><primary>piechart</primary></indexterm>
<para>The <literal>PIECHART</literal> subcommand adds a pie chart for each variable to the data.  Each
slice represents one value, with the size of the slice proportional to
the value&#8217;s frequency.  By default, all non-missing values are given
slices.
The <literal>MINIMUM</literal> and <literal>MAXIMUM</literal> keywords can be used to limit the
displayed slices to a given range of values.
The keyword <literal>NOMISSING</literal> causes missing values to be omitted from the
piechart.  This is the default.
If instead, <literal>MISSING</literal> is specified, then the pie chart includes
a single slice representing all system missing and user-missing cases.
</para>
<indexterm role="cp"><primary>bar chart</primary></indexterm>
<para>The <literal>BARCHART</literal> subcommand produces a bar chart for each variable.
The <literal>MINIMUM</literal> and <literal>MAXIMUM</literal> keywords can be used to omit
categories whose counts which lie outside the specified limits.
The <literal>FREQ</literal> option (default) causes the ordinate to display the frequency
of each category, whereas the <literal>PERCENT</literal> option displays relative
percentages.
</para>
<para>The <literal>FREQ</literal> and <literal>PERCENT</literal> options on <literal>HISTOGRAM</literal> and
<literal>PIECHART</literal> are accepted but not currently honoured.
</para>
<para>The <literal>ORDER</literal> subcommand is accepted but ignored.
</para>
<sect2 label="15.2.1">
<title>Frequencies Example</title>

<para><link linkend="frequencies_003aex">frequencies:ex</link> runs a frequency analysis on the <emphasis role="bold">sex</emphasis>
and <emphasis role="bold">occupation</emphasis> variables from the <filename>personnel.sav</filename> file.
This is useful to get a general idea of the way in which these nominal
variables are distributed.
</para>
<anchor id="frequencies_003aex"/>
<sidebar><screen>get file='personnel.sav'.

frequencies /variables = sex occupation
            /statistics = none.
</screen></sidebar>
<para>If you are using the graphic user interface, the dialog box is set up such that
by default, several statistics are calculated.   Some are not particularly useful
for categorical variables, so you may want to disable those.
</para>
<anchor id="frequencies_003ascr"/>
<sidebar></sidebar>
<para>From <link linkend="frequencies_003ares">frequencies:res</link> it is evident that there are 33 males, 21 females and
2 persons for whom their sex has not been entered.
</para>
<para>One can also see how many of each occupation there are in the data.
When dealing with string variables used as nominal values, running a frequency
analysis is useful to detect data input entries.  Notice that
one <emphasis role="bold">occupation</emphasis> value has been mistyped as &#8220;Scrientist&#8221;.  This entry should
be corrected, or marked as missing before using the data.
</para>
<anchor id="frequencies_003ares"/>
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                                sex
+--------------+---------+-------+-------------+------------------+
|              |Frequency|Percent|Valid Percent|Cumulative Percent|
+--------------+---------+-------+-------------+------------------+
|Valid   Male  |       33|  58.9%|        61.1%|             61.1%|
|        Female|       21|  37.5%|        38.9%|            100.0%|
+--------------+---------+-------+-------------+------------------+
|Missing .     |        2|   3.6%|             |                  |
+--------------+---------+-------+-------------+------------------+
|Total         |       56| 100.0%|             |                  |
+--------------+---------+-------+-------------+------------------+

                                  occupation
+------------------------+---------+-------+-------------+------------------+
|                        |Frequency|Percent|Valid Percent|Cumulative Percent|
+------------------------+---------+-------+-------------+------------------+
|Valid Artist            |        8|  14.3%|        14.3%|             14.3%|
|      Baker             |        2|   3.6%|         3.6%|             17.9%|
|      Barrister         |        1|   1.8%|         1.8%|             19.6%|
|      Carpenter         |        4|   7.1%|         7.1%|             26.8%|
|      Cleaner           |        4|   7.1%|         7.1%|             33.9%|
|      Cook              |        7|  12.5%|        12.5%|             46.4%|
|      Manager           |        8|  14.3%|        14.3%|             60.7%|
|      Mathematician     |        4|   7.1%|         7.1%|             67.9%|
|      Painter           |        2|   3.6%|         3.6%|             71.4%|
|      Payload Specialist|        1|   1.8%|         1.8%|             73.2%|
|      Plumber           |        5|   8.9%|         8.9%|             82.1%|
|      Scientist         |        7|  12.5%|        12.5%|             94.6%|
|      Scrientist        |        1|   1.8%|         1.8%|             96.4%|
|      Tailor            |        2|   3.6%|         3.6%|            100.0%|
+------------------------+---------+-------+-------------+------------------+
|Total                   |       56| 100.0%|             |                  |
+------------------------+---------+-------+-------------+------------------+
</screen>
</sect2>
</sect1>
<sect1 label="15.3" id="EXAMINE">
<title>EXAMINE</title>

<indexterm role="vr"><primary>EXAMINE</primary></indexterm>
<indexterm role="cp"><primary>Exploratory data analysis</primary></indexterm>
<indexterm role="cp"><primary>normality, testing</primary></indexterm>

<literallayout>EXAMINE
        VARIABLES= <replaceable>var1</replaceable> [<replaceable>var2</replaceable>] &#8230; [<replaceable>varN</replaceable>]
           [BY <replaceable>factor1</replaceable> [BY <replaceable>subfactor1</replaceable>]
             [ <replaceable>factor2</replaceable> [BY <replaceable>subfactor2</replaceable>]]
             &#8230;
             [ <replaceable>factor3</replaceable> [BY <replaceable>subfactor3</replaceable>]]
            ]
        /STATISTICS={DESCRIPTIVES, EXTREME[(<replaceable>n</replaceable>)], ALL, NONE}
        /PLOT={BOXPLOT, NPPLOT, HISTOGRAM, SPREADLEVEL[(<replaceable>t</replaceable>)], ALL, NONE}
        /CINTERVAL <replaceable>p</replaceable>
        /COMPARE={GROUPS,VARIABLES}
        /ID=<replaceable>identity_variable</replaceable>
        /{TOTAL,NOTOTAL}
        /PERCENTILE=[<replaceable>percentiles</replaceable>]={HAVERAGE, WAVERAGE, ROUND, AEMPIRICAL, EMPIRICAL }
        /MISSING={LISTWISE, PAIRWISE} [{EXCLUDE, INCLUDE}]
		[{NOREPORT,REPORT}]

</literallayout>
<para>The <literal>EXAMINE</literal> command is used to perform exploratory data analysis.
In particular, it is useful for testing how closely a distribution follows a
normal distribution, and for finding outliers and extreme values.
</para>
<para>The <literal>VARIABLES</literal> subcommand is mandatory.
It specifies the dependent variables and optionally variables to use as
factors for the analysis.
Variables listed before the first <literal>BY</literal> keyword (if any) are the
dependent variables.
The dependent variables may optionally be followed by a list of
factors which tell PSPP how to break down the analysis for each
dependent variable.
</para>
<para>Following the dependent variables, factors may be specified.
The factors (if desired) should be preceded by a single <literal>BY</literal> keyword.
The format for each factor is
</para><literallayout><replaceable>factorvar</replaceable> [BY <replaceable>subfactorvar</replaceable>].
</literallayout><para>Each unique combination of the values of  <replaceable>factorvar</replaceable> and
<replaceable>subfactorvar</replaceable> divide the dataset into <firstterm>cells</firstterm>.
Statistics are calculated for each cell
and for the entire dataset (unless <literal>NOTOTAL</literal> is given).
</para>
<para>The <literal>STATISTICS</literal> subcommand specifies which statistics to show.
<literal>DESCRIPTIVES</literal> produces a table showing some parametric and
non-parametrics statistics.
<literal>EXTREME</literal> produces a table showing the extremities of each cell.
A number in parentheses, <replaceable>n</replaceable> determines
how many upper and lower extremities to show.
The default number is 5.
</para>
<para>The subcommands <literal>TOTAL</literal> and <literal>NOTOTAL</literal> are mutually exclusive.
If <literal>TOTAL</literal> appears, then statistics for the entire dataset
as well as for each cell are produced.
If <literal>NOTOTAL</literal> appears, then statistics are produced only for the cells
(unless no factor variables have been given).
These subcommands have no effect if there have  been no factor variables
specified.
</para>
<indexterm role="cp"><primary>boxplot</primary></indexterm>
<indexterm role="cp"><primary>histogram</primary></indexterm>
<indexterm role="cp"><primary>npplot</primary></indexterm>
<indexterm role="cp"><primary>spreadlevel plot</primary></indexterm>
<para>The <literal>PLOT</literal> subcommand specifies which plots are to be produced if any.
Available plots are <literal>HISTOGRAM</literal>, <literal>NPPLOT</literal>,  <literal>BOXPLOT</literal> and
<literal>SPREADLEVEL</literal>.
The first three can be used to visualise how closely each cell conforms to a
normal distribution, whilst the spread vs. level plot can be useful to visualise
how the variance differs between factors.
Boxplots show you the outliers and extreme values.
<footnote><para><literal>HISTOGRAM</literal> uses Sturges&#8217; rule to determine the number of
bins, as approximately <inlineequation><mathphrase>1 + \log2(n)</mathphrase></inlineequation>, where <inlineequation><mathphrase>n</mathphrase></inlineequation> is the number of samples.
Note that <literal>FREQUENCIES</literal> uses a different algorithm to find the bin size.</para></footnote>
</para>
<para>The <literal>SPREADLEVEL</literal> plot displays the interquartile range versus the
median.  It takes an optional parameter <replaceable>t</replaceable>, which specifies how the data
should be transformed prior to plotting.
The given value <replaceable>t</replaceable> is a power to which the data are raised.  For example, if
<replaceable>t</replaceable> is given as 2, then the square of the data is used.
Zero, however is a special value.  If <replaceable>t</replaceable> is 0 or
is omitted, then data are transformed by taking its natural logarithm instead of
raising to the power of <replaceable>t</replaceable>.
</para>
<indexterm role="cp"><primary>Shapiro-Wilk</primary></indexterm>
<para>When one or more plots are requested, <literal>EXAMINE</literal> also performs the
Shapiro-Wilk test for each category.
There are however a number of provisos:
</para><itemizedlist><listitem><para>All weight values must be integer.
</para></listitem><listitem><para>The cumulative weight value must be in the range [3, 5000]
</para></listitem></itemizedlist>
<para>The <literal>COMPARE</literal> subcommand is only relevant if producing boxplots, and it is only
useful there is more than one dependent variable and at least one factor.
If
<literal>/COMPARE=GROUPS</literal> is specified, then one plot per dependent variable is produced,
each of which contain boxplots for all the cells.
If <literal>/COMPARE=VARIABLES</literal> is specified, then one plot per cell is produced,
each containing one boxplot per dependent variable.
If the <literal>/COMPARE</literal> subcommand is omitted, then PSPP behaves as if
<literal>/COMPARE=GROUPS</literal> were given.
</para>
<para>The <literal>ID</literal> subcommand is relevant only if <literal>/PLOT=BOXPLOT</literal> or
<literal>/STATISTICS=EXTREME</literal> has been given.
If given, it should provide the name of a variable which is to be used
to labels extreme values and outliers.
Numeric or string variables are permissible.
If the <literal>ID</literal> subcommand is not given, then the case number is used for
labelling.
</para>
<para>The <literal>CINTERVAL</literal> subcommand specifies the confidence interval to use in
calculation of the descriptives command.  The default is 95%.
</para>
<indexterm role="cp"><primary>percentiles</primary></indexterm>
<para>The <literal>PERCENTILES</literal> subcommand specifies which percentiles are to be calculated,
and which algorithm to use for calculating them.  The default is to
calculate the 5, 10, 25, 50, 75, 90, 95 percentiles using the
<literal>HAVERAGE</literal> algorithm.
</para>
<para>The <literal>TOTAL</literal> and <literal>NOTOTAL</literal> subcommands are mutually exclusive.  If <literal>NOTOTAL</literal>
is given and factors have been specified in the <literal>VARIABLES</literal> subcommand,
then statistics for the unfactored dependent variables are
produced in addition to the factored variables.  If there are no
factors specified then <literal>TOTAL</literal> and <literal>NOTOTAL</literal> have no effect.
</para>

<para>The following example generates descriptive statistics and histograms for
two variables <replaceable>score1</replaceable> and <replaceable>score2</replaceable>.
Two factors are given, <emphasis>viz</emphasis>: <replaceable>gender</replaceable> and <replaceable>gender</replaceable> BY <replaceable>culture</replaceable>.
Therefore, the descriptives and histograms are generated for each
distinct  value
of <replaceable>gender</replaceable> <emphasis>and</emphasis> for each distinct combination of the values
of <replaceable>gender</replaceable> and <replaceable>race</replaceable>.
Since the <literal>NOTOTAL</literal> keyword is given, statistics and histograms for
<replaceable>score1</replaceable> and <replaceable>score2</replaceable> covering the  whole dataset are not produced.
</para><screen>EXAMINE <replaceable>score1</replaceable> <replaceable>score2</replaceable> BY
        <replaceable>gender</replaceable>
        <replaceable>gender</replaceable> BY <replaceable>culture</replaceable>
        /STATISTICS = DESCRIPTIVES
        /PLOT = HISTOGRAM
        /NOTOTAL.
</screen>
<para>Here is a second example showing how the <literal>examine</literal> command can be used to find extremities.
</para><screen>EXAMINE <replaceable>height</replaceable> <replaceable>weight</replaceable> BY
        <replaceable>gender</replaceable>
        /STATISTICS = EXTREME (3)
        /PLOT = BOXPLOT
        /COMPARE = GROUPS
        /ID = <replaceable>name</replaceable>.
</screen><para>In this example, we look at the height and weight of a sample of individuals and
how they differ between male and female.
A table showing the 3 largest and the 3 smallest values of <emphasis role="bold">height</emphasis> and
<emphasis role="bold">weight</emphasis> for each gender, and for the whole dataset as are shown.
In addition, the <literal>/PLOT</literal> subcommand requests boxplots.
Because <literal>/COMPARE = GROUPS</literal> was specified, boxplots for male and female are
shown in juxtaposed in the same graphic, allowing us to easily see the difference between
the genders.
Since the variable <replaceable>name</replaceable> was specified on the <literal>ID</literal> subcommand,
values of the <replaceable>name</replaceable> variable are used to label the extreme values.
</para>
<para><emphasis role="bold">Warning!</emphasis>
If you specify many dependent variables or factor variables
for which there are many distinct values, then <literal>EXAMINE</literal> will produce a very
large quantity of output.
</para>
</sect1>
<sect1 label="15.4" id="GRAPH">
<title>GRAPH</title>

<indexterm role="vr"><primary>GRAPH</primary></indexterm>
<indexterm role="cp"><primary>Exploratory data analysis</primary></indexterm>
<indexterm role="cp"><primary>normality, testing</primary></indexterm>

<literallayout>GRAPH
        /HISTOGRAM [(NORMAL)]= <replaceable>var</replaceable>
        /SCATTERPLOT [(BIVARIATE)] = <replaceable>var1</replaceable> WITH <replaceable>var2</replaceable> [BY <replaceable>var3</replaceable>]
        /BAR = {<replaceable>summary-function</replaceable>(<replaceable>var1</replaceable>) | <replaceable>count-function</replaceable>} BY <replaceable>var2</replaceable> [BY <replaceable>var3</replaceable>]
        [ /MISSING={LISTWISE, VARIABLE} [{EXCLUDE, INCLUDE}] ]
		[{NOREPORT,REPORT}]

</literallayout>
<para>The <literal>GRAPH</literal> command produces graphical plots of data. Only one of the subcommands
<literal>HISTOGRAM</literal>, <literal>BAR</literal> or <literal>SCATTERPLOT</literal> can be specified, <emphasis>i.e.</emphasis> only one plot
can be produced per call of <literal>GRAPH</literal>. The <literal>MISSING</literal> is optional.
</para>

<sect2 label="15.4.1" id="SCATTERPLOT">
<title>Scatterplot</title>
<indexterm role="cp"><primary>scatterplot</primary></indexterm>

<para>The subcommand <literal>SCATTERPLOT</literal> produces an xy plot of the
data.
<literal>GRAPH</literal> uses the third variable <replaceable>var3</replaceable>, if specified, to determine
the colours and/or markers for the plot.
The following is an example for producing a scatterplot.
</para>
<screen>GRAPH
        /SCATTERPLOT = <replaceable>height</replaceable> WITH <replaceable>weight</replaceable> BY <replaceable>gender</replaceable>.
</screen>
<para>This example produces a scatterplot where <replaceable>height</replaceable> is plotted versus <replaceable>weight</replaceable>. Depending
on the value of the <replaceable>gender</replaceable> variable, the colour of the datapoint is different. With
this plot it is possible to analyze gender differences for <replaceable>height</replaceable> versus <replaceable>weight</replaceable> relation.
</para>
</sect2>
<sect2 label="15.4.2" id="HISTOGRAM">
<title>Histogram</title>
<indexterm role="cp"><primary>histogram</primary></indexterm>

<para>The subcommand <literal>HISTOGRAM</literal> produces a histogram. Only one variable is allowed for
the histogram plot.
The keyword <literal>NORMAL</literal> may be specified in parentheses, to indicate that the ideal normal curve
should be superimposed over the histogram.
For an alternative method to produce histograms see <link linkend="EXAMINE">EXAMINE</link>. The
following example produces a histogram plot for the variable <replaceable>weight</replaceable>.
</para>
<screen>GRAPH
        /HISTOGRAM = <replaceable>weight</replaceable>.
</screen>
</sect2>
<sect2 label="15.4.3" id="BAR-CHART">
<title>Bar Chart</title>
<indexterm role="cp"><primary>bar chart</primary></indexterm>

<para>The subcommand <literal>BAR</literal> produces a bar chart.
This subcommand requires that a <replaceable>count-function</replaceable> be specified (with no arguments) or a <replaceable>summary-function</replaceable> with a variable <replaceable>var1</replaceable> in parentheses.
Following the summary or count function, the keyword <literal>BY</literal> should be specified and then a catagorical variable, <replaceable>var2</replaceable>.
The values of the variable <replaceable>var2</replaceable> determine the labels of the bars to be plotted.
Optionally a second categorical variable <replaceable>var3</replaceable> may be specified in which case a clustered (grouped) bar chart is produced.
</para>
<para>Valid count functions are
</para><variablelist><varlistentry><term><literal>COUNT</literal>
</term><listitem><para>The weighted counts of the cases in each category.
</para></listitem></varlistentry><varlistentry><term><literal>PCT</literal>
</term><listitem><para>The weighted counts of the cases in each category expressed as a percentage of the total weights of the cases.
</para></listitem></varlistentry><varlistentry><term><literal>CUFREQ</literal>
</term><listitem><para>The cumulative weighted counts of the cases in each category.
</para></listitem></varlistentry><varlistentry><term><literal>CUPCT</literal>
</term><listitem><para>The cumulative weighted counts of the cases in each category expressed as a percentage of the total weights of the cases.
</para></listitem></varlistentry></variablelist>
<para>The summary function is applied to <replaceable>var1</replaceable> across all cases in each category.
The recognised summary functions are:
</para><variablelist><varlistentry><term><literal>SUM</literal>
</term><listitem><para>The sum.
</para></listitem></varlistentry><varlistentry><term><literal>MEAN</literal>
</term><listitem><para>The arithmetic mean.
</para></listitem></varlistentry><varlistentry><term><literal>MAXIMUM</literal>
</term><listitem><para>The maximum value.
</para></listitem></varlistentry><varlistentry><term><literal>MINIMUM</literal>
</term><listitem><para>The minimum value.
</para></listitem></varlistentry></variablelist>
<para>The following examples assume a dataset which is the results of a survey.
Each respondent has indicated annual income, their sex and city of residence.
One could create a bar chart showing how the mean income varies between of residents of different cities, thus:
</para><screen>GRAPH  /BAR  = MEAN(<replaceable>income</replaceable>) BY <replaceable>city</replaceable>.
</screen>
<para>This can be extended to also indicate how income in each city differs between the sexes.
</para><screen>GRAPH  /BAR  = MEAN(<replaceable>income</replaceable>) BY <replaceable>city</replaceable> BY <replaceable>sex</replaceable>.
</screen>
<para>One might also want to see how many respondents there are from each city.  This can be achieved as follows:
</para><screen>GRAPH  /BAR  = COUNT BY <replaceable>city</replaceable>.
</screen>
<para>Bar charts can also be produced using the <link linkend="FREQUENCIES">FREQUENCIES</link> and <link linkend="CROSSTABS">CROSSTABS</link> commands.
</para>
</sect2>
</sect1>
<sect1 label="15.5" id="CORRELATIONS">
<title>CORRELATIONS</title>

<indexterm role="vr"><primary>CORRELATIONS</primary></indexterm>
<literallayout>CORRELATIONS
     /VARIABLES = <replaceable>var_list</replaceable> [ WITH <replaceable>var_list</replaceable> ]
     [
      .
      .
      .
      /VARIABLES = <replaceable>var_list</replaceable> [ WITH <replaceable>var_list</replaceable> ]
      /VARIABLES = <replaceable>var_list</replaceable> [ WITH <replaceable>var_list</replaceable> ]
     ]

     [ /PRINT={TWOTAIL, ONETAIL} {SIG, NOSIG} ]
     [ /STATISTICS=DESCRIPTIVES XPROD ALL]
     [ /MISSING={PAIRWISE, LISTWISE} {INCLUDE, EXCLUDE} ]
</literallayout>
<indexterm role="cp"><primary>correlation</primary></indexterm>
<para>The <literal>CORRELATIONS</literal> procedure produces tables of the Pearson correlation coefficient
for a set of variables.  The significance of the coefficients are also given.
</para>
<para>At least one <literal>VARIABLES</literal> subcommand is required. If you specify the <literal>WITH</literal>
keyword, then a non-square correlation table is produced.
The variables preceding <literal>WITH</literal>, are used as the rows of the table,
and the variables following <literal>WITH</literal> are used as the columns of the table.
If no <literal>WITH</literal> subcommand is specified, then <literal>CORRELATIONS</literal> produces a
square, symmetrical table using all variables.
</para>
<para>The <literal>MISSING</literal> subcommand determines the handling of missing variables.
If <literal>INCLUDE</literal> is set, then user-missing values are included in the
calculations, but system-missing values are not.
If <literal>EXCLUDE</literal> is set, which is the default, user-missing
values are excluded as well as system-missing values.
</para>
<para>If <literal>LISTWISE</literal> is set, then the entire case is excluded from analysis
whenever any variable  specified in any <literal>/VARIABLES</literal> subcommand
contains a missing value.
If <literal>PAIRWISE</literal> is set, then a case is considered missing only if either of the
values  for the particular coefficient are missing.
The default is <literal>PAIRWISE</literal>.
</para>
<para>The <literal>PRINT</literal> subcommand is used to control how the reported significance values are printed.
If the <literal>TWOTAIL</literal> option is used, then a two-tailed test of significance is
printed.  If the <literal>ONETAIL</literal> option is given, then a one-tailed test is used.
The default is <literal>TWOTAIL</literal>.
</para>
<para>If the <literal>NOSIG</literal> option is specified, then correlation coefficients with significance less than
0.05 are highlighted.
If <literal>SIG</literal> is specified, then no highlighting is performed.  This is the default.
</para>
<indexterm role="cp"><primary>covariance</primary></indexterm>
<para>The <literal>STATISTICS</literal> subcommand requests additional statistics to be displayed.  The keyword
<literal>DESCRIPTIVES</literal> requests that the mean, number of non-missing cases, and the non-biased
estimator of the standard deviation are displayed.
These statistics are displayed in a separated table, for all the variables listed
in any <literal>/VARIABLES</literal> subcommand.
The <literal>XPROD</literal> keyword requests cross-product deviations and covariance estimators to
be displayed for each pair of variables.
The keyword <literal>ALL</literal> is the union of <literal>DESCRIPTIVES</literal> and <literal>XPROD</literal>.
</para>
</sect1>
<sect1 label="15.6" id="CROSSTABS">
<title>CROSSTABS</title>

<indexterm role="vr"><primary>CROSSTABS</primary></indexterm>
<literallayout>CROSSTABS
        /TABLES=<replaceable>var_list</replaceable> BY <replaceable>var_list</replaceable> [BY <replaceable>var_list</replaceable>]&#8230;
        /MISSING={TABLE,INCLUDE,REPORT}
        /FORMAT={TABLES,NOTABLES}
                {AVALUE,DVALUE}
        /CELLS={COUNT,ROW,COLUMN,TOTAL,EXPECTED,RESIDUAL,SRESIDUAL,
                ASRESIDUAL,ALL,NONE}
        /COUNT={ASIS,CASE,CELL}
               {ROUND,TRUNCATE}
        /STATISTICS={CHISQ,PHI,CC,LAMBDA,UC,BTAU,CTAU,RISK,GAMMA,D,
                     KAPPA,ETA,CORR,ALL,NONE}
        /BARCHART

(Integer mode.)
        /VARIABLES=<replaceable>var_list</replaceable> (<replaceable>low</replaceable>,<replaceable>high</replaceable>)&#8230;
</literallayout>
<para>The <literal>CROSSTABS</literal> procedure displays crosstabulation
tables requested by the user.  It can calculate several statistics for
each cell in the crosstabulation tables.  In addition, a number of
statistics can be calculated for each table itself.
</para>
<para>The <literal>TABLES</literal> subcommand is used to specify the tables to be reported.  Any
number of dimensions is permitted, and any number of variables per
dimension is allowed.  The <literal>TABLES</literal> subcommand may be repeated as many
times as needed.  This is the only required subcommand in <firstterm>general
mode</firstterm>.
</para>
<para>Occasionally, one may want to invoke a special mode called <firstterm>integer
mode</firstterm>.  Normally, in general mode, PSPP automatically determines
what values occur in the data.  In integer mode, the user specifies the
range of values that the data assumes.  To invoke this mode, specify the
<literal>VARIABLES</literal> subcommand, giving a range of data values in parentheses for
each variable to be used on the <literal>TABLES</literal> subcommand.  Data values inside
the range are truncated to the nearest integer, then assigned to that
value.  If values occur outside this range, they are discarded.  When it
is present, the <literal>VARIABLES</literal> subcommand must precede the <literal>TABLES</literal>
subcommand.
</para>
<para>In general mode, numeric and string variables may be specified on
TABLES.  In integer mode, only numeric variables are allowed.
</para>
<para>The <literal>MISSING</literal> subcommand determines the handling of user-missing values.
When set to <literal>TABLE</literal>, the default, missing values are dropped on a table by
table basis.  When set to <literal>INCLUDE</literal>, user-missing values are included in
tables and statistics.  When set to <literal>REPORT</literal>, which is allowed only in
integer mode, user-missing values are included in tables but marked with
a footnote and excluded from statistical calculations.
</para>
<para>The <literal>FORMAT</literal> subcommand controls the characteristics of the
crosstabulation tables to be displayed.  It has a number of possible
settings:
</para>
<itemizedlist><listitem><para><!-- /@w --> <literal>TABLES</literal>, the default, causes crosstabulation tables to be output.
<literal>NOTABLES</literal>, which is equivalent to <literal>CELLS=NONE</literal>, suppresses them.
</para>
</listitem><listitem><para><!-- /@w --> <literal>AVALUE</literal>, the default, causes values to be sorted in ascending order.
<literal>DVALUE</literal> asserts a descending sort order.
</para></listitem></itemizedlist>
<para>The <literal>CELLS</literal> subcommand controls the contents of each cell in the displayed
crosstabulation table.  The possible settings are:
</para>
<variablelist><varlistentry><term>COUNT
</term><listitem><para>Frequency count.
</para></listitem></varlistentry><varlistentry><term>ROW
</term><listitem><para>Row percent.
</para></listitem></varlistentry><varlistentry><term>COLUMN
</term><listitem><para>Column percent.
</para></listitem></varlistentry><varlistentry><term>TOTAL
</term><listitem><para>Table percent.
</para></listitem></varlistentry><varlistentry><term>EXPECTED
</term><listitem><para>Expected value.
</para></listitem></varlistentry><varlistentry><term>RESIDUAL
</term><listitem><para>Residual.
</para></listitem></varlistentry><varlistentry><term>SRESIDUAL
</term><listitem><para>Standardized residual.
</para></listitem></varlistentry><varlistentry><term>ASRESIDUAL
</term><listitem><para>Adjusted standardized residual.
</para></listitem></varlistentry><varlistentry><term>ALL
</term><listitem><para>All of the above.
</para></listitem></varlistentry><varlistentry><term>NONE
</term><listitem><para>Suppress cells entirely.
</para></listitem></varlistentry></variablelist>
<para>&#8216;<literal>/CELLS</literal>&#8217; without any settings specified requests <literal>COUNT</literal>, <literal>ROW</literal>,
<literal>COLUMN</literal>, and <literal>TOTAL</literal>.
If <literal>CELLS</literal> is not specified at all then only <literal>COUNT</literal>
is selected.
</para>
<para>By default, crosstabulation and statistics use raw case weights,
without rounding.  Use the <literal>/COUNT</literal> subcommand to perform
rounding: CASE rounds the weights of individual weights as cases are
read, CELL rounds the weights of cells within each crosstabulation
table after it has been constructed, and ASIS explicitly specifies the
default non-rounding behavior.  When rounding is requested, ROUND, the
default, rounds to the nearest integer and TRUNCATE rounds toward
zero.
</para>
<para>The <literal>STATISTICS</literal> subcommand selects statistics for computation:
</para>
<variablelist><varlistentry><term>CHISQ
</term><listitem><indexterm role="cp"><primary>chi-square</primary></indexterm>

<para>Pearson chi-square, likelihood ratio, Fisher&#8217;s exact test, continuity
correction, linear-by-linear association.
</para></listitem></varlistentry><varlistentry><term>PHI
</term><listitem><para>Phi.
</para></listitem></varlistentry><varlistentry><term>CC
</term><listitem><para>Contingency coefficient.
</para></listitem></varlistentry><varlistentry><term>LAMBDA
</term><listitem><para>Lambda.
</para></listitem></varlistentry><varlistentry><term>UC
</term><listitem><para>Uncertainty coefficient.
</para></listitem></varlistentry><varlistentry><term>BTAU
</term><listitem><para>Tau-b.
</para></listitem></varlistentry><varlistentry><term>CTAU
</term><listitem><para>Tau-c.
</para></listitem></varlistentry><varlistentry><term>RISK
</term><listitem><para>Risk estimate.
</para></listitem></varlistentry><varlistentry><term>GAMMA
</term><listitem><para>Gamma.
</para></listitem></varlistentry><varlistentry><term>D
</term><listitem><para>Somers&#8217; D.
</para></listitem></varlistentry><varlistentry><term>KAPPA
</term><listitem><para>Cohen&#8217;s Kappa.
</para></listitem></varlistentry><varlistentry><term>ETA
</term><listitem><para>Eta.
</para></listitem></varlistentry><varlistentry><term>CORR
</term><listitem><para>Spearman correlation, Pearson&#8217;s r.
</para></listitem></varlistentry><varlistentry><term>ALL
</term><listitem><para>All of the above.
</para></listitem></varlistentry><varlistentry><term>NONE
</term><listitem><para>No statistics.
</para></listitem></varlistentry></variablelist>
<para>Selected statistics are only calculated when appropriate for the
statistic.  Certain statistics require tables of a particular size, and
some statistics are calculated only in integer mode.
</para>
<para>&#8216;<literal>/STATISTICS</literal>&#8217; without any settings selects CHISQ.  If the
<literal>STATISTICS</literal> subcommand is not given, no statistics are calculated.
</para>
<indexterm role="cp"><primary>bar chart</primary></indexterm>
<para>The &#8216;<literal>/BARCHART</literal>&#8217; subcommand produces a clustered bar chart for the first two
variables on each table.
If a table has more than two variables, the counts for the third and subsequent levels
are aggregated and the chart is produced as if there were only two variables.
</para>

<para><emphasis role="bold">Please note:</emphasis> Currently the implementation of <literal>CROSSTABS</literal> has the
following limitations:
</para>
<itemizedlist><listitem><para>Significance of some directional measures is not calculated.
</para></listitem><listitem><para>Asymptotic standard error is not calculated for
Goodman and Kruskal&#8217;s tau or symmetric Somers&#8217; d.
</para></listitem><listitem><para>Approximate T is not calculated for symmetric uncertainty coefficient.
</para></listitem></itemizedlist>
<para>Fixes for any of these deficiencies would be welcomed.
</para>
<sect2 label="15.6.1">
<title>Crosstabs Example</title>

<indexterm role="cp"><primary>chi-square test of independence</primary></indexterm>

<para>A researcher wishes to know if, in an industry, a person&#8217;s sex is related to
the person&#8217;s occupation.  To investigate this, she has determined that the
<filename>personnel.sav</filename> is a representative, randomly selected sample of persons.
The researcher&#8217;s null hypothesis is that a person&#8217;s sex has no relation to a
person&#8217;s occupation. She uses a chi-squared test of independence to investigate
the hypothesis.
</para>
<anchor id="crosstabs_003aex"/>
<sidebar><screen>get file=&quot;personnel.sav&quot;.

crosstabs
	/tables= occupation by sex
	/cells = count expected
	/statistics=chisq.


</screen></sidebar>
<para>The syntax in <link linkend="crosstabs_003aex">crosstabs:ex</link> conducts a chi-squared test of independence.
The line <literal>/tables = occupation by sex</literal> indicates that <emphasis role="bold">occupation</emphasis>
and <emphasis role="bold">sex</emphasis> are the variables to be tabulated.  To do this using the graphic user interface
you must place these variable names respectively in the &#8216;<literal>Row</literal>&#8217; and
&#8216;<literal>Column</literal>&#8217; fields as shown in <link linkend="crosstabs_003ascr">crosstabs:scr</link>.
</para>
<anchor id="crosstabs_003ascr"/>
<sidebar></sidebar>
<para>Similarly, the &#8216;<literal>Cells</literal>&#8217; button shows a dialog box to select the <literal>count</literal>
and <literal>expected</literal> options.  All other cell options can be deselected for this
test.
</para>
<para>You would use the &#8216;<literal>Format</literal>&#8217; and &#8216;<literal>Statistics</literal>&#8217;  buttons to select options
for the <literal>FORMAT</literal> and <literal>STATISTICS</literal> subcommands.  In this example,
the &#8216;<literal>Statistics</literal>&#8217; requires only the &#8216;<literal>Chisq</literal>&#8217; option to be checked.  All
other options should be unchecked.  No special settings are required from the
&#8216;<literal>Format</literal>&#8217; dialog.
</para>
<para>As shown in <link linkend="crosstabs_003ares">crosstabs:res</link> <literal>CROSSTABS</literal> generates a contingency table
containing the observed count and the expected count of each sex and each
occupation.  The expected count is the count which would be observed if the
null hypothesis were true.
</para>
<para>The significance of the Pearson Chi-Square value is very much larger than the
normally accepted value of 0.05 and so one cannot reject the null hypothesis.
Thus the researcher must conclude that a person&#8217;s sex has no relation to the
person&#8217;s occupation.
</para>
<anchor id="crosstabs_003ares"/>
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                      Summary
+----------------+-------------------------------+
|                |             Cases             |
|                +----------+---------+----------+
|                |   Valid  | Missing |   Total  |
|                +--+-------+-+-------+--+-------+
|                | N|Percent|N|Percent| N|Percent|
+----------------+--+-------+-+-------+--+-------+
|occupation × sex|54|  96.4%|2|   3.6%|56| 100.0%|
+----------------+--+-------+-+-------+--+-------+

                     occupation × sex
+--------------------------------------+-----------+-----+
|                                      |    sex    |     |
|                                      +----+------+     |
|                                      |Male|Female|Total|
+--------------------------------------+----+------+-----+
|occupation Artist             Count   |   2|     6|    8|
|                              Expected|4.89|  3.11|  .15|
|          ----------------------------+----+------+-----+
|           Baker              Count   |   1|     1|    2|
|                              Expected|1.22|   .78|  .04|
|          ----------------------------+----+------+-----+
|           Barrister          Count   |   0|     1|    1|
|                              Expected| .61|   .39|  .02|
|          ----------------------------+----+------+-----+
|           Carpenter          Count   |   3|     1|    4|
|                              Expected|2.44|  1.56|  .07|
|          ----------------------------+----+------+-----+
|           Cleaner            Count   |   4|     0|    4|
|                              Expected|2.44|  1.56|  .07|
|          ----------------------------+----+------+-----+
|           Cook               Count   |   3|     2|    5|
|                              Expected|3.06|  1.94|  .09|
|          ----------------------------+----+------+-----+
|           Manager            Count   |   4|     4|    8|
|                              Expected|4.89|  3.11|  .15|
|          ----------------------------+----+------+-----+
|           Mathematician      Count   |   3|     1|    4|
|                              Expected|2.44|  1.56|  .07|
|          ----------------------------+----+------+-----+
|           Painter            Count   |   1|     1|    2|
|                              Expected|1.22|   .78|  .04|
|          ----------------------------+----+------+-----+
|           Payload Specialist Count   |   1|     0|    1|
|                              Expected| .61|   .39|  .02|
|          ----------------------------+----+------+-----+
|           Plumber            Count   |   5|     0|    5|
|                              Expected|3.06|  1.94|  .09|
|          ----------------------------+----+------+-----+
|           Scientist          Count   |   5|     2|    7|
|                              Expected|4.28|  2.72|  .13|
|          ----------------------------+----+------+-----+
|           Scrientist         Count   |   0|     1|    1|
|                              Expected| .61|   .39|  .02|
|          ----------------------------+----+------+-----+
|           Tailor             Count   |   1|     1|    2|
|                              Expected|1.22|   .78|  .04|
+--------------------------------------+----+------+-----+
|Total                         Count   |  33|    21|   54|
|                              Expected| .61|   .39| 1.00|
+--------------------------------------+----+------+-----+

                    Chi-Square Tests
+------------------+-----+--+--------------------------+
|                  |Value|df|Asymptotic Sig. (2-tailed)|
+------------------+-----+--+--------------------------+
|Pearson Chi-Square|15.59|13|                      .272|
|Likelihood Ratio  |19.66|13|                      .104|
|N of Valid Cases  |   54|  |                          |
+------------------+-----+--+--------------------------+
</screen>
</sect2>
</sect1>
<sect1 label="15.7" id="CTABLES">
<title>CTABLES</title>

<indexterm role="vr"><primary>CTABLES</primary></indexterm>
<indexterm role="cp"><primary>custom tables</primary></indexterm>
<indexterm role="cp"><primary>tables, custom</primary></indexterm>

<para><literal>CTABLES</literal> has the following overall syntax.  At least one
<literal>TABLE</literal> subcommand is required:
</para>
<literallayout><literal>CTABLES</literal>
  &#8230;<emphasis>global subcommands</emphasis>&#8230;
  [<literal>/TABLE</literal> <emphasis>axis</emphasis> [<literal>BY</literal> <emphasis>axis</emphasis> [<literal>BY</literal> <emphasis>axis</emphasis>]]
   &#8230;<emphasis>per-table subcommands</emphasis>&#8230;]&#8230;
</literallayout>
<para>where each <emphasis>axis</emphasis> may be empty or take one of the following forms:
</para>
<literallayout><emphasis>variable</emphasis>
<emphasis>variable</emphasis> <literal>[</literal>{<literal>C</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>S</literal>}<literal>]</literal>
<emphasis>axis</emphasis> + <emphasis>axis</emphasis>
<emphasis>axis</emphasis> &gt; <emphasis>axis</emphasis>
(<emphasis>axis</emphasis>)
<emphasis>axis</emphasis> <literal>[</literal><emphasis>summary</emphasis> [<emphasis>string</emphasis>] [<emphasis>format</emphasis>]<literal>]</literal>
</literallayout>
<para>The following subcommands precede the first <literal>TABLE</literal> subcommand
and apply to all of the output tables.  All of these subcommands are
optional:
</para>
<literallayout><literal>/FORMAT</literal>
    [<literal>MINCOLWIDTH=</literal>{<literal>DEFAULT</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <emphasis>width</emphasis>}]
    [<literal>MAXCOLWIDTH=</literal>{<literal>DEFAULT</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <emphasis>width</emphasis>}]
    [<literal>UNITS=</literal>{<literal>POINTS</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>INCHES</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>CM</literal>}]
    [<literal>EMPTY=</literal>{<literal>ZERO</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>BLANK</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <emphasis>string</emphasis>}]
    [<literal>MISSING=</literal><emphasis>string</emphasis>]
<literal>/VLABELS</literal>
    <literal>VARIABLES=</literal><emphasis>variables</emphasis>
    <literal>DISPLAY</literal>={<literal>DEFAULT</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>NAME</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>LABEL</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>BOTH</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>NONE</literal>}
<literal>/SMISSING</literal> {<literal>VARIABLE</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>LISTWISE</literal>}
<literal>/PCOMPUTE</literal> <literal>&amp;</literal><emphasis>postcompute</emphasis><literal>=EXPR(</literal><emphasis>expression</emphasis><literal>)</literal>
<literal>/PPROPERTIES</literal> <literal>&amp;</literal><emphasis>postcompute</emphasis>&#8230;
    [<literal>LABEL=</literal><emphasis>string</emphasis>]
    [<literal>FORMAT=</literal>[<emphasis>summary</emphasis> <emphasis>format</emphasis>]&#8230;]
    [<literal>HIDESOURCECATS=</literal>{<literal>NO</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>YES</literal>}
<literal>/WEIGHT VARIABLE=</literal><emphasis>variable</emphasis>
<literal>/HIDESMALLCOUNTS COUNT=<emphasis>count</emphasis></literal>
</literallayout>
<para>The following subcommands follow <literal>TABLE</literal> and apply only to the
previous <literal>TABLE</literal>.  All of these subcommands are optional:
</para>
<literallayout><literal>/SLABELS</literal>
    [<literal>POSITION=</literal>{<literal>COLUMN</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>ROW</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>LAYER</literal>}]
    [<literal>VISIBLE=</literal>{<literal>YES</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>NO</literal>}]
<literal>/CLABELS</literal> {<literal>AUTO</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> {<literal>ROWLABELS</literal><inlineequation><mathphrase>|</mathphrase></inlineequation><literal>COLLABELS</literal>}<literal>=</literal>{<literal>OPPOSITE</literal><inlineequation><mathphrase>|</mathphrase></inlineequation><literal>LAYER</literal>}}
<literal>/CATEGORIES</literal> <literal>VARIABLES=</literal><emphasis>variables</emphasis>
    {<literal>[</literal><emphasis>value</emphasis><literal>,</literal> <emphasis>value</emphasis>&#8230;<literal>]</literal>
   <inlineequation><mathphrase>|</mathphrase></inlineequation> [<literal>ORDER=</literal>{<literal>A</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>D</literal>}]
     [<literal>KEY=</literal>{<literal>VALUE</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>LABEL</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <emphasis>summary</emphasis><literal>(</literal><emphasis>variable</emphasis><literal>)</literal>}]
     [<literal>MISSING=</literal>{<literal>EXCLUDE</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>INCLUDE</literal>}]}
    [<literal>TOTAL=</literal>{<literal>NO</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>YES</literal>} [<literal>LABEL=</literal><emphasis>string</emphasis>] [<literal>POSITION=</literal>{<literal>AFTER</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>BEFORE</literal>}]]
    [<literal>EMPTY=</literal>{<literal>INCLUDE</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>EXCLUDE</literal>}]
<literal>/TITLES</literal>
    [<literal>TITLE=</literal><emphasis>string</emphasis>&#8230;]
    [<literal>CAPTION=</literal><emphasis>string</emphasis>&#8230;]
    [<literal>CORNER=</literal><emphasis>string</emphasis>&#8230;]
</literallayout>
<para>The <literal>CTABLES</literal> (aka &#8220;custom tables&#8221;) command produces
multi-dimensional tables from categorical and scale data.  It offers
many options for data summarization and formatting.
</para>
<para>This section&#8217;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 <ulink url="https://data.transportation.gov">https://data.transportation.gov</ulink>.  PSPP includes
this data set, with a modified dictionary, as
<filename>examples/nhtsa.sav</filename>.
</para>
<sect2 label="15.7.1" id="CTABLES-Basics">
<title>Basics</title>

<para>The only required subcommand is <literal>TABLE</literal>, which specifies the
variables to include along each axis:
</para><literallayout><literal>/TABLE</literal> <emphasis>rows</emphasis> [<literal>BY</literal> <emphasis>columns</emphasis> [<literal>BY</literal> <emphasis>layers</emphasis>]]
</literallayout><para>In <literal>TABLE</literal>, each of <replaceable>rows</replaceable>, <replaceable>columns</replaceable>, and <replaceable>layers</replaceable>
is either empty or an axis expression that specifies one or more
variables.  At least one must specify an axis expression.
</para>
<sect3 label="15.7.1.1" id="CTABLES-Categorical-Variable-Basics">
<title>Categorical Variables</title>

<para>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 <literal>TABLE</literal> are categorical, by default each cell
displays the number of cases that it contains, so specifying a single
variable yields a frequency table, much like the output of the
<literal>FREQUENCIES</literal> command (see <link linkend="FREQUENCIES">FREQUENCIES</link>):
</para>
<screen>CTABLES /TABLE=ageGroup.
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>         Custom Tables
+-----------------------+-----+
|                       |Count|
+-----------------------+-----+
|Age group 15 or younger|    0|
|          16 to 25     | 1099|
|          26 to 35     |  967|
|          36 to 45     | 1037|
|          46 to 55     | 1175|
|          56 to 65     | 1247|
|          66 or older  | 1474|
+-----------------------+-----+
</screen>
<para>Specifying a row and a column categorical variable yields a
crosstabulation, much like the output of the <literal>CROSSTABS</literal> command
(see <link linkend="CROSSTABS">CROSSTABS</link>):
</para>
<screen>CTABLES /TABLE=ageGroup BY gender.
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>             Custom Tables
+-----------------------+------------+
|                       |S3a. GENDER:|
|                       +-----+------+
|                       | Male|Female|
|                       +-----+------+
|                       |Count| Count|
+-----------------------+-----+------+
|Age group 15 or younger|    0|     0|
|          16 to 25     |  594|   505|
|          26 to 35     |  476|   491|
|          36 to 45     |  489|   548|
|          46 to 55     |  526|   649|
|          56 to 65     |  516|   731|
|          66 or older  |  531|   943|
+-----------------------+-----+------+
</screen>
<para>The &#8216;<literal>&gt;</literal>&#8217; &#8220;nesting&#8221; operator nests multiple variables on a single
axis, e.g.:
</para>
<screen>CTABLES /TABLE likelihoodOfBeingStoppedByPolice BY ageGroup &gt; gender.
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                                 Custom Tables
+---------------------------------+-------------------------------------------+
|                                 |  86. In the past year, have you hosted a  |
|                                 |  social event or party where alcohol was  |
|                                 |             served to adults?             |
|                                 +---------------------+---------------------+
|                                 |         Yes         |          No         |
|                                 +---------------------+---------------------+
|                                 |        Count        |        Count        |
+---------------------------------+---------------------+---------------------+
|Age    15 or      S3a.     Male  |                    0|                    0|
|group  younger    GENDER:  Female|                    0|                    0|
|      ---------------------------+---------------------+---------------------+
|       16 to 25   S3a.     Male  |                  208|                  386|
|                  GENDER:  Female|                  202|                  303|
|      ---------------------------+---------------------+---------------------+
|       26 to 35   S3a.     Male  |                  225|                  251|
|                  GENDER:  Female|                  242|                  249|
|      ---------------------------+---------------------+---------------------+
|       36 to 45   S3a.     Male  |                  223|                  266|
|                  GENDER:  Female|                  240|                  307|
|      ---------------------------+---------------------+---------------------+
|       46 to 55   S3a.     Male  |                  201|                  325|
|                  GENDER:  Female|                  282|                  366|
|      ---------------------------+---------------------+---------------------+
|       56 to 65   S3a.     Male  |                  196|                  320|
|                  GENDER:  Female|                  279|                  452|
|      ---------------------------+---------------------+---------------------+
|       66 or      S3a.     Male  |                  162|                  367|
|       older      GENDER:  Female|                  243|                  700|
+---------------------------------+---------------------+---------------------+
</screen>
<para>The &#8216;<literal>+</literal>&#8217; &#8220;stacking&#8221; operator allows a single output table to
include multiple data analyses.  With &#8216;<literal>+</literal>&#8217;, <literal>CTABLES</literal> divides
the output table into multiple <firstterm>sections</firstterm>, 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:
</para>
<screen>CTABLES /TABLE ageGroup + freqOfDriving BY gender.
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                                 Custom Tables
+----------------------------------------------------------------+------------+
|                                                                |S3a. GENDER:|
|                                                                +-----+------+
|                                                                | Male|Female|
|                                                                +-----+------+
|                                                                |Count| Count|
+----------------------------------------------------------------+-----+------+
|Age group                                    15 or younger      |    0|     0|
|                                             16 to 25           |  594|   505|
|                                             26 to 35           |  476|   491|
|                                             36 to 45           |  489|   548|
|                                             46 to 55           |  526|   649|
|                                             56 to 65           |  516|   731|
|                                             66 or older        |  531|   943|
+----------------------------------------------------------------+-----+------+
| 1. How often do you usually drive a car or  Every day          | 2305|  2362|
|other motor vehicle?                         Several days a week|  440|   834|
|                                             Once a week or less|  125|   236|
|                                             Only certain times |   58|    72|
|                                             a year             |     |      |
|                                             Never              |  192|   348|
+----------------------------------------------------------------+-----+------+
</screen>
<para>When &#8216;<literal>+</literal>&#8217; and &#8216;<literal>&gt;</literal>&#8217; are used together, &#8216;<literal>&gt;</literal>&#8217; binds more
tightly.  Use parentheses to override operator precedence.  Thus:
</para>
<screen>CTABLES /TABLE hasConsideredReduction + hasBeenCriticized &gt; gender.
CTABLES /TABLE (hasConsideredReduction + hasBeenCriticized) &gt; gender.
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                                 Custom Tables
+-----------------------------------------------------------------------+-----+
|                                                                       |Count|
+-----------------------------------------------------------------------+-----+
|26. During the last 12 months, has there been a    Yes                 |  513|
|time when you felt you should cut down on your    ---------------------+-----+
|drinking?                                          No                  | 3710|
+-----------------------------------------------------------------------+-----+
|27. During the last 12 months, has there been a    Yes S3a.      Male  |  135|
|time when people criticized your drinking?             GENDER:   Female|   49|
|                                                  ---------------------+-----+
|                                                   No  S3a.      Male  | 1916|
|                                                       GENDER:   Female| 2126|
+-----------------------------------------------------------------------+-----+

                                 Custom Tables
+-----------------------------------------------------------------------+-----+
|                                                                       |Count|
+-----------------------------------------------------------------------+-----+
|26. During the last 12 months, has there been a    Yes S3a.      Male  |  333|
|time when you felt you should cut down on your         GENDER:   Female|  180|
|drinking?                                         ---------------------+-----+
|                                                   No  S3a.      Male  | 1719|
|                                                       GENDER:   Female| 1991|
+-----------------------------------------------------------------------+-----+
|27. During the last 12 months, has there been a    Yes S3a.      Male  |  135|
|time when people criticized your drinking?             GENDER:   Female|   49|
|                                                  ---------------------+-----+
|                                                   No  S3a.      Male  | 1916|
|                                                       GENDER:   Female| 2126|
+-----------------------------------------------------------------------+-----+
</screen>
</sect3>
<sect3 label="15.7.1.2" id="CTABLES-Scalar-Variable-Basics">
<title>Scalar Variables</title>

<para>For a categorical variable, <literal>CTABLES</literal> divides the table into a
cell per category.  For a scalar variable, <literal>CTABLES</literal> 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:
</para>
<screen>CTABLES /TABLE age.
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>          Custom Tables
+--------------------------+----+
|                          |Mean|
+--------------------------+----+
|D1. AGE: What is your age?|  48|
+--------------------------+----+
</screen>
<para>A scalar variable may nest with categorical variables.  The following
example shows the mean age of survey respondents across gender and
language groups:
</para>
<screen>CTABLES /TABLE gender &gt; age BY region.
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                                 Custom Tables
+-------------------------------------+---------------------------------------+
|                                     |Was this interview conducted in English|
|                                     |              or Spanish?              |
|                                     +-------------------+-------------------+
|                                     |      English      |      Spanish      |
|                                     +-------------------+-------------------+
|                                     |        Mean       |        Mean       |
+-------------------------------------+-------------------+-------------------+
|D1. AGE: What is   S3a.        Male  |                 46|                 37|
|your age?          GENDER:     Female|                 51|                 39|
+-------------------------------------+-------------------+-------------------+
</screen>
<para>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:
</para>
<screen>CTABLES /TABLE age &gt; gender BY region.
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                                 Custom Tables
+-------------------------------------+---------------------------------------+
|                                     |Was this interview conducted in English|
|                                     |              or Spanish?              |
|                                     +-------------------+-------------------+
|                                     |      English      |      Spanish      |
|                                     +-------------------+-------------------+
|                                     |        Mean       |        Mean       |
+-------------------------------------+-------------------+-------------------+
|S3a.       Male   D1. AGE: What is   |                 46|                 37|
|GENDER:           your age?          |                   |                   |
|          ---------------------------+-------------------+-------------------+
|           Female D1. AGE: What is   |                 51|                 39|
|                  your age?          |                   |                   |
+-------------------------------------+-------------------+-------------------+
</screen>
<para>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
<literal>TABLE</literal>.
</para>
</sect3>
<sect3 label="15.7.1.3" id="CTABLES-Overriding-Measurement-Level">
<title>Overriding Measurement Level</title>

<para>By default, <literal>CTABLES</literal> uses a variable&#8217;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.
</para>
<para>When PSPP reads data from a file in an external format, such as a
text file, variables&#8217; measurement levels are often unknown.  If
<literal>CTABLES</literal> runs when a variable has an unknown measurement level,
it makes an initial pass through the data to guess measurement levels
using the rules described in an earlier section (see <link linkend="Measurement-Level">Measurement
Level</link>).  Use the <literal>VARIABLE LEVEL</literal> command to set or change a
variable&#8217;s measurement level (see <link linkend="VARIABLE-LEVEL">VARIABLE LEVEL</link>).
</para>
<para>To treat a variable as categorical or scalar only for one use on
<literal>CTABLES</literal>, add &#8216;<literal>[C]</literal>&#8217; or &#8216;<literal>[S]</literal>&#8217;, respectively, after the
variable name.  The following example shows the output when variable
<literal>monthDaysMin1drink</literal> is analyzed as scalar (the default for its measurement
level) and as categorical:
</para>
<screen>CTABLES
    /TABLE monthDaysMin1drink BY gender
    /TABLE monthDaysMin1drink [C] BY gender.
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                                 Custom Tables
+----------------------------------------------------------------+------------+
|                                                                |S3a. GENDER:|
|                                                                +----+-------+
|                                                                |Male| Female|
|                                                                +----+-------+
|                                                                |Mean|  Mean |
+----------------------------------------------------------------+----+-------+
|20. On how many of the thirty days in this typical month did you|   7|      5|
|have one or more alcoholic beverages to drink?                  |    |       |
+----------------------------------------------------------------+----+-------+

                                 Custom Tables
+----------------------------------------------------------------+------------+
|                                                                |S3a. GENDER:|
|                                                                +-----+------+
|                                                                | Male|Female|
|                                                                +-----+------+
|                                                                |Count| Count|
+----------------------------------------------------------------+-----+------+
|20. On how many of the thirty days in this typical month None   |  152|   258|
|did you have one or more alcoholic beverages to drink?   1      |  403|   653|
|                                                         2      |  284|   324|
|                                                         3      |  169|   215|
|                                                         4      |  178|   143|
|                                                         5      |  107|   106|
|                                                         6      |   67|    59|
|                                                         7      |   31|    11|
|                                                         8      |  101|    74|
|                                                         9      |    6|     4|
|                                                         10     |   95|    75|
|                                                         11     |    4|     0|
|                                                         12     |   58|    33|
|                                                         13     |    3|     2|
|                                                         14     |   13|     3|
|                                                         15     |   79|    58|
|                                                         16     |   10|     6|
|                                                         17     |    4|     2|
|                                                         18     |    5|     4|
|                                                         19     |    2|     0|
|                                                         20     |  105|    47|
|                                                         21     |    2|     0|
|                                                         22     |    3|     3|
|                                                         23     |    0|     3|
|                                                         24     |    3|     0|
|                                                         25     |   35|    25|
|                                                         26     |    1|     1|
|                                                         27     |    3|     3|
|                                                         28     |   13|     8|
|                                                         29     |    3|     3|
|                                                         Every  |  104|    43|
|                                                         day    |     |      |
+----------------------------------------------------------------+-----+------+
</screen>

</sect3>
</sect2>
<sect2 label="15.7.2" id="CTABLES-Data-Summarization">
<title>Data Summarization</title>

<para>The <literal>CTABLES</literal> command allows the user to control how the data are
summarized with <firstterm>summary specifications</firstterm>, syntax that lists one or
more summary function names, optionally separated by commas, and which
are enclosed in square brackets following a variable name on the
<literal>TABLE</literal> 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.
</para>
<para>The following example includes a summary specification for column and
row percentages for categorical variables, and mean and median for a
scalar variable:
</para>
<screen>CTABLES
    /TABLE=age [MEAN, MEDIAN] BY gender
    /TABLE=ageGroup [COLPCT, ROWPCT] BY gender.
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                    Custom Tables
+--------------------------+-----------------------+
|                          |      S3a. GENDER:     |
|                          +-----------+-----------+
|                          |    Male   |   Female  |
|                          +----+------+----+------+
|                          |Mean|Median|Mean|Median|
+--------------------------+----+------+----+------+
|D1. AGE: What is your age?|  46|    45|  50|    52|
+--------------------------+----+------+----+------+

                     Custom Tables
+-----------------------+-----------------------------+
|                       |         S3a. GENDER:        |
|                       +--------------+--------------+
|                       |     Male     |    Female    |
|                       +--------+-----+--------+-----+
|                       |Column %|Row %|Column %|Row %|
+-----------------------+--------+-----+--------+-----+
|Age group 15 or younger|     .0%|    .|     .0%|    .|
|          16 to 25     |   19.0%|54.0%|   13.1%|46.0%|
|          26 to 35     |   15.2%|49.2%|   12.7%|50.8%|
|          36 to 45     |   15.6%|47.2%|   14.2%|52.8%|
|          46 to 55     |   16.8%|44.8%|   16.8%|55.2%|
|          56 to 65     |   16.5%|41.4%|   18.9%|58.6%|
|          66 or older  |   17.0%|36.0%|   24.4%|64.0%|
+-----------------------+--------+-----+--------+-----+
</screen>
<para>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:
</para>
<screen>CTABLES /TABLE=ageGroup [COLPCT 'Gender %' PCT5.0,
                         ROWPCT 'Age Group %' PCT5.0]
               BY gender.
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                           Custom Tables
+-----------------------+-----------------------------------------+
|                       |               S3a. GENDER:              |
|                       +--------------------+--------------------+
|                       |        Male        |       Female       |
|                       +--------+-----------+--------+-----------+
|                       |Gender %|Age Group %|Gender %|Age Group %|
+-----------------------+--------+-----------+--------+-----------+
|Age group 15 or younger|      0%|          .|      0%|          .|
|          16 to 25     |     19%|        54%|     13%|        46%|
|          26 to 35     |     15%|        49%|     13%|        51%|
|          36 to 45     |     16%|        47%|     14%|        53%|
|          46 to 55     |     17%|        45%|     17%|        55%|
|          56 to 65     |     16%|        41%|     19%|        59%|
|          66 or older  |     17%|        36%|     24%|        64%|
+-----------------------+--------+-----------+--------+-----------+
</screen>
<para>In addition to the standard formats, <literal>CTABLES</literal> allows the user to
specify the following special formats:
</para>
<informaltable><tgroup cols="4"><colspec colwidth="11*"></colspec><colspec colwidth="36*"></colspec><colspec colwidth="8*"></colspec><colspec colwidth="9*"></colspec><tbody><row><entry><para><literal>NEGPAREN<emphasis>w</emphasis>.<emphasis>d</emphasis></literal>
</para></entry><entry><para>Encloses negative numbers in parentheses.
</para></entry><entry><para><literal>&amp;#160;<!-- /@w -->42.96</literal>
</para></entry><entry><para><literal>&amp;#160;<!-- /@w -->(42.96)</literal>
</para>
</entry></row><row><entry><para><literal>NEQUAL<emphasis>w</emphasis>.<emphasis>d</emphasis></literal>
</para></entry><entry><para>Adds a <literal>N=</literal> prefix.
</para></entry><entry><para><literal>&amp;#160;<!-- /@w -->N=42.96</literal>
</para></entry><entry><para><literal>&amp;#160;<!-- /@w -->N=-42.96</literal>
</para>
</entry></row><row><entry><para><literal><literal>PAREN<emphasis>w</emphasis>.<emphasis>d</emphasis></literal></literal>
</para></entry><entry><para>Encloses all numbers in parentheses.
</para></entry><entry><para><literal>&amp;#160;<!-- /@w -->(42.96)</literal>
</para></entry><entry><para><literal>&amp;#160;<!-- /@w -->(-42.96)</literal>
</para>
</entry></row><row><entry><para><literal>PCTPAREN<emphasis>w</emphasis>.<emphasis>d</emphasis></literal>
</para></entry><entry><para>Encloses all numbers in parentheses with a &#8216;<literal>%</literal>&#8217; suffix.
</para></entry><entry><para><literal>&amp;#160;<!-- /@w -->(42.96%)</literal>
</para></entry><entry><para><literal>(-42.96%)</literal>
</para></entry></row></tbody></tgroup></informaltable>
<para>Parentheses provide a shorthand to apply summary specifications to
multiple variables.  For example, both of these commands:
</para>
<screen>CTABLES /TABLE=ageGroup[COLPCT] + membersOver16[COLPCT] BY gender.
CTABLES /TABLE=(ageGroup + membersOver16)[COLPCT] BY gender.
</screen>
<para>produce the same output shown below:
</para>
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                                 Custom Tables
+-------------------------------------------------------------+---------------+
|                                                             |  S3a. GENDER: |
|                                                             +-------+-------+
|                                                             |  Male | Female|
|                                                             +-------+-------+
|                                                             | Column| Column|
|                                                             |   %   |   %   |
+-------------------------------------------------------------+-------+-------+
|Age group                                         15 or      |    .0%|    .0%|
|                                                  younger    |       |       |
|                                                  16 to 25   |  19.0%|  13.1%|
|                                                  26 to 35   |  15.2%|  12.7%|
|                                                  36 to 45   |  15.6%|  14.2%|
|                                                  46 to 55   |  16.8%|  16.8%|
|                                                  56 to 65   |  16.5%|  18.9%|
|                                                  66 or older|  17.0%|  24.4%|
+-------------------------------------------------------------+-------+-------+
|S1. Including yourself, how many members of this  None       |    .0%|    .0%|
|household are age 16 or older?                    1          |  21.4%|  35.0%|
|                                                  2          |  61.9%|  52.3%|
|                                                  3          |  11.0%|   8.2%|
|                                                  4          |   4.2%|   3.2%|
|                                                  5          |   1.1%|    .9%|
|                                                  6 or more  |    .4%|    .4%|
+-------------------------------------------------------------+-------+-------+
</screen>
<para>The following sections list the available summary functions.  After
each function&#8217;s name is given its default label and format.  If no
format is listed, then the default format is the print format for the
variable being summarized.
</para>
<sect3 label="15.7.2.1" id="CTABLES-Summary-Functions-for-Individual-Cells">
<title>Summary Functions for Individual Cells</title>

<para>This section lists the summary functions that consider only an
individual cell in <literal>CTABLES</literal>.  Only one such summary function,
<literal>COUNT</literal>, may be applied to both categorical and scale variables:
</para>
<variablelist><varlistentry><term><literal>COUNT</literal> (&#8220;Count&#8221;, F40.0)
</term><listitem><para>The sum of weights in a cell.
</para>
<para>If <literal>CATEGORIES</literal> for one or more of the variables in a table
include missing values (see <link linkend="CTABLES-Per_002dVariable-Category-Options">CTABLES Per-Variable Category
Options</link>), then some or all of the categories for a cell might be
missing values.  <literal>COUNT</literal> counts data included in a cell
regardless of whether its categories are missing.
</para></listitem></varlistentry></variablelist>
<para>The following summary functions apply only to scale variables or
totals and subtotals for categorical variables.  Be cautious about
interpreting the summary value in the latter case, because it is not
necessarily meaningful; however, the mean of a Likert scale, etc.
may have a straightforward interpreation.
</para>
<variablelist><varlistentry><term><literal>MAXIMUM</literal> (&#8220;Maximum&#8221;)
</term><listitem><para>The largest value.
</para>
</listitem></varlistentry><varlistentry><term><literal>MEAN</literal> (&#8220;Mean&#8221;)
</term><listitem><para>The mean.
</para>
</listitem></varlistentry><varlistentry><term><literal>MEDIAN</literal> (&#8220;Median&#8221;)
</term><listitem><para>The median value.
</para>
</listitem></varlistentry><varlistentry><term><literal>MINIMUM</literal> (&#8220;Minimum&#8221;)
</term><listitem><para>The smallest value.
</para>
</listitem></varlistentry><varlistentry><term><literal>MISSING</literal> (&#8220;Missing&#8221;)
</term><listitem><para>Sum of weights of user- and system-missing values.
</para>
</listitem></varlistentry><varlistentry><term><literal>MODE</literal> (&#8220;Mode&#8221;)
</term><listitem><para>The highest-frequency value.  Ties are broken by taking the smallest mode.
</para>
</listitem></varlistentry><varlistentry><term><literal>PTILE</literal> <emphasis>n</emphasis> (&#8220;Percentile <emphasis>n</emphasis>&#8221;)
</term><listitem><para>The <replaceable>n</replaceable>th percentile, where <inlineequation><mathphrase>0 &#8804; <replaceable>n</replaceable> &#8804; 100</mathphrase></inlineequation>.
</para>
</listitem></varlistentry><varlistentry><term><literal>RANGE</literal> (&#8220;Range&#8221;)
</term><listitem><para>The maximum minus the minimum.
</para>
</listitem></varlistentry><varlistentry><term><literal>SEMEAN</literal> (&#8220;Std Error of Mean&#8221;)
</term><listitem><para>The standard error of the mean.
</para>
</listitem></varlistentry><varlistentry><term><literal>STDDEV</literal> (&#8220;Std Deviation&#8221;)
</term><listitem><para>The standard deviation.
</para>
</listitem></varlistentry><varlistentry><term><literal>SUM</literal> (&#8220;Sum&#8221;)
</term><listitem><para>The sum.
</para>
</listitem></varlistentry><varlistentry><term><literal>TOTALN</literal> (&#8220;Total N&#8221;, F40.0)
</term><listitem><para>The sum of weights in a cell.
</para>
<para>For scale data, <literal>COUNT</literal> and <literal>TOTALN</literal> are the same.
</para>
<para>For categorical data, <literal>TOTALN</literal> counts missing values in excluded
categories, that is, user-missing values not in an explicit category
list on <literal>CATEGORIES</literal> (see <link linkend="CTABLES-Per_002dVariable-Category-Options">CTABLES Per-Variable Category
Options</link>), or user-missing values excluded because
<literal>MISSING=EXCLUDE</literal> is in effect on <literal>CATEGORIES</literal>, or
system-missing values.  <literal>COUNT</literal> does not count these.
</para>
<para>See <link linkend="CTABLES-Missing-Values-for-Summary-Variables">CTABLES Missing Values for Summary Variables</link>, for details of
how <literal>CTABLES</literal> summarizes missing values.
</para>
</listitem></varlistentry><varlistentry><term><literal>VALIDN</literal> (&#8220;Valid N&#8221;, F40.0)
</term><listitem><para>The sum of valid count weights in included categories.
</para>
<para>For categorical variables, <literal>VALIDN</literal> does not count missing values
regardless of whether they are in included categories via
<literal>CATEGORIES</literal>.  <literal>VALIDN</literal> does not count valid values that are
in excluded categories.  See <link linkend="CTABLES-Missing-Values-for-Summary-Variables">CTABLES Missing Values for Summary
Variables</link>, for details.
</para>
</listitem></varlistentry><varlistentry><term><literal>VARIANCE</literal> (&#8220;Variance&#8221;)
</term><listitem><para>The variance.
</para></listitem></varlistentry></variablelist>
</sect3>
<sect3 label="15.7.2.2" id="CTABLES-Summary-Functions-for-Groups-of-Cells">
<title>Summary Functions for Groups of Cells</title>

<para>These summary functions summarize over multiple cells within an area
of the output chosen by the user and specified as part of the function
name.  The following basic <replaceable>area</replaceable>s are supported, in decreasing
order of size:
</para>
<variablelist><varlistentry><term><literal>TABLE</literal>
</term><listitem><para>A <firstterm>section</firstterm>.  Stacked variables divide sections of the output from
each other.  sections may span multiple layers.
</para>
</listitem></varlistentry><varlistentry><term><literal>LAYER</literal>
</term><listitem><para>A section within a single layer.
</para>
</listitem></varlistentry><varlistentry><term><literal>SUBTABLE</literal>
</term><listitem><para>A <firstterm>subtable</firstterm>, whose contents are the cells that pair an innermost
row variable and an innermost column variable within a single layer.
</para></listitem></varlistentry></variablelist>
<para>The following shows how the output for the table expression
<literal>hasBeenPassengerOfDesignatedDriver &gt;
hasBeenPassengerOfDrunkDriver BY isLicensedDriver &gt;
hasHostedEventWithAlcohol + hasBeenDesignatedDriver BY
gender</literal><footnote><para>This is not necessarily a meaningful table.  To make
it easier to read, short variable labels are used.</para></footnote> is divided up into
<literal>TABLE</literal>, <literal>LAYER</literal>, and <literal>SUBTABLE</literal> areas.  Each unique
value for Table ID is one section, and similarly for Layer ID and
Subtable ID.  Thus, this output has two <literal>TABLE</literal> areas (one for
<literal>isLicensedDriver</literal> and one for <literal>hasBeenDesignatedDriver</literal>),
four <literal>LAYER</literal> areas (for those two variables, per layer), and 12
<literal>SUBTABLE</literal> areas.
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
</para><screen>                        Custom Tables
Male
+---------------------------------+-----------------+------+
|                                 |     licensed    |desDrv|
|                                 +--------+--------+---+--+
|                                 |   Yes  |   No   |   |  |
|                                 +--------+--------+   |  |
|                                 | hostAlc| hostAlc|   |  |
|                                 +----+---+----+---+   |  |
|                                 | Yes| No| Yes| No|Yes|No|
+---------------------------------+----+---+----+---+---+--+
|desPas Yes druPas Yes Table ID   |   1|  1|   1|  1|  2| 2|
|                      Layer ID   |   1|  1|   1|  1|  2| 2|
|                      Subtable ID|   1|  1|   2|  2|  3| 3|
|                 ----------------+----+---+----+---+---+--+
|                  No  Table ID   |   1|  1|   1|  1|  2| 2|
|                      Layer ID   |   1|  1|   1|  1|  2| 2|
|                      Subtable ID|   1|  1|   2|  2|  3| 3|
|      ---------------------------+----+---+----+---+---+--+
|       No  druPas Yes Table ID   |   1|  1|   1|  1|  2| 2|
|                      Layer ID   |   1|  1|   1|  1|  2| 2|
|                      Subtable ID|   4|  4|   5|  5|  6| 6|
|                 ----------------+----+---+----+---+---+--+
|                  No  Table ID   |   1|  1|   1|  1|  2| 2|
|                      Layer ID   |   1|  1|   1|  1|  2| 2|
|                      Subtable ID|   4|  4|   5|  5|  6| 6|
+---------------------------------+----+---+----+---+---+--+
</screen>
<para><literal>CTABLES</literal> also supports the following <replaceable>area</replaceable>s that further
divide a subtable or a layer within a section:
</para>
<variablelist><varlistentry><term><literal>LAYERROW</literal>
</term><term><literal>LAYERCOL</literal>
</term><listitem><para>A row or column, respectively, in one layer of a section.
</para>
</listitem></varlistentry><varlistentry><term><literal>ROW</literal>
</term><term><literal>COL</literal>
</term><listitem><para>A row or column, respectively, in a subtable.
</para></listitem></varlistentry></variablelist>
<para>The following summary functions for groups of cells are available for
each <replaceable>area</replaceable> described above, for both categorical and scale
variables:
</para>
<variablelist><varlistentry><term><literal><emphasis>area</emphasis>PCT</literal> or <literal><emphasis>area</emphasis>PCT.COUNT</literal> (&#8220;<emphasis>Area</emphasis> %&#8221;, PCT40.1)
</term><listitem><para>A percentage of total counts within <replaceable>area</replaceable>.
</para>
</listitem></varlistentry><varlistentry><term><literal><emphasis>area</emphasis>PCT.VALIDN</literal> (&#8220;<emphasis>Area</emphasis> Valid N %&#8221;, PCT40.1)
</term><listitem><para>A percentage of total counts for valid values within <replaceable>area</replaceable>.
</para>
</listitem></varlistentry><varlistentry><term><literal><emphasis>area</emphasis>PCT.TOTALN</literal> (&#8220;<emphasis>Area</emphasis> Total N %&#8221;, PCT40.1)
</term><listitem><para>A percentage of total counts for all values within <replaceable>area</replaceable>.
</para></listitem></varlistentry></variablelist>
<para>Scale variables and totals and subtotals for categorical variables may
use the following additional group cell summary function:
</para>
<variablelist><varlistentry><term><literal><emphasis>area</emphasis>PCT.SUM</literal> (&#8220;<emphasis>Area</emphasis> Sum %&#8221;, PCT40.1)
</term><listitem><para>Percentage of the sum of the values within <replaceable>area</replaceable>.
</para></listitem></varlistentry></variablelist>
</sect3>
<sect3 label="15.7.2.3" id="CTABLES-Summary-Functions-for-Adjusted-Weights">
<title>Summary Functions for Adjusted Weights</title>

<para>If the <literal>WEIGHT</literal> subcommand specified an effective weight variable
(see <link linkend="CTABLES-Effective-Weight">CTABLES Effective Weight</link>), then the following summary functions
use its value instead of the dictionary weight variable.  Otherwise,
they are equivalent to the summary function without the
&#8216;<literal>E</literal>&#8217;-prefix:
</para>
<itemizedlist><listitem><para><literal>ECOUNT</literal> (&#8220;Adjusted Count&#8221;, F40.0)
</para>
</listitem><listitem><para><literal>ETOTALN</literal> (&#8220;Adjusted Total N&#8221;, F40.0)
</para>
</listitem><listitem><para><literal>EVALIDN</literal> (&#8220;Adjusted Valid N&#8221;, F40.0)
</para></listitem></itemizedlist>
</sect3>
<sect3 label="15.7.2.4" id="CTABLES-Unweighted-Summary-Functions">
<title>Unweighted Summary Functions</title>

<para>The following summary functions with a &#8216;<literal>U</literal>&#8217;-prefix are equivalent
to the same ones without the prefix, except that they use unweighted
counts:
</para>
<itemizedlist><listitem><para><literal>UCOUNT</literal> (&#8220;Unweighted Count&#8221;, F40.0)
</para>
</listitem><listitem><para><literal>U<emphasis>area</emphasis>PCT</literal> or <literal>U<emphasis>area</emphasis>PCT.COUNT</literal> (&#8220;Unweighted <emphasis>Area</emphasis> %&#8221;, PCT40.1)
</para>
</listitem><listitem><para><literal>U<emphasis>area</emphasis>PCT.VALIDN</literal> (&#8220;Unweighted <emphasis>Area</emphasis> Valid N %&#8221;, PCT40.1)
</para>
</listitem><listitem><para><literal>U<emphasis>area</emphasis>PCT.TOTALN</literal> (&#8220;Unweighted <emphasis>Area</emphasis> Total N %&#8221;, PCT40.1)
</para>
</listitem><listitem><para><literal>UMEAN</literal> (&#8220;Unweighted Mean&#8221;)
</para>
</listitem><listitem><para><literal>UMEDIAN</literal> (&#8220;Unweighted Median&#8221;)
</para>
</listitem><listitem><para><literal>UMISSING</literal> (&#8220;Unweighted Missing&#8221;)
</para>
</listitem><listitem><para><literal>UMODE</literal> (&#8220;Unweighted Mode&#8221;)
</para>
</listitem><listitem><para><literal>U<emphasis>area</emphasis>PCT.SUM</literal> (&#8220;Unweighted <emphasis>Area</emphasis> Sum %&#8221;, PCT40.1)
</para>
</listitem><listitem><para><literal>UPTILE</literal> <emphasis>n</emphasis> (&#8220;Unweighted Percentile <emphasis>n</emphasis>&#8221;)
</para>
</listitem><listitem><para><literal>USEMEAN</literal> (&#8220;Unweighted Std Error of Mean&#8221;)
</para>
</listitem><listitem><para><literal>USTDDEV</literal> (&#8220;Unweighted Std Deviation&#8221;)
</para>
</listitem><listitem><para><literal>USUM</literal> (&#8220;Unweighted Sum&#8221;)
</para>
</listitem><listitem><para><literal>UTOTALN</literal> (&#8220;Unweighted Total N&#8221;, F40.0)
</para>
</listitem><listitem><para><literal>UVALIDN</literal> (&#8220;Unweighted Valid N&#8221;, F40.0)
</para>
</listitem><listitem><para><literal>UVARIANCE</literal> (&#8220;Unweighted Variance&#8221;, F40.0)
</para></listitem></itemizedlist>
</sect3>
</sect2>
<sect2 label="15.7.3" id="CTABLES-Statistics-Positions-and-Labels">
<title>Statistics Positions and Labels</title>

<literallayout><literal>/SLABELS</literal>
    [<literal>POSITION=</literal>{<literal>COLUMN</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>ROW</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>LAYER</literal>}]
    [<literal>VISIBLE=</literal>{<literal>YES</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>NO</literal>}]
</literallayout>
<para>The <literal>SLABELS</literal> subcommand controls the position and visibility of
summary statistics for the <literal>TABLE</literal> subcommand that it follows.
</para>
<para><literal>POSITION</literal> sets the axis on which summary statistics appear.
With <literal>POSITION=COLUMN</literal>, which is the default, each summary statistic
appears in a column.  For example:
</para>
<screen>CTABLES /TABLE=age [MEAN, MEDIAN] BY gender.
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                    Custom Tables
+--------------------------+-----------------------+
|                          |      S3a. GENDER:     |
|                          +-----------+-----------+
|                          |    Male   |   Female  |
|                          +----+------+----+------+
|                          |Mean|Median|Mean|Median|
+--------------------------+----+------+----+------+
|D1. AGE: What is your age?|  46|    45|  50|    52|
+--------------------------+----+------+----+------+
</screen>
<para>With <literal>POSITION=ROW</literal>, each summary statistic appears in a row, as
shown below:
</para>
<screen>CTABLES /TABLE=age [MEAN, MEDIAN] BY gender /SLABELS POSITION=ROW.
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                  Custom Tables
+---------------------------------+-------------+
|                                 | S3a. GENDER:|
|                                 +-----+-------+
|                                 | Male| Female|
+---------------------------------+-----+-------+
|D1. AGE: What is your age? Mean  |   46|     50|
|                           Median|   45|     52|
+---------------------------------+-----+-------+
</screen>
<para><literal>POSITION=LAYER</literal> is also available to place each summary statistic in
a separate layer.
</para>
<para>Labels for summary statistics are shown by default.  Use
<literal>VISIBLE=NO</literal> to suppress them.  Because unlabeled data can cause
confusion, it should only be considered if the meaning of the data is
evident, as in a simple case like this:
</para>
<screen>CTABLES /TABLE=ageGroup [TABLEPCT] /SLABELS VISIBLE=NO.
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>         Custom Tables
+-----------------------+-----+
|Age group 15 or younger|  .0%|
|          16 to 25     |15.7%|
|          26 to 35     |13.8%|
|          36 to 45     |14.8%|
|          46 to 55     |16.8%|
|          56 to 65     |17.8%|
|          66 or older  |21.1%|
+-----------------------+-----+
</screen>
</sect2>
<sect2 label="15.7.4" id="CTABLES-Category-Label-Positions">
<title>Category Label Positions</title>

<literallayout><literal>/CLABELS</literal> {<literal>AUTO</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> {<literal>ROWLABELS</literal><inlineequation><mathphrase>|</mathphrase></inlineequation><literal>COLLABELS</literal>}<literal>=</literal>{<literal>OPPOSITE</literal><inlineequation><mathphrase>|</mathphrase></inlineequation><literal>LAYER</literal>}}
</literallayout>
<para>The <literal>CLABELS</literal> subcommand controls the position of category labels
for the <literal>TABLE</literal> subcommand that it follows.  By default, or if
<literal>AUTO</literal> is specified, category labels for a given variable nest
inside the variable&#8217;s label on the same axis.  For example, the
command below results in age categories nesting within the age group
variable on the rows axis and gender categories within the gender
variable on the columns axis:
</para>
<screen>CTABLES /TABLE ageGroup BY gender.
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>             Custom Tables
+-----------------------+------------+
|                       |S3a. GENDER:|
|                       +-----+------+
|                       | Male|Female|
|                       +-----+------+
|                       |Count| Count|
+-----------------------+-----+------+
|Age group 15 or younger|    0|     0|
|          16 to 25     |  594|   505|
|          26 to 35     |  476|   491|
|          36 to 45     |  489|   548|
|          46 to 55     |  526|   649|
|          56 to 65     |  516|   731|
|          66 or older  |  531|   943|
+-----------------------+-----+------+
</screen>
<para><literal>ROWLABELS=OPPOSITE</literal> or <literal>COLLABELS=OPPOSITE</literal> move row or column
variable category labels, respectively, to the opposite axis.  The
setting affects only the innermost variable or variables, which must
be categorical, on the given axis.  For example:
</para>
<screen>CTABLES /TABLE ageGroup BY gender /CLABELS ROWLABELS=OPPOSITE.
CTABLES /TABLE ageGroup BY gender /CLABELS COLLABELS=OPPOSITE.
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                                Custom Tables
+-----+----------------------------------------------------------------------
|     |                                      S3a. GENDER:
|     +-------------------------------------------+--------------------------
|     |                    Male                   |                   Female
|     +-------+-----+-----+-----+-----+-----+-----+-------+-----+-----+-----+
|     | 15 or |16 to|26 to|36 to|46 to|56 to|66 or| 15 or |16 to|26 to|36 to|
|     |younger|  25 |  35 |  45 |  55 |  65 |older|younger|  25 |  35 |  45 |
|     +-------+-----+-----+-----+-----+-----+-----+-------+-----+-----+-----+
|     | Count |Count|Count|Count|Count|Count|Count| Count |Count|Count|Count|
+-----+-------+-----+-----+-----+-----+-----+-----+-------+-----+-----+-----+
|Age  |      0|  594|  476|  489|  526|  516|  531|      0|  505|  491|  548|
|group|       |     |     |     |     |     |     |       |     |     |     |
+-----+-------+-----+-----+-----+-----+-----+-----+-------+-----+-----+-----+

+-----+-----------------+
|     |                 |
|     +-----------------+
|     |                 |
|     +-----+-----+-----+
|     |46 to|56 to|66 or|
|     |  55 |  65 |older|
|     +-----+-----+-----+
|     |Count|Count|Count|
+-----+-----+-----+-----+
|Age  |  649|  731|  943|
|group|     |     |     |
+-----+-----+-----+-----+

                Custom Tables
+------------------------------+------------+
|                              |S3a. GENDER:|
|                              +------------+
|                              |    Count   |
+------------------------------+------------+
|Age group 15 or younger Male  |           0|
|                        Female|           0|
|         ---------------------+------------+
|          16 to 25      Male  |         594|
|                        Female|         505|
|         ---------------------+------------+
|          26 to 35      Male  |         476|
|                        Female|         491|
|         ---------------------+------------+
|          36 to 45      Male  |         489|
|                        Female|         548|
|         ---------------------+------------+
|          46 to 55      Male  |         526|
|                        Female|         649|
|         ---------------------+------------+
|          56 to 65      Male  |         516|
|                        Female|         731|
|         ---------------------+------------+
|          66 or older   Male  |         531|
|                        Female|         943|
+------------------------------+------------+
</screen>
<para><literal>ROWLABELS=LAYER</literal> or <literal>COLLABELS=LAYER</literal> move the innermost row or
column variable category labels, respectively, to the layer axis.
</para>
<para>Only one axis&#8217;s labels may be moved, whether to the opposite axis or
to the layer axis.
</para>
<bridgehead renderas="sect3">Effect on Summary Statistics</bridgehead>

<para><literal>CLABELS</literal> primarily affects the appearance of tables, not the
data displayed in them.  However, <literal>CTABLES</literal> can affect the values
displayed for statistics that summarize areas of a table, since it can
change the definitions of these areas.
</para>
<para>For example, consider the following syntax and output:
</para>
<screen>CTABLES /TABLE ageGroup BY gender [ROWPCT, COLPCT].
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                     Custom Tables
+-----------------------+-----------------------------+
|                       |         S3a. GENDER:        |
|                       +--------------+--------------+
|                       |     Male     |    Female    |
|                       +-----+--------+-----+--------+
|                       |Row %|Column %|Row %|Column %|
+-----------------------+-----+--------+-----+--------+
|Age group 15 or younger|    .|     .0%|    .|     .0%|
|          16 to 25     |54.0%|   19.0%|46.0%|   13.1%|
|          26 to 35     |49.2%|   15.2%|50.8%|   12.7%|
|          36 to 45     |47.2%|   15.6%|52.8%|   14.2%|
|          46 to 55     |44.8%|   16.8%|55.2%|   16.8%|
|          56 to 65     |41.4%|   16.5%|58.6%|   18.9%|
|          66 or older  |36.0%|   17.0%|64.0%|   24.4%|
+-----------------------+-----+--------+-----+--------+
</screen>
<para>Using <literal>COLLABELS=OPPOSITE</literal> changes the definitions of rows and
columns, so that column percentages display what were previously row
percentages and the new row percentages become meaningless (because
there is only one cell per row):
</para>
<screen>CTABLES
    /TABLE ageGroup BY gender [ROWPCT, COLPCT]
    /CLABELS COLLABELS=OPPOSITE.
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                  Custom Tables
+------------------------------+---------------+
|                              |  S3a. GENDER: |
|                              +------+--------+
|                              | Row %|Column %|
+------------------------------+------+--------+
|Age group 15 or younger Male  |     .|       .|
|                        Female|     .|       .|
|         ---------------------+------+--------+
|          16 to 25      Male  |100.0%|   54.0%|
|                        Female|100.0%|   46.0%|
|         ---------------------+------+--------+
|          26 to 35      Male  |100.0%|   49.2%|
|                        Female|100.0%|   50.8%|
|         ---------------------+------+--------+
|          36 to 45      Male  |100.0%|   47.2%|
|                        Female|100.0%|   52.8%|
|         ---------------------+------+--------+
|          46 to 55      Male  |100.0%|   44.8%|
|                        Female|100.0%|   55.2%|
|         ---------------------+------+--------+
|          56 to 65      Male  |100.0%|   41.4%|
|                        Female|100.0%|   58.6%|
|         ---------------------+------+--------+
|          66 or older   Male  |100.0%|   36.0%|
|                        Female|100.0%|   64.0%|
+------------------------------+------+--------+
</screen>
<bridgehead renderas="sect3">Moving Categories for Stacked Variables</bridgehead>

<para>If <literal>CLABELS</literal> moves category labels from an axis with stacked
variables, the variables that are moved must have the same category
specifications (see <link linkend="CTABLES-Per_002dVariable-Category-Options">CTABLES Per-Variable Category Options</link>) and the
same value labels.
</para>
<para>The following shows both moving stacked category variables and
adapting to the changing definitions of rows and columns:
</para>
<screen>CTABLES /TABLE (likelihoodOfBeingStoppedByPolice
                + likelihoodOfHavingAnAccident) [COLPCT].
CTABLES /TABLE (likelihoodOfBeingStoppedByPolice
                + likelihoodOfHavingAnAccident) [ROWPCT]
  /CLABELS ROW=OPPOSITE.
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                                 Custom Tables
+---------------------------------------------------------------------+-------+
|                                                                     | Column|
|                                                                     |   %   |
+---------------------------------------------------------------------+-------+
|105b. How likely is it that drivers who have had too     Almost      |  10.2%|
|much to drink to drive safely will A. Get stopped by the certain     |       |
|police?                                                  Very likely |  21.8%|
|                                                         Somewhat    |  40.2%|
|                                                         likely      |       |
|                                                         Somewhat    |  19.0%|
|                                                         unlikely    |       |
|                                                         Very        |   8.9%|
|                                                         unlikely    |       |
+---------------------------------------------------------------------+-------+
|105b. How likely is it that drivers who have had too     Almost      |  15.9%|
|much to drink to drive safely will B. Have an accident?  certain     |       |
|                                                         Very likely |  40.8%|
|                                                         Somewhat    |  35.0%|
|                                                         likely      |       |
|                                                         Somewhat    |   6.2%|
|                                                         unlikely    |       |
|                                                         Very        |   2.0%|
|                                                         unlikely    |       |
+---------------------------------------------------------------------+-------+

                                 Custom Tables
+-----------------------------+--------+-------+---------+----------+---------+
|                             | Almost |  Very | Somewhat| Somewhat |   Very  |
|                             | certain| likely|  likely | unlikely | unlikely|
|                             +--------+-------+---------+----------+---------+
|                             |  Row % | Row % |  Row %  |   Row %  |  Row %  |
+-----------------------------+--------+-------+---------+----------+---------+
|105b. How likely is it that  |   10.2%|  21.8%|    40.2%|     19.0%|     8.9%|
|drivers who have had too much|        |       |         |          |         |
|to drink to drive safely will|        |       |         |          |         |
|A. Get stopped by the police?|        |       |         |          |         |
|105b. How likely is it that  |   15.9%|  40.8%|    35.0%|      6.2%|     2.0%|
|drivers who have had too much|        |       |         |          |         |
|to drink to drive safely will|        |       |         |          |         |
|B. Have an accident?         |        |       |         |          |         |
+-----------------------------+--------+-------+---------+----------+---------+
</screen>
</sect2>
<sect2 label="15.7.5" id="CTABLES-Per_002dVariable-Category-Options">
<title>Per-Variable Category Options</title>

<literallayout><literal>/CATEGORIES</literal> <literal>VARIABLES=</literal><emphasis>variables</emphasis>
    {<literal>[</literal><emphasis>value</emphasis><literal>,</literal> <emphasis>value</emphasis>&#8230;<literal>]</literal>
   <inlineequation><mathphrase>|</mathphrase></inlineequation> [<literal>ORDER=</literal>{<literal>A</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>D</literal>}]
     [<literal>KEY=</literal>{<literal>VALUE</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>LABEL</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <emphasis>summary</emphasis><literal>(</literal><emphasis>variable</emphasis><literal>)</literal>}]
     [<literal>MISSING=</literal>{<literal>EXCLUDE</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>INCLUDE</literal>}]}
    [<literal>TOTAL=</literal>{<literal>NO</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>YES</literal>} [<literal>LABEL=</literal><emphasis>string</emphasis>] [<literal>POSITION=</literal>{<literal>AFTER</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>BEFORE</literal>}]]
    [<literal>EMPTY=</literal>{<literal>INCLUDE</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>EXCLUDE</literal>}]
</literallayout>
<para>The <literal>CATEGORIES</literal> subcommand specifies, for one or more
categorical variables, the categories to include and exclude, the sort
order for included categories, and treatment of missing values.  It
also controls the totals and subtotals to display.  It may be
specified any number of times, each time for a different set of
variables.  <literal>CATEGORIES</literal> applies to the table produced by the
<literal>TABLE</literal> subcommand that it follows.
</para>
<para><literal>CATEGORIES</literal> does not apply to scalar variables.
</para>
<para><literal>VARIABLES</literal> is required and must list the variables for the subcommand
to affect.
</para>
<para>The syntax may specify the categories to include and their sort order
either explicitly or implicitly.  The following sections give the
details of each form of syntax, followed by information on totals and
subtotals and the <literal>EMPTY</literal> setting.
</para>
<sect3 label="15.7.5.1" id="CTABLES-Explicit-Categories">
<title>Explicit Categories</title>

<anchor id="CTABLES-Explicit-Category-List"/>
<para>To use <literal>CTABLES</literal> to explicitly specify categories to include,
list the categories within square brackets in the desired sort order.
Use spaces or commas to separate values.  Categories not covered by
the list are excluded from analysis.
</para>
<para>Each element of the list takes one of the following forms:
</para>
<variablelist><varlistentry><term><literal><emphasis>number</emphasis></literal>
</term><term><literal>'<emphasis>string</emphasis>'</literal>
</term><listitem><para>A numeric or string category value, for variables that have the
corresponding type.
</para>
</listitem></varlistentry><varlistentry><term><literal>'<emphasis>date</emphasis>'</literal>
</term><term><literal>'<emphasis>time</emphasis>'</literal>
</term><listitem><para>A date or time category value, for variables that have a date or time
print format.
</para>
</listitem></varlistentry><varlistentry><term><literal><emphasis>min</emphasis> THRU <emphasis>max</emphasis></literal>
</term><term><literal>LO THRU <emphasis>max</emphasis></literal>
</term><term><literal><emphasis>min</emphasis> THRU HI</literal>
</term><listitem><para>A range of category values, where <replaceable>min</replaceable> and <replaceable>max</replaceable> each takes
one of the forms above, in increasing order.
</para>
</listitem></varlistentry><varlistentry><term><literal>MISSING</literal>
</term><listitem><para>All user-missing values.  (To match individual user-missing values,
specify their category values.)
</para>
</listitem></varlistentry><varlistentry><term><literal>OTHERNM</literal>
</term><listitem><para>Any non-missing value not covered by any other element of the list
(regardless of where <literal>OTHERNM</literal> is placed in the list).
</para>
</listitem></varlistentry><varlistentry><term><literal>&amp;<emphasis>postcompute</emphasis></literal>
</term><listitem><para>A computed category name (see <link linkend="CTABLES-Computed-Categories">CTABLES Computed Categories</link>).
</para>
</listitem></varlistentry><varlistentry><term><literal>SUBTOTAL</literal>
</term><term><literal>HSUBTOTAL</literal>
</term><listitem><para>A subtotal (see <link linkend="CTABLES-Totals-and-Subtotals">CTABLES Totals and Subtotals</link>).
</para></listitem></varlistentry></variablelist>
<para>If multiple elements of the list cover a given category, the last one
in the list takes precedence.
</para>
<para>The following example syntax and output show how an explicit category
can limit the displayed categories:
</para>
<screen>CTABLES /TABLE freqOfDriving.
CTABLES /TABLE freqOfDriving /CATEGORIES VARIABLES=freqOfDriving [1, 2, 3].
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                                 Custom Tables
+-----------------------------------------------------------------------+-----+
|                                                                       |Count|
+-----------------------------------------------------------------------+-----+
| 1. How often do you usually drive a car or other  Every day           | 4667|
|motor vehicle?                                     Several days a week | 1274|
|                                                   Once a week or less |  361|
|                                                   Only certain times a|  130|
|                                                   year                |     |
|                                                   Never               |  540|
+-----------------------------------------------------------------------+-----+

                                 Custom Tables
+-----------------------------------------------------------------------+-----+
|                                                                       |Count|
+-----------------------------------------------------------------------+-----+
| 1. How often do you usually drive a car or other     Every day        | 4667|
|motor vehicle?                                        Several days a   | 1274|
|                                                      week             |     |
|                                                      Once a week or   |  361|
|                                                      less             |     |
+-----------------------------------------------------------------------+-----+
</screen>
</sect3>
<sect3 label="15.7.5.2" id="CTABLES-Implicit-Categories">
<title>Implicit Categories</title>

<para>In the absence of an explicit list of categories, <literal>CATEGORIES</literal>
allows <literal>KEY</literal>, <literal>ORDER</literal>, and <literal>MISSING</literal> to specify how to
select and sort categories.
</para>
<para>The <literal>KEY</literal> setting specifies the sort key.  By default, or with
<literal>KEY=VALUE</literal>, categories are sorted by default.  Categories may
also be sorted by value label, with <literal>KEY=LABEL</literal>, or by the value
of a summary function, e.g. <literal>KEY=COUNT</literal>.
</para>
<para>By default, or with <literal>ORDER=A</literal>, categories are sorted in ascending
order.  Specify <literal>ORDER=D</literal> to sort in descending order.
</para>
<para>User-missing values are excluded by default, or with
<literal>MISSING=EXCLUDE</literal>.  Specify <literal>MISSING=INCLUDE</literal> to include
user-missing values.  The system-missing value is always excluded.
</para>
<para>The following example syntax and output show how
<literal>MISSING=INCLUDE</literal> causes missing values to be included in a
category list.
</para>
<screen>CTABLES /TABLE freqOfDriving.
CTABLES /TABLE freqOfDriving
        /CATEGORIES VARIABLES=freqOfDriving MISSING=INCLUDE.
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                                 Custom Tables
+-----------------------------------------------------------------------+-----+
|                                                                       |Count|
+-----------------------------------------------------------------------+-----+
| 1. How often do you usually drive a car or other  Every day           | 4667|
|motor vehicle?                                     Several days a week | 1274|
|                                                   Once a week or less |  361|
|                                                   Only certain times a|  130|
|                                                   year                |     |
|                                                   Never               |  540|
+-----------------------------------------------------------------------+-----+

                                 Custom Tables
+-----------------------------------------------------------------------+-----+
|                                                                       |Count|
+-----------------------------------------------------------------------+-----+
| 1. How often do you usually drive a car or other  Every day           | 4667|
|motor vehicle?                                     Several days a week | 1274|
|                                                   Once a week or less |  361|
|                                                   Only certain times a|  130|
|                                                   year                |     |
|                                                   Never               |  540|
|                                                   Don't know          |    8|
|                                                   Refused             |   19|
+-----------------------------------------------------------------------+-----+
</screen>
</sect3>
<sect3 label="15.7.5.3" id="CTABLES-Totals-and-Subtotals">
<title>Totals and Subtotals</title>

<para><literal>CATEGORIES</literal> also controls display of totals and subtotals.  By
default, or with <literal>TOTAL=NO</literal>, totals are not displayed.  Use
<literal>TOTAL=YES</literal> to display a total.  By default, the total is labeled
&#8220;Total&#8221;; use <literal>LABEL=&quot;<emphasis>label</emphasis>&quot;</literal> to override it.
</para>
<para>Subtotals are also not displayed by default.  To add one or more
subtotals, use an explicit category list and insert <literal>SUBTOTAL</literal> or
<literal>HSUBTOTAL</literal> in the position or positions where the subtotal
should appear.  The subtotal becomes an extra row or column or layer.
<literal>HSUBTOTAL</literal> additionally hides the categories that make up the
subtotal.  Either way, the default label is &#8220;Subtotal&#8221;, use
<literal>SUBTOTAL=&quot;<emphasis>label</emphasis>&quot;</literal> or <literal>HSUBTOTAL=&quot;<emphasis>label</emphasis>&quot;</literal> to specify
a custom label.
</para>
<para>The following example syntax and output show how to use
<literal>TOTAL=YES</literal> and <literal>SUBTOTAL</literal>:
</para>
<screen>CTABLES
    /TABLE freqOfDriving
    /CATEGORIES VARIABLES=freqOfDriving [OTHERNM, SUBTOTAL='Valid Total',
                                         MISSING, SUBTOTAL='Missing Total']
                                        TOTAL=YES LABEL='Overall Total'.
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                                 Custom Tables
+-----------------------------------------------------------------------+-----+
|                                                                       |Count|
+-----------------------------------------------------------------------+-----+
| 1. How often do you usually drive a car or other  Every day           | 4667|
|motor vehicle?                                     Several days a week | 1274|
|                                                   Once a week or less |  361|
|                                                   Only certain times a|  130|
|                                                   year                |     |
|                                                   Never               |  540|
|                                                   Valid Total         | 6972|
|                                                   Don't know          |    8|
|                                                   Refused             |   19|
|                                                   Missing Total       |   27|
|                                                   Overall Total       | 6999|
+-----------------------------------------------------------------------+-----+
</screen>
<para>By default, or with <literal>POSITION=AFTER</literal>, totals are displayed in the
output after the last category and subtotals apply to categories that
precede them.  With <literal>POSITION=BEFORE</literal>, totals come before the
first category and subtotals apply to categories that follow them.
</para>
<para>Only categorical variables may have totals and subtotals.  Scalar
variables may be &#8220;totaled&#8221; indirectly by enabling totals and
subtotals on a categorical variable within which the scalar variable
is summarized.  For example, the following syntax produces a mean,
count, and valid count across all data by adding a total on the
categorical <literal>region</literal> variable, as shown:
</para>
<screen>CTABLES /TABLE=region &gt; monthDaysMin1drink [MEAN, VALIDN]
    /CATEGORIES VARIABLES=region TOTAL=YES LABEL='All regions'.
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                                 Custom Tables
+-----------------------------------------------------------+----+-----+------+
|                                                           |    |     | Valid|
|                                                           |Mean|Count|   N  |
+-----------------------------------------------------------+----+-----+------+
|20. On how many of the thirty days in this  Region NE      | 5.6| 1409|   945|
|typical month did you have one or more             MW      | 5.0| 1654|  1026|
|alcoholic beverages to drink?                      S       | 6.0| 2390|  1285|
|                                                   W       | 6.5| 1546|   953|
|                                                   All     | 5.8| 6999|  4209|
|                                                   regions |    |     |      |
+-----------------------------------------------------------+----+-----+------+
</screen>
<para>By default, PSPP uses the same summary functions for totals and
subtotals as other categories.  To summarize totals and subtotals
differently, specify the summary functions for totals and subtotals
after the ordinary summary functions inside a nested set of <literal>[]</literal>
following <literal>TOTALS</literal>.  For example, the following syntax displays
<literal>COUNT</literal> for individual categories and totals and <literal>VALIDN</literal>
for totals, as shown:
</para>
<screen>CTABLES
    /TABLE isLicensedDriver [COUNT, TOTALS[COUNT, VALIDN]]
    /CATEGORIES VARIABLES=isLicensedDriver TOTAL=YES MISSING=INCLUDE.
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                                 Custom Tables
+----------------------------------------------------------------+-----+------+
|                                                                |     | Valid|
|                                                                |Count|   N  |
+----------------------------------------------------------------+-----+------+
|D7a. Are you a licensed driver; that is, do you have a Yes      | 6379|      |
|valid driver's license?                                No       |  572|      |
|                                                       Don't    |    4|      |
|                                                       know     |     |      |
|                                                       Refused  |   44|      |
|                                                       Total    | 6999|  6951|
+----------------------------------------------------------------+-----+------+
</screen>
</sect3>
<sect3 label="15.7.5.4" id="CTABLES-Categories-Without-Values">
<title>Categories Without Values</title>

<para>Some categories might not be included in the data set being analyzed.
For example, our example data set has no cases in the &#8220;15 or
younger&#8221; age group.  By default, or with <literal>EMPTY=INCLUDE</literal>,
PSPP includes these empty categories in output tables.  To exclude
them, specify <literal>EMPTY=EXCLUDE</literal>.
</para>
<para>For implicit categories, empty categories potentially include all the
values with value labels for a given variable; for explicit
categories, they include all the values listed individually and all
values with value labels that are covered by ranges or <literal>MISSING</literal>
or <literal>OTHERNM</literal>.
</para>
<para>The following example syntax and output show the effect of
<literal>EMPTY=EXCLUDE</literal> for the <literal>membersOver16</literal> variable, in which 0
is labeled &#8220;None&#8221; but no cases exist with that value:
</para>
<screen>CTABLES /TABLE=membersOver16.
CTABLES /TABLE=membersOver16 /CATEGORIES VARIABLES=membersOver16 EMPTY=EXCLUDE.
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                                 Custom Tables
+-----------------------------------------------------------------------+-----+
|                                                                       |Count|
+-----------------------------------------------------------------------+-----+
|S1. Including yourself, how many members of this household are None    |    0|
|age 16 or older?                                               1       | 1586|
|                                                               2       | 3031|
|                                                               3       |  505|
|                                                               4       |  194|
|                                                               5       |   55|
|                                                               6 or    |   21|
|                                                               more    |     |
+-----------------------------------------------------------------------+-----+

                                 Custom Tables
+-----------------------------------------------------------------------+-----+
|                                                                       |Count|
+-----------------------------------------------------------------------+-----+
|S1. Including yourself, how many members of this household are 1       | 1586|
|age 16 or older?                                               2       | 3031|
|                                                               3       |  505|
|                                                               4       |  194|
|                                                               5       |   55|
|                                                               6 or    |   21|
|                                                               more    |     |
+-----------------------------------------------------------------------+-----+
</screen>
</sect3>
</sect2>
<sect2 label="15.7.6" id="CTABLES-Titles">
<title>Titles</title>

<literallayout><literal>/TITLES</literal>
    [<literal>TITLE=</literal><emphasis>string</emphasis>&#8230;]
    [<literal>CAPTION=</literal><emphasis>string</emphasis>&#8230;]
    [<literal>CORNER=</literal><emphasis>string</emphasis>&#8230;]
</literallayout>
<para>The <literal>TITLES</literal> subcommand sets the title, caption, and corner text
for the table output for the previous <literal>TABLE</literal> subcommand.  Any
number of strings may be specified for each kind of text, with each
string appearing on a separate line in the output.  The title appears
above the table, the caption below the table, and the corner text
appears in the table&#8217;s upper left corner.  By default, the title is
&#8220;Custom Tables&#8221; and the caption and corner text are empty.  With
some table output styles, the corner text is not displayed.
</para>
<para>The strings provided in this subcommand may contain the following
macro-like keywords that PSPP substitutes at the time that it runs
the command:
</para>
<variablelist><varlistentry><term><literal>)DATE</literal>
</term><listitem><para>The current date, e.g. MM/DD/YY.  The format is locale-dependent.
</para>
<!-- ( -->
</listitem></varlistentry><varlistentry><term><literal>)TIME</literal>
</term><listitem><para>The current time, e.g. HH:MM:SS.  The format is locale-dependent.
</para>
<!-- ( -->
</listitem></varlistentry><varlistentry><term><literal>)TABLE</literal>
</term><listitem><para>The expression specified on the <literal>TABLE</literal> command.  Summary
and measurement level specifications are omitted, and variable labels are used in place of variable names.
</para></listitem></varlistentry></variablelist>
</sect2>
<sect2 label="15.7.7" id="CTABLES-Table-Formatting">
<title>Table Formatting</title>

<literallayout><literal>/FORMAT</literal>
    [<literal>MINCOLWIDTH=</literal>{<literal>DEFAULT</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <emphasis>width</emphasis>}]
    [<literal>MAXCOLWIDTH=</literal>{<literal>DEFAULT</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <emphasis>width</emphasis>}]
    [<literal>UNITS=</literal>{<literal>POINTS</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>INCHES</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>CM</literal>}]
    [<literal>EMPTY=</literal>{<literal>ZERO</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>BLANK</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <emphasis>string</emphasis>}]
    [<literal>MISSING=</literal><emphasis>string</emphasis>]
</literallayout>
<para>The <literal>FORMAT</literal> subcommand, which must precede the first
<literal>TABLE</literal> subcommand, controls formatting for all the output
tables.  <literal>FORMAT</literal> and all of its settings are optional.
</para>
<para>Use <literal>MINCOLWIDTH</literal> and <literal>MAXCOLWIDTH</literal> to control the minimum
or maximum width of columns in output tables.  By default, with
<literal>DEFAULT</literal>, column width varies based on content.  Otherwise,
specify a number for either or both of these settings.  If both are
specified, <literal>MAXCOLWIDTH</literal> must be greater than or equal to
<literal>MINCOLWIDTH</literal>.  The default unit, or with <literal>UNITS=POINTS</literal>, is
points (1/72 inch), or specify <literal>UNITS=INCHES</literal> to use inches or
<literal>UNITS=CM</literal> for centimeters.  PSPP does not currently honor any
of these settings.
</para>
<para>By default, or with <literal>EMPTY=ZERO</literal>, zero values are displayed in
their usual format.  Use <literal>EMPTY=BLANK</literal> to use an empty cell
instead, or <literal>EMPTY=&quot;<emphasis>string</emphasis>&quot;</literal> to use the specified string.
</para>
<para>By default, missing values are displayed as &#8216;<literal>.</literal>&#8217;, the same as in
other tables.  Specify <literal>MISSING=&quot;<emphasis>string</emphasis>&quot;</literal> to instead use a
custom string.
</para>
</sect2>
<sect2 label="15.7.8" id="CTABLES-Display-of-Variable-Labels">
<title>Display of Variable Labels</title>

<literallayout><literal>/VLABELS</literal>
    <literal>VARIABLES=</literal><emphasis>variables</emphasis>
    <literal>DISPLAY</literal>={<literal>DEFAULT</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>NAME</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>LABEL</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>BOTH</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>NONE</literal>}
</literallayout>
<para>The <literal>VLABELS</literal> subcommand, which must precede the first
<literal>TABLE</literal> subcommand, controls display of variable labels in all
the output tables.  <literal>VLABELS</literal> is optional.  It may appear
multiple times to adjust settings for different variables.
</para>
<para><literal>VARIABLES</literal> and <literal>DISPLAY</literal> are required.  The value of
<literal>DISPLAY</literal> controls how variable labels are displayed for the
variables listed on <literal>VARIABLES</literal>.  The supported values are:
</para>
<variablelist><varlistentry><term><literal>DEFAULT</literal>
</term><listitem><para>Use the setting from <literal>SET TVARS</literal> (see <link linkend="SET-TVARS">SET TVARS</link>).
</para>
</listitem></varlistentry><varlistentry><term><literal>NAME</literal>
</term><listitem><para>Show only a variable name.
</para>
</listitem></varlistentry><varlistentry><term><literal>LABEL</literal>
</term><listitem><para>Show only a variable label.
</para>
</listitem></varlistentry><varlistentry><term><literal>BOTH</literal>
</term><listitem><para>Show variable name and label.
</para>
</listitem></varlistentry><varlistentry><term><literal>NONE</literal>
</term><listitem><para>Show nothing.
</para></listitem></varlistentry></variablelist>
</sect2>
<sect2 label="15.7.9" id="CTABLES-Missing-Value-Treatment">
<title>Missing Value Treatment</title>

<para>The <literal>TABLE</literal> subcommand on <literal>CTABLES</literal> specifies two different
kinds of variables: variables that divide tables into cells (which are
always categorical) and variables being summarized (which may be
categorical or scale).  PSPP treats missing values differently in
each kind of variable, as described in the sections below.
</para>
<sect3 label="15.7.9.1" id="CTABLES-Missing-Values-for-Cell_002dDefining-Variables">
<title>Missing Values for Cell-Defining Variables</title>

<para>For variables that divide tables into cells, per-variable category
options, as described in <link linkend="CTABLES-Per_002dVariable-Category-Options">CTABLES Per-Variable Category Options</link>,
determine which data is analyzed.  If any of the categories for such a
variable would exclude a case, then that case is not included.
</para>
<para>As an example, consider the following entirely artificial dataset, in
which &#8216;<literal>x</literal>&#8217; and &#8216;<literal>y</literal>&#8217; are categorical variables with missing
value 9, and &#8216;<literal>z</literal>&#8217; is scale:
</para>
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>   Data List
+-+-+---------+
|x|y|    z    |
+-+-+---------+
|1|1|        1|
|1|2|       10|
|1|9|      100|
|2|1|     1000|
|2|2|    10000|
|2|9|   100000|
|9|1|  1000000|
|9|2| 10000000|
|9|9|100000000|
+-+-+---------+
</screen>
<para>Using &#8216;<literal>x</literal>&#8217; and &#8216;<literal>y</literal>&#8217; to define cells, and summarizing &#8216;<literal>z</literal>&#8217;,
by default PSPP omits all the cases that have &#8216;<literal>x</literal>&#8217; or &#8216;<literal>y</literal>&#8217; (or both)
missing:
</para>
<screen>CTABLES /TABLE x &gt; y &gt; z [SUM].
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>  Custom Tables
+---------+-----+
|         | Sum |
+---------+-----+
|x 1 y 1 z|    1|
|     ----+-----+
|      2 z|   10|
| --------+-----+
|  2 y 1 z| 1000|
|     ----+-----+
|      2 z|10000|
+---------+-----+
</screen>
<para>If, however, we add <literal>CATEGORIES</literal> specifications to include
missing values for &#8216;<literal>y</literal>&#8217; or for &#8216;<literal>x</literal>&#8217; and &#8216;<literal>y</literal>&#8217;, the output
table includes them, like so:
</para>
<screen>CTABLES /TABLE x &gt; y &gt; z [SUM] /CATEGORIES VARIABLES=y MISSING=INCLUDE.
CTABLES /TABLE x &gt; y &gt; z [SUM] /CATEGORIES VARIABLES=x y MISSING=INCLUDE.
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>   Custom Tables
+---------+------+
|         |  Sum |
+---------+------+
|x 1 y 1 z|     1|
|     ----+------+
|      2 z|    10|
|     ----+------+
|      9 z|   100|
| --------+------+
|  2 y 1 z|  1000|
|     ----+------+
|      2 z| 10000|
|     ----+------+
|      9 z|100000|
+---------+------+

    Custom Tables
+---------+---------+
|         |   Sum   |
+---------+---------+
|x 1 y 1 z|        1|
|     ----+---------+
|      2 z|       10|
|     ----+---------+
|      9 z|      100|
| --------+---------+
|  2 y 1 z|     1000|
|     ----+---------+
|      2 z|    10000|
|     ----+---------+
|      9 z|   100000|
| --------+---------+
|  9 y 1 z|  1000000|
|     ----+---------+
|      2 z| 10000000|
|     ----+---------+
|      9 z|100000000|
+---------+---------+
</screen>
</sect3>
<sect3 label="15.7.9.2" id="CTABLES-Missing-Values-for-Summary-Variables">
<title>Missing Values for Summary Variables</title>

<para>For summary variables, values that are valid and in included
categories are analyzed, and values that are missing or in excluded
categories are not analyzed, with the following exceptions:
</para>
<itemizedlist><listitem><para>The &#8220;<literal>VALIDN</literal>&#8221; summary functions (<literal>VALIDN</literal>, <literal>EVALIDN</literal>,
<literal>UVALIDN</literal>, <literal><emphasis>area</emphasis>PCT.VALIDN</literal>, and
<literal>U<emphasis>area</emphasis>PCT.VALIDN</literal>) only count valid values in included
categories (not missing values in included categories).
</para>
</listitem><listitem><para>The &#8220;<literal>TOTALN</literal>&#8221; summary functions (<literal>TOTALN</literal>, <literal>ETOTALN</literal>,
<literal>UTOTALN</literal>, <literal><emphasis>area</emphasis>PCT.TOTALN</literal>), and
<literal>U<emphasis>area</emphasis>PCT.TOTALN</literal> count all values (valid and missing) in
included categories and missing (but not valid) values in excluded
categories.
</para></listitem></itemizedlist>
<para>For categorical variables, system-missing values are never in included
categories.  For scale variables, there is no notion of included and
excluded categories, so all values are effectively included.
</para>
<para>The following table provides another view of the above rules:
</para>
<informaltable><tgroup cols="4"><colspec colwidth="41*"></colspec><colspec colwidth="6*"></colspec><colspec colwidth="5*"></colspec><colspec colwidth="6*"></colspec><thead><row><entry></entry><entry><para><literal>VALIDN</literal> </para></entry><entry><para>other </para></entry><entry><para><literal>TOTALN</literal>
</para></entry></row></thead><tbody><row><entry><para><emphasis role="bold">Categorical variables:</emphasis>
</para></entry></row><row><entry><para>&amp;#160;<!-- /@w -->&amp;#160;<!-- /@w -->&amp;#160;<!-- /@w -->&amp;#160;<!-- /@w -->Valid values in included categories   </para></entry><entry><para>yes </para></entry><entry><para>yes </para></entry><entry><para>yes
</para></entry></row><row><entry><para>&amp;#160;<!-- /@w -->&amp;#160;<!-- /@w -->&amp;#160;<!-- /@w -->&amp;#160;<!-- /@w -->Missing values in included categories </para></entry><entry><para>&#8212; </para></entry><entry><para>yes </para></entry><entry><para>yes
</para></entry></row><row><entry><para>&amp;#160;<!-- /@w -->&amp;#160;<!-- /@w -->&amp;#160;<!-- /@w -->&amp;#160;<!-- /@w -->Missing values in excluded categories </para></entry><entry><para>&#8212; </para></entry><entry><para>&#8212; </para></entry><entry><para>yes
</para></entry></row><row><entry><para>&amp;#160;<!-- /@w -->&amp;#160;<!-- /@w -->&amp;#160;<!-- /@w -->&amp;#160;<!-- /@w -->Valid values in excluded categories   </para></entry><entry><para>&#8212; </para></entry><entry><para>&#8212; </para></entry><entry><para>&#8212;
</para></entry></row><row><entry><para><emphasis role="bold">Scale variables:</emphasis>
</para></entry></row><row><entry><para>&amp;#160;<!-- /@w -->&amp;#160;<!-- /@w -->&amp;#160;<!-- /@w -->&amp;#160;<!-- /@w -->Valid values                          </para></entry><entry><para>yes </para></entry><entry><para>yes </para></entry><entry><para>yes
</para></entry></row><row><entry><para>&amp;#160;<!-- /@w -->&amp;#160;<!-- /@w -->&amp;#160;<!-- /@w -->&amp;#160;<!-- /@w -->User- or system-missing values        </para></entry><entry><para>&#8212; </para></entry><entry><para>yes </para></entry><entry><para>yes
</para></entry></row></tbody></tgroup></informaltable>
</sect3>
<sect3 label="15.7.9.3" id="CTABLES-Scale-Missing-Values">
<title>Scale Missing Values</title>

<literallayout><literal>/SMISSING</literal> {<literal>VARIABLE</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>LISTWISE</literal>}
</literallayout>
<para>The <literal>SMISSING</literal> subcommand, which must precede the first
<literal>TABLE</literal> subcommand, controls treatment of missing values for
scalar variables in producing all the output tables.  <literal>SMISSING</literal>
is optional.
</para>
<para>With <literal>SMISSING=VARIABLE</literal>, which is the default, missing values
are excluded on a variable-by-variable basis.  With
<literal>SMISSING=LISTWISE</literal>, when stacked scalar variables are nested
together with a categorical variable, a missing value for any of the
scalar variables causes the case to be excluded for all of them.
</para>
<para>As an example, consider the following dataset, in which &#8216;<literal>x</literal>&#8217; is a
categorical variable and &#8216;<literal>y</literal>&#8217; and &#8216;<literal>z</literal>&#8217; are scale:
</para>
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>   Data List
+-+-----+-----+
|x|  y  |  z  |
+-+-----+-----+
|1|    .|40.00|
|1|10.00|50.00|
|1|20.00|60.00|
|1|30.00|    .|
+-+-----+-----+
</screen>
<para>With the default missing-value treatment, &#8216;<literal>x</literal>&#8217;&#8217;s mean is 20, based
on the values 10, 20, and 30, and &#8216;<literal>y</literal>&#8217;&#8217;s mean is 50, based on 40,
50, and 60:
</para>
<screen>CTABLES /TABLE (y + z) &gt; x.
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>Custom Tables
+-----+-----+
|     | Mean|
+-----+-----+
|y x 1|20.00|
+-----+-----+
|z x 1|50.00|
+-----+-----+
</screen>
<para>By adding <literal>SMISSING=LISTWISE</literal>, only cases where &#8216;<literal>y</literal>&#8217; and
&#8216;<literal>z</literal>&#8217; are both non-missing are considered, so &#8216;<literal>x</literal>&#8217;&#8217;s mean
becomes 15, as the average of 10 and 20, and &#8216;<literal>y</literal>&#8217;&#8217;s mean becomes
55, the average of 50 and 60:
</para>
<screen>CTABLES /SMISSING LISTWISE /TABLE (y + z) &gt; x.
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>Custom Tables
+-----+-----+
|     | Mean|
+-----+-----+
|y x 1|15.00|
+-----+-----+
|z x 1|55.00|
+-----+-----+
</screen>
<para>Even with <literal>SMISSING=LISTWISE</literal>, if &#8216;<literal>y</literal>&#8217; and &#8216;<literal>z</literal>&#8217; are
separately nested with &#8216;<literal>x</literal>&#8217;, instead of using a single &#8216;<literal>&gt;</literal>&#8217;
operator, missing values revert to being considered on a
variable-by-variable basis:
</para>
<screen>CTABLES /SMISSING LISTWISE /TABLE (y &gt; x) + (z &gt; x).
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>Custom Tables
+-----+-----+
|     | Mean|
+-----+-----+
|y x 1|20.00|
+-----+-----+
|z x 1|50.00|
+-----+-----+
</screen>
</sect3>
</sect2>
<sect2 label="15.7.10" id="CTABLES-Computed-Categories">
<title>Computed Categories</title>

<literallayout><literal>/PCOMPUTE</literal> <literal>&amp;</literal><emphasis>postcompute</emphasis><literal>=EXPR(</literal><emphasis>expression</emphasis><literal>)</literal>
<literal>/PPROPERTIES</literal> <literal>&amp;</literal><emphasis>postcompute</emphasis>&#8230;
    [<literal>LABEL=</literal><emphasis>string</emphasis>]
    [<literal>FORMAT=</literal>[<emphasis>summary</emphasis> <emphasis>format</emphasis>]&#8230;]
    [<literal>HIDESOURCECATS=</literal>{<literal>NO</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>YES</literal>}
</literallayout>
<para><firstterm>Computed categories</firstterm>, also called <firstterm>postcomputes</firstterm>, are
categories created using arithmetic on categories obtained from the
data.  The <literal>PCOMPUTE</literal> subcommand creates a postcompute, which may
then be used on <literal>CATEGORIES</literal> within an explicit category list
(see <link linkend="CTABLES-Explicit-Category-List">CTABLES Explicit Category List</link>).  Optionally,
<literal>PPROPERTIES</literal> refines how a postcompute is displayed.  The
following sections provide the details.
</para>
<sect3 label="15.7.10.1" id="CTABLES-PCOMPUTE">
<title>PCOMPUTE</title>

<literallayout><literal>/PCOMPUTE</literal> <literal>&amp;</literal><emphasis>postcompute</emphasis><literal>=EXPR(</literal><emphasis>expression</emphasis><literal>)</literal>
</literallayout>
<para>The <literal>PCOMPUTE</literal> subcommand, which must precede the first
<literal>TABLE</literal> command, defines computed categories.  It is optional and
may be used any number of times to define multiple postcomputes.
</para>
<para>Each <literal>PCOMPUTE</literal> defines one postcompute.  Its syntax consists of
a name to identify the postcompute as a PSPP identifier prefixed by
&#8216;<literal>&amp;</literal>&#8217;, followed by &#8216;<literal>=</literal>&#8217; and a postcompute expression enclosed
in <literal>EXPR(&#8230;)</literal>.  A postcompute expression consists of:
</para>
<variablelist><varlistentry><term><literal>[<emphasis>category</emphasis>]</literal>
</term><listitem><para>This form evaluates to the summary statistic for <emphasis>category</emphasis>, e.g.
<literal>[1]</literal> evaluates to the value of the summary statistic associated
with category 1.  The <emphasis>category</emphasis> may be a number, a quoted string,
or a quoted time or date value.  All of the categories for a given
postcompute must have the same form.  The category must appear in all
the <literal>CATEGORIES</literal> list in which the postcompute is used.
</para>
</listitem></varlistentry><varlistentry><term><literal>[<emphasis>min</emphasis> THRU <emphasis>max</emphasis>]</literal>
</term><term><literal>[LO THRU <emphasis>max</emphasis>]</literal>
</term><term><literal>[<emphasis>min</emphasis> THRU HI]</literal>
</term><term><literal>MISSING</literal>
</term><term><literal>OTHERNM</literal>
</term><listitem><para>These forms evaluate to the summary statistics for a category
specified with the same syntax, as described in previous section
(see <link linkend="CTABLES-Explicit-Category-List">CTABLES Explicit Category List</link>).  The category must appear in
all the <literal>CATEGORIES</literal> list in which the postcompute is used.
</para>
</listitem></varlistentry><varlistentry><term><literal>SUBTOTAL</literal>
</term><listitem><para>The summary statistic for the subtotal category.  This form is allowed
only if the <literal>CATEGORIES</literal> lists that include this postcompute have
exactly one subtotal.
</para>
</listitem></varlistentry><varlistentry><term><literal>SUBTOTAL[<emphasis>index</emphasis>]</literal>
</term><listitem><para>The summary statistic for subtotal category <emphasis>index</emphasis>, where 1 is the
first subtotal, 2 is the second, and so on.  This form may be used for
<literal>CATEGORIES</literal> lists with any number of subtotals.
</para>
</listitem></varlistentry><varlistentry><term><literal>TOTAL</literal>
</term><listitem><para>The summary statistic for the total.  The <literal>CATEGORIES</literal> lsits that
include this postcompute must have a total enabled.
</para>
</listitem></varlistentry><varlistentry><term><literal><emphasis>a</emphasis> + <emphasis>b</emphasis></literal>
</term><term><literal><emphasis>a</emphasis> - <emphasis>b</emphasis></literal>
</term><term><literal><emphasis>a</emphasis> * <emphasis>b</emphasis></literal>
</term><term><literal><emphasis>a</emphasis> / <emphasis>b</emphasis></literal>
</term><term><literal><emphasis>a</emphasis> ** <emphasis>b</emphasis></literal>
</term><listitem><para>These forms perform arithmetic on the values of postcompute
expressions <emphasis>a</emphasis> and <emphasis>b</emphasis>.  The usual operator precedence rules
apply.
</para>
</listitem></varlistentry><varlistentry><term><literal><emphasis>number</emphasis></literal>
</term><listitem><para>Numeric constants may be used in postcompute expressions.
</para>
</listitem></varlistentry><varlistentry><term><literal>(<emphasis>a</emphasis>)</literal>
</term><listitem><para>Parentheses override operator precedence.
</para></listitem></varlistentry></variablelist>
<para>A postcompute is not associated with any particular variable.
Instead, it may be referenced within <literal>CATEGORIES</literal> for any
suitable variable (e.g. only a string variable is suitable for a
postcompute expression that refers to a string category, only a
variable with subtotals for an expression that refers to subtotals,
&#8230;).
</para>
<para>Normally a named postcompute is defined only once, but if a later
<literal>PCOMPUTE</literal> redefines a postcompute with the same name as an
earlier one, the later one take precedence.
</para>
<para>The following syntax and output shows how <literal>PCOMPUTE</literal> can compute
a total over subtotals, summing the &#8220;Frequent Drivers&#8221; and
&#8220;Infrequent Drivers&#8221; subtotals to form an &#8220;All Drivers&#8221;
postcompute.  It also shows how to calculate and display a percentage,
in this case the percentage of valid responses that report never
driving.  It uses <literal>PPROPERTIES</literal> (see <link linkend="CTABLES-PPROPERTIES">CTABLES PPROPERTIES</link>) to
display the latter in <literal>PCT</literal> format.
</para>
<screen>CTABLES
    /PCOMPUTE &amp;all_drivers=EXPR([1 THRU 2] + [3 THRU 4])
    /PPROPERTIES &amp;all_drivers LABEL='All Drivers'
    /PCOMPUTE &amp;pct_never=EXPR([5] / ([1 THRU 2] + [3 THRU 4] + [5]) * 100)
    /PPROPERTIES &amp;pct_never LABEL='% Not Drivers' FORMAT=COUNT PCT40.1
    /TABLE=freqOfDriving BY gender
    /CATEGORIES VARIABLES=freqOfDriving
                             [1 THRU 2, SUBTOTAL='Frequent Drivers',
                              3 THRU 4, SUBTOTAL='Infrequent Drivers',
                              &amp;all_drivers, 5, &amp;pct_never,
                              MISSING, SUBTOTAL='Not Drivers or Missing'].
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                                 Custom Tables
+----------------------------------------------------------------+------------+
|                                                                |S3a. GENDER:|
|                                                                +-----+------+
|                                                                | Male|Female|
|                                                                +-----+------+
|                                                                |Count| Count|
+----------------------------------------------------------------+-----+------+
| 1. How often do you usually drive a car or Every day           | 2305|  2362|
|other motor vehicle?                        Several days a week |  440|   834|
|                                            Frequent Drivers    | 2745|  3196|
|                                            Once a week or less |  125|   236|
|                                            Only certain times a|   58|    72|
|                                            year                |     |      |
|                                            Infrequent Drivers  |  183|   308|
|                                            All Drivers         | 2928|  3504|
|                                            Never               |  192|   348|
|                                            % Not Drivers       | 6.2%|  9.0%|
|                                            Don't know          |    3|     5|
|                                            Refused             |    9|    10|
|                                            Not Drivers or      |  204|   363|
|                                            Missing             |     |      |
+----------------------------------------------------------------+-----+------+
</screen>
</sect3>
<sect3 label="15.7.10.2" id="CTABLES-PPROPERTIES">
<title>PPROPERTIES</title>

<literallayout><literal>/PPROPERTIES</literal> <literal>&amp;</literal><emphasis>postcompute</emphasis>&#8230;
    [<literal>LABEL=</literal><emphasis>string</emphasis>]
    [<literal>FORMAT=</literal>[<emphasis>summary</emphasis> <emphasis>format</emphasis>]&#8230;]
    [<literal>HIDESOURCECATS=</literal>{<literal>NO</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>YES</literal>}
</literallayout>
<para>The <literal>PPROPERTIES</literal> subcommand, which must appear before
<literal>TABLE</literal>, sets properties for one or more postcomputes defined on
prior <literal>PCOMPUTE</literal> subcommands.  The subcommand syntax begins with
the list of postcomputes, each prefixed with &#8216;<literal>&amp;</literal>&#8217; as specified on
<literal>PCOMPUTE</literal>.
</para>
<para>All of the settings on <literal>PPROPERTIES</literal> are optional.  Use
<literal>LABEL</literal> to set the label shown for the postcomputes in table
output.  The default label for a postcompute is the expression used to
define it.
</para>
<para>A postcompute always uses same summary functions as the variable whose
categories contain it, but <literal>FORMAT</literal> allows control over the
format used to display their values.  It takes a list of summary
function names and format specifiers.
</para>
<para>By default, or with <literal>HIDESOURCECATS=NO</literal>, categories referred to
by computed categories are displayed like other categories.  Use
<literal>HIDESOURCECATS=YES</literal> to hide them.
</para>
<para>The previous section provides an example for <literal>PPROPERTIES</literal>.
</para>
</sect3>
</sect2>
<sect2 label="15.7.11" id="CTABLES-Effective-Weight">
<title>Effective Weight</title>

<literallayout><literal>/WEIGHT VARIABLE=</literal><emphasis>variable</emphasis>
</literallayout>
<para>The <literal>WEIGHT</literal> subcommand is optional and must appear before
<literal>TABLE</literal>.  If it appears, it must name a numeric variable, known
as the <firstterm>effective weight</firstterm> or <firstterm>adjustment weight</firstterm>.  The
effective weight variable stands in for the dictionary&#8217;s weight
variable (see <link linkend="WEIGHT">WEIGHT</link>), if any, in most calculations in
<literal>CTABLES</literal>.  The only exceptions are the <literal>COUNT</literal>,
<literal>TOTALN</literal>, and <literal>VALIDN</literal> summary functions, which use the
dictionary weight instead.
</para>
<para>Weights obtained from the PSPP dictionary are rounded to the
nearest integer at the case level.  Effective weights are not rounded.
Regardless of the weighting source, PSPP does not analyze cases
with zero, missing, or negative effective weights.
</para>
</sect2>
<sect2 label="15.7.12" id="CTABLES-Hiding-Small-Counts">
<title>Hiding Small Counts</title>

<literallayout><literal>/HIDESMALLCOUNTS COUNT=<emphasis>count</emphasis></literal>
</literallayout>
<para>The <literal>HIDESMALLCOUNTS</literal> subcommand is optional.  If it specified,
then <literal>COUNT</literal>, <literal>ECOUNT</literal>, and <literal>UCOUNT</literal> values in output
tables less than the value of <emphasis>count</emphasis> are shown as <literal>&lt;<emphasis>count</emphasis></literal>
instead of their true values.  The value of <emphasis>count</emphasis> must be an
integer and must be at least 2.
</para>
<para>The following syntax and example shows how to use
<literal>HIDESMALLCOUNTS</literal>:
</para>
<screen>CTABLES /HIDESMALLCOUNTS COUNT=10 /TABLE placeOfLastDrinkBeforeDrive.
</screen><!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                                 Custom Tables
+-----------------------------------------------------------------------+-----+
|                                                                       |Count|
+-----------------------------------------------------------------------+-----+
|37. Please think about the most recent occasion that   Other (list)    |&lt;10  |
|you drove within two hours of drinking alcoholic       Your home       |  182|
|beverages. Where did you drink on that occasion?       Friend's home   |  264|
|                                                       Bar/Tavern/Club |  279|
|                                                       Restaurant      |  495|
|                                                       Work            |   21|
|                                                       Bowling alley   |&lt;10  |
|                                                       Hotel/Motel     |&lt;10  |
|                                                       Country Club/   |   17|
|                                                       Golf course     |     |
|                                                       Drank in the    |&lt;10  |
|                                                       car/On the road |     |
|                                                       Sporting event  |   15|
|                                                       Movie theater   |&lt;10  |
|                                                       Shopping/Store/ |&lt;10  |
|                                                       Grocery store   |     |
|                                                       Wedding         |   15|
|                                                       Party at someone|   81|
|                                                       else's home     |     |
|                                                       Park/picnic     |   14|
|                                                       Party at your   |&lt;10  |
|                                                       house           |     |
+-----------------------------------------------------------------------+-----+
</screen>
</sect2>
</sect1>
<sect1 label="15.8" id="FACTOR">
<title>FACTOR</title>

<indexterm role="vr"><primary>FACTOR</primary></indexterm>
<indexterm role="cp"><primary>factor analysis</primary></indexterm>
<indexterm role="cp"><primary>principal components analysis</primary></indexterm>
<indexterm role="cp"><primary>principal axis factoring</primary></indexterm>
<indexterm role="cp"><primary>data reduction</primary></indexterm>

<literallayout>FACTOR  {
         VARIABLES=<replaceable>var_list</replaceable>,
         MATRIX IN ({CORR,COV}={*,<replaceable>file_spec</replaceable>})
        }

        [ /METHOD = {CORRELATION, COVARIANCE} ]

        [ /ANALYSIS=<replaceable>var_list</replaceable> ]

        [ /EXTRACTION={PC, PAF}]

        [ /ROTATION={VARIMAX, EQUAMAX, QUARTIMAX, PROMAX[(<replaceable>k</replaceable>)], NOROTATE}]

        [ /PRINT=[INITIAL] [EXTRACTION] [ROTATION] [UNIVARIATE] [CORRELATION] [COVARIANCE] [DET] [KMO] [AIC] [SIG] [ALL] [DEFAULT] ]

        [ /PLOT=[EIGEN] ]

        [ /FORMAT=[SORT] [BLANK(<replaceable>n</replaceable>)] [DEFAULT] ]

        [ /CRITERIA=[FACTORS(<replaceable>n</replaceable>)] [MINEIGEN(<replaceable>l</replaceable>)] [ITERATE(<replaceable>m</replaceable>)] [ECONVERGE (<replaceable>delta</replaceable>)] [DEFAULT] ]

        [ /MISSING=[{LISTWISE, PAIRWISE}] [{INCLUDE, EXCLUDE}] ]
</literallayout>
<para>The <literal>FACTOR</literal> command performs Factor Analysis or Principal Axis Factoring on a dataset.  It may be used to find
common factors in the data or for data reduction purposes.
</para>
<para>The <literal>VARIABLES</literal> subcommand is required (unless the <literal>MATRIX IN</literal>
subcommand is used).
It lists the variables which are to partake in the analysis.  (The <literal>ANALYSIS</literal>
subcommand may optionally further limit the variables that
participate; it is useful primarily in conjunction with <literal>MATRIX IN</literal>.)
</para>
<para>If <literal>MATRIX IN</literal> instead of <literal>VARIABLES</literal> is specified, then the analysis
is performed on a pre-prepared correlation or covariance matrix file instead of on
individual data cases.  Typically the matrix file will have been generated by
<literal>MATRIX DATA</literal> (see <link linkend="MATRIX-DATA">MATRIX DATA</link>) or provided by a third party.
If specified, <literal>MATRIX IN</literal> must be followed by &#8216;<literal>COV</literal>&#8217; or &#8216;<literal>CORR</literal>&#8217;,
then by &#8216;<literal>=</literal>&#8217; and <replaceable>file_spec</replaceable> all in parentheses.
<replaceable>file_spec</replaceable> may either be an asterisk, which indicates the currently loaded
dataset, or it may be a file name to be loaded. See <link linkend="MATRIX-DATA">MATRIX DATA</link>, for the expected
format of the file.
</para>
<para>The <literal>/EXTRACTION</literal> subcommand is used to specify the way in which factors
(components) are extracted from the data.
If <literal>PC</literal> is specified, then Principal Components Analysis is used.
If <literal>PAF</literal> is specified, then Principal Axis Factoring is
used. By default Principal Components Analysis is used.
</para>
<para>The <literal>/ROTATION</literal> subcommand is used to specify the method by which the
extracted solution is rotated.  Three orthogonal rotation methods are available:
<literal>VARIMAX</literal> (which is the default), <literal>EQUAMAX</literal>, and <literal>QUARTIMAX</literal>.
There is one oblique rotation method, <emphasis>viz</emphasis>: <literal>PROMAX</literal>.
Optionally you may enter the power of the promax rotation <replaceable>k</replaceable>, which must be enclosed in parentheses.
The default value of <replaceable>k</replaceable> is 5.
If you don&#8217;t want any rotation to be performed, the word <literal>NOROTATE</literal>
prevents the command from performing any rotation on the data.
</para>
<para>The <literal>/METHOD</literal> subcommand should be used to determine whether the
covariance matrix or the correlation matrix of the data is
to be analysed.  By default, the correlation matrix is analysed.
</para>
<para>The <literal>/PRINT</literal> subcommand may be used to select which features of the analysis are reported:
</para>
<itemizedlist><listitem><para><literal>UNIVARIATE</literal>
      A table of mean values, standard deviations and total weights are printed.
</para></listitem><listitem><para><literal>INITIAL</literal>
      Initial communalities and eigenvalues are printed.
</para></listitem><listitem><para><literal>EXTRACTION</literal>
      Extracted communalities and eigenvalues are printed.
</para></listitem><listitem><para><literal>ROTATION</literal>
      Rotated communalities and eigenvalues are printed.
</para></listitem><listitem><para><literal>CORRELATION</literal>
      The correlation matrix is printed.
</para></listitem><listitem><para><literal>COVARIANCE</literal>
      The covariance matrix is printed.
</para></listitem><listitem><para><literal>DET</literal>
      The determinant of the correlation or covariance matrix is printed.
</para></listitem><listitem><para><literal>AIC</literal>
      The anti-image covariance and anti-image correlation matrices are printed.
</para></listitem><listitem><para><literal>KMO</literal>
      The Kaiser-Meyer-Olkin measure of sampling adequacy and the Bartlett test of sphericity is printed.
</para></listitem><listitem><para><literal>SIG</literal>
      The significance of the elements of correlation matrix is printed.
</para></listitem><listitem><para><literal>ALL</literal>
      All of the above are printed.
</para></listitem><listitem><para><literal>DEFAULT</literal>
      Identical to <literal>INITIAL</literal> and <literal>EXTRACTION</literal>.
</para></listitem></itemizedlist>
<para>If <literal>/PLOT=EIGEN</literal> is given, then a &#8220;Scree&#8221; plot of the eigenvalues is
printed.  This can be useful for visualizing the factors and deciding
which factors (components) should be retained.
</para>
<para>The <literal>/FORMAT</literal> subcommand determined how data are to be
displayed in loading matrices.  If <literal>SORT</literal> is specified, then
the variables are sorted in descending order of significance.  If
<literal>BLANK(<replaceable>n</replaceable>)</literal> is specified, then coefficients whose absolute
value is less than <replaceable>n</replaceable> are not printed.  If the keyword
<literal>DEFAULT</literal> is specified, or if no <literal>/FORMAT</literal> subcommand is
specified, then no sorting is performed, and all coefficients are printed.
</para>
<para>You can use the <literal>/CRITERIA</literal> subcommand to specify how the number of
extracted factors (components) are chosen.  If <literal>FACTORS(<replaceable>n</replaceable>)</literal> is
specified, where <replaceable>n</replaceable> is an integer, then <replaceable>n</replaceable> factors are
extracted.  Otherwise, the <literal>MINEIGEN</literal> setting is used.
<literal>MINEIGEN(<replaceable>l</replaceable>)</literal> requests that all factors whose eigenvalues
are greater than or equal to <replaceable>l</replaceable> are extracted. The default value
of <replaceable>l</replaceable> is 1. The <literal>ECONVERGE</literal> setting has effect only when
using iterative algorithms for factor extraction (such as Principal Axis
Factoring).  <literal>ECONVERGE(<replaceable>delta</replaceable>)</literal> specifies that
iteration should cease when the maximum absolute value of the
communality estimate between one iteration and the previous is less
than <replaceable>delta</replaceable>. The default value of <replaceable>delta</replaceable> is 0.001.
</para>
<para>The <literal>ITERATE(<replaceable>m</replaceable>)</literal> may appear any number of times and is
used for two different purposes. It is used to set the maximum number
of iterations (<replaceable>m</replaceable>) for convergence and also to set the maximum
number of iterations for rotation.
Whether it affects convergence or rotation depends upon which
subcommand follows the <literal>ITERATE</literal> subcommand.
If <literal>EXTRACTION</literal> follows, it affects convergence.
If <literal>ROTATION</literal> follows, it affects rotation.
If neither <literal>ROTATION</literal> nor <literal>EXTRACTION</literal> follow a
<literal>ITERATE</literal> subcommand, then the entire subcommand is ignored.
The default value of <replaceable>m</replaceable> is 25.
</para>
<para>The <literal>MISSING</literal> subcommand determines the handling of missing
variables.  If <literal>INCLUDE</literal> is set, then user-missing values are
included in the calculations, but system-missing values are not.
If <literal>EXCLUDE</literal> is set, which is the default, user-missing
values are excluded as well as system-missing values.  This is the
default. If <literal>LISTWISE</literal> is set, then the entire case is excluded
from analysis whenever any variable  specified in the <literal>VARIABLES</literal>
subcommand contains a missing value.
</para>
<para>If <literal>PAIRWISE</literal> is set, then a case is considered missing only if
either of the values  for the particular coefficient are missing.
The default is <literal>LISTWISE</literal>.
</para>
</sect1>
<sect1 label="15.9" id="GLM">
<title>GLM</title>

<indexterm role="vr"><primary>GLM</primary></indexterm>
<indexterm role="cp"><primary>univariate analysis of variance</primary></indexterm>
<indexterm role="cp"><primary>fixed effects</primary></indexterm>
<indexterm role="cp"><primary>factorial anova</primary></indexterm>
<indexterm role="cp"><primary>analysis of variance</primary></indexterm>
<indexterm role="cp"><primary>ANOVA</primary></indexterm>


<literallayout>GLM <replaceable>dependent_vars</replaceable> BY <replaceable>fixed_factors</replaceable>
     [/METHOD = SSTYPE(<replaceable>type</replaceable>)]
     [/DESIGN = <replaceable>interaction_0</replaceable> [<replaceable>interaction_1</replaceable> [... <replaceable>interaction_n</replaceable>]]]
     [/INTERCEPT = {INCLUDE|EXCLUDE}]
     [/MISSING = {INCLUDE|EXCLUDE}]
</literallayout>
<para>The <literal>GLM</literal> procedure can be used for fixed effects factorial Anova.
</para>
<para>The <replaceable>dependent_vars</replaceable> are the variables to be analysed.
You may analyse several variables in the same command in which case they should all
appear before the <literal>BY</literal> keyword.
</para>
<para>The <replaceable>fixed_factors</replaceable> list must be one or more categorical variables.  Normally it
does not make sense to enter a scalar variable in the <replaceable>fixed_factors</replaceable> and doing
so may cause PSPP to do a lot of unnecessary processing.
</para>
<para>The <literal>METHOD</literal> subcommand is used to change the method for producing the sums of
squares.  Available values of <replaceable>type</replaceable> are 1, 2 and 3.  The default is type 3.
</para>
<para>You may specify a custom design using the <literal>DESIGN</literal> subcommand.
The design comprises a list of interactions where each interaction is a
list of variables separated by a &#8216;<literal>*</literal>&#8217;.  For example the command
</para><literallayout>GLM subject BY sex age_group race
    /DESIGN = age_group sex group age_group*sex age_group*race
</literallayout><para>specifies the model <inlineequation><mathphrase>subject = age_group + sex + race + age_group*sex + age_group*race</mathphrase></inlineequation>.
If no <literal>DESIGN</literal> subcommand is specified, then the default is all possible combinations
of the fixed factors.  That is to say
</para><literallayout>GLM subject BY sex age_group race
</literallayout><para>implies the model
<inlineequation><mathphrase>subject = age_group + sex + race + age_group*sex + age_group*race + sex*race + age_group*sex*race</mathphrase></inlineequation>.
</para>

<para>The <literal>MISSING</literal> subcommand determines the handling of missing
variables.
If <literal>INCLUDE</literal> is set then, for the purposes of GLM analysis,
only system-missing values are considered
to be missing; user-missing values are not regarded as missing.
If <literal>EXCLUDE</literal> is set, which is the default, then user-missing
values are considered to be missing as well as system-missing values.
A case for which any dependent variable or any factor
variable has a missing value is excluded from the analysis.
</para>
</sect1>
<sect1 label="15.10" id="LOGISTIC-REGRESSION">
<title>LOGISTIC REGRESSION</title>

<indexterm role="vr"><primary>LOGISTIC REGRESSION</primary></indexterm>
<indexterm role="cp"><primary>logistic regression</primary></indexterm>
<indexterm role="cp"><primary>bivariate logistic regression</primary></indexterm>

<literallayout>LOGISTIC REGRESSION [VARIABLES =] <replaceable>dependent_var</replaceable> WITH <replaceable>predictors</replaceable>

     [/CATEGORICAL = <replaceable>categorical_predictors</replaceable>]

     [{/NOCONST | /ORIGIN | /NOORIGIN }]

     [/PRINT = [SUMMARY] [DEFAULT] [CI(<replaceable>confidence</replaceable>)] [ALL]]

     [/CRITERIA = [BCON(<replaceable>min_delta</replaceable>)] [ITERATE(<replaceable>max_interations</replaceable>)]
                  [LCON(<replaceable>min_likelihood_delta</replaceable>)] [EPS(<replaceable>min_epsilon</replaceable>)]
                  [CUT(<replaceable>cut_point</replaceable>)]]

     [/MISSING = {INCLUDE|EXCLUDE}]
</literallayout>
<para>Bivariate Logistic Regression is used when you want to explain a dichotomous dependent
variable in terms of one or more predictor variables.
</para>
<para>The minimum command is
</para><screen>LOGISTIC REGRESSION <replaceable>y</replaceable> WITH <replaceable>x1</replaceable> <replaceable>x2</replaceable> &#8230; <replaceable>xn</replaceable>.
</screen><para>Here, <replaceable>y</replaceable> is the dependent variable, which must be dichotomous and <replaceable>x1</replaceable> &#8230; <replaceable>xn</replaceable>
are the predictor variables whose coefficients the procedure estimates.
</para>
<para>By default, a constant term is included in the model.
Hence, the full model is
<inlineequation><mathphrase>{\bf y}
= b_0 + b_1 {\bf x_1}
+ b_2 {\bf x_2}
+ \dots
+ b_n {\bf x_n}
</mathphrase></inlineequation>
</para>
<para>Predictor variables which are categorical in nature should be listed on the <literal>/CATEGORICAL</literal> subcommand.
Simple variables as well as interactions between variables may be listed here.
</para>
<para>If you want a model without the constant term <inlineequation><mathphrase>b_0</mathphrase></inlineequation>, use the keyword <literal>/ORIGIN</literal>.
<literal>/NOCONST</literal> is a synonym for <literal>/ORIGIN</literal>.
</para>
<para>An iterative Newton-Raphson procedure is used to fit the model.
The <literal>/CRITERIA</literal> subcommand is used to specify the stopping criteria of the procedure,
and other parameters.
The value of <replaceable>cut_point</replaceable> is used in the classification table.  It is the
threshold above which predicted values are considered to be 1.  Values
of <replaceable>cut_point</replaceable> must lie in the range [0,1].
During iterations, if any one of the stopping criteria are satisfied, the procedure is
considered complete.
The stopping criteria are:
</para><itemizedlist><listitem><para>The number of iterations exceeds <replaceable>max_iterations</replaceable>.
      The default value of <replaceable>max_iterations</replaceable> is 20.
</para></listitem><listitem><para>The change in the all coefficient estimates are less than <replaceable>min_delta</replaceable>.
The default value of <replaceable>min_delta</replaceable> is 0.001.
</para></listitem><listitem><para>The magnitude of change in the likelihood estimate is less than <replaceable>min_likelihood_delta</replaceable>.
The default value of <replaceable>min_delta</replaceable> is zero.
This means that this criterion is disabled.
</para></listitem><listitem><para>The differential of the estimated probability for all cases is less than <replaceable>min_epsilon</replaceable>.
In other words, the probabilities are close to zero or one.
The default value of <replaceable>min_epsilon</replaceable> is 0.00000001.
</para></listitem></itemizedlist>

<para>The <literal>PRINT</literal> subcommand controls the display of optional statistics.
Currently there is one such option, <literal>CI</literal>, which indicates that the
confidence interval of the odds ratio should be displayed as well as its value.
<literal>CI</literal> should be followed by an integer in parentheses, to indicate the
confidence level of the desired confidence interval.
</para>
<para>The <literal>MISSING</literal> subcommand determines the handling of missing
variables.
If <literal>INCLUDE</literal> is set, then user-missing values are included in the
calculations, but system-missing values are not.
If <literal>EXCLUDE</literal> is set, which is the default, user-missing
values are excluded as well as system-missing values.
This is the default.
</para>
</sect1>
<sect1 label="15.11" id="MEANS">
<title>MEANS</title>

<indexterm role="vr"><primary>MEANS</primary></indexterm>
<indexterm role="cp"><primary>means</primary></indexterm>

<literallayout>MEANS [TABLES =]
      {<replaceable>var_list</replaceable>}
        [ BY {<replaceable>var_list</replaceable>} [BY {<replaceable>var_list</replaceable>} [BY {<replaceable>var_list</replaceable>} &#8230; ]]]

      [ /{<replaceable>var_list</replaceable>}
         [ BY {<replaceable>var_list</replaceable>} [BY {<replaceable>var_list</replaceable>} [BY {<replaceable>var_list</replaceable>} &#8230; ]]] ]

      [/CELLS = [MEAN] [COUNT] [STDDEV] [SEMEAN] [SUM] [MIN] [MAX] [RANGE]
        [VARIANCE] [KURT] [SEKURT]
        [SKEW] [SESKEW] [FIRST] [LAST]
        [HARMONIC] [GEOMETRIC]
        [DEFAULT]
        [ALL]
        [NONE] ]

      [/MISSING = [INCLUDE] [DEPENDENT]]
</literallayout>
<para>You can use the <literal>MEANS</literal> command to calculate the arithmetic mean and similar
statistics, either for the dataset as a whole or for categories of data.
</para>
<para>The simplest form of the command is
</para><screen>MEANS <replaceable>v</replaceable>.
</screen><para>which calculates the mean, count and standard deviation for <replaceable>v</replaceable>.
If you specify a grouping variable, for example
</para><screen>MEANS <replaceable>v</replaceable> BY <replaceable>g</replaceable>.
</screen><para>then the means, counts and standard deviations for <replaceable>v</replaceable> after having
been grouped by <replaceable>g</replaceable> are calculated.
Instead of the mean, count and standard deviation, you could specify the statistics
in which you are interested:
</para><screen>MEANS <replaceable>x</replaceable> <replaceable>y</replaceable> BY <replaceable>g</replaceable>
      /CELLS = HARMONIC SUM MIN.
</screen><para>This example calculates the harmonic mean, the sum and the minimum values of <replaceable>x</replaceable> and <replaceable>y</replaceable>
grouped by <replaceable>g</replaceable>.
</para>
<para>The <literal>CELLS</literal> subcommand specifies which statistics to calculate.  The available statistics
are:
</para><itemizedlist><listitem><para><literal>MEAN</literal>
<indexterm role="cp"><primary>arithmetic mean</primary></indexterm>
      The arithmetic mean.
</para></listitem><listitem><para><literal>COUNT</literal>
      The count of the values.
</para></listitem><listitem><para><literal>STDDEV</literal>
      The standard deviation.
</para></listitem><listitem><para><literal>SEMEAN</literal>
      The standard error of the mean.
</para></listitem><listitem><para><literal>SUM</literal>
      The sum of the values.
</para></listitem><listitem><para><literal>MIN</literal>
      The minimum value.
</para></listitem><listitem><para><literal>MAX</literal>
      The maximum value.
</para></listitem><listitem><para><literal>RANGE</literal>
      The difference between the maximum and minimum values.
</para></listitem><listitem><para><literal>VARIANCE</literal>
      The variance.
</para></listitem><listitem><para><literal>FIRST</literal>
      The first value in the category.
</para></listitem><listitem><para><literal>LAST</literal>
      The last value in the category.
</para></listitem><listitem><para><literal>SKEW</literal>
      The skewness.
</para></listitem><listitem><para><literal>SESKEW</literal>
      The standard error of the skewness.
</para></listitem><listitem><para><literal>KURT</literal>
      The kurtosis
</para></listitem><listitem><para><literal>SEKURT</literal>
      The standard error of the kurtosis.
</para></listitem><listitem><para><literal>HARMONIC</literal>
<indexterm role="cp"><primary>harmonic mean</primary></indexterm>
      The harmonic mean.
</para></listitem><listitem><para><literal>GEOMETRIC</literal>
<indexterm role="cp"><primary>geometric mean</primary></indexterm>
      The geometric mean.
</para></listitem></itemizedlist>
<para>In addition, three special keywords are recognized:
</para><itemizedlist><listitem><para><literal>DEFAULT</literal>
      This is the same as <literal>MEAN</literal> <literal>COUNT</literal> <literal>STDDEV</literal>.
</para></listitem><listitem><para><literal>ALL</literal>
      All of the above statistics are calculated.
</para></listitem><listitem><para><literal>NONE</literal>
      No statistics are calculated (only a summary is shown).
</para></listitem></itemizedlist>

<para>More than one <firstterm>table</firstterm> can be specified in a single command.
Each table is separated by a &#8216;<literal>/</literal>&#8217;. For
example
</para><screen>MEANS TABLES =
      <replaceable>c</replaceable> <replaceable>d</replaceable> <replaceable>e</replaceable> BY <replaceable>x</replaceable>
      /<replaceable>a</replaceable> <replaceable>b</replaceable> BY <replaceable>x</replaceable> <replaceable>y</replaceable>
      /<replaceable>f</replaceable> BY <replaceable>y</replaceable> BY <replaceable>z</replaceable>.
</screen><para>has three tables (the &#8216;<literal>TABLE =</literal>&#8217; is optional).
The first table has three dependent variables <replaceable>c</replaceable>, <replaceable>d</replaceable> and <replaceable>e</replaceable>
and a single categorical variable <replaceable>x</replaceable>.
The second table has two dependent variables <replaceable>a</replaceable> and <replaceable>b</replaceable>,
and two categorical variables <replaceable>x</replaceable> and <replaceable>y</replaceable>.
The third table has a single dependent variables <replaceable>f</replaceable>
and a categorical variable formed by the combination of <replaceable>y</replaceable> and <replaceable>z</replaceable>.
</para>

<para>By default values are omitted from the analysis only if missing values
(either system missing or user missing)
for any of the variables directly involved in their calculation are
encountered.
This behaviour can be modified with the  <literal>/MISSING</literal> subcommand.
Three options are possible: <literal>TABLE</literal>, <literal>INCLUDE</literal> and <literal>DEPENDENT</literal>.
</para>
<para><literal>/MISSING = INCLUDE</literal> says that user missing values, either in the dependent
variables or in the categorical variables should be taken at their face
value, and not excluded.
</para>
<para><literal>/MISSING = DEPENDENT</literal> says that user missing values, in the dependent
variables should be taken at their face value, however cases which
have user missing values for the categorical variables should be omitted
from the calculation.
</para>
<sect2 label="15.11.1">
<title>Example Means</title>

<para>The dataset in <filename>repairs.sav</filename> contains the mean time between failures (<emphasis role="bold">mtbf</emphasis>)
for a sample of artifacts produced by different factories and trialed under
different operating conditions.
Since there are four combinations of categorical variables, by simply looking
at the list of data, it would be hard to how the scores vary for each category.
<link linkend="means_003aex">means:ex</link> shows one way of tabulating the <emphasis role="bold">mtbf</emphasis> in a way which is
easier to understand.
</para>
<anchor id="means_003aex"/>
<sidebar><screen>get file='repairs.sav'.

means tables = mtbf
      by factory by environment.
</screen></sidebar>
<para>The results are shown in <link linkend="means_003ares">means:res</link>.   The figures shown indicate the mean,
standard deviation and number of samples in each category.
These figures however do not indicate whether the results are statistically
significant.  For that, you would need to use the procedures <literal>ONEWAY</literal>, <literal>GLM</literal> or
<literal>T-TEST</literal> depending on the hypothesis being tested.
</para>
<anchor id="means_003ares"/>
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                    Case Processing Summary
+----------------------------+-------------------------------+
|                            |             Cases             |
|                            +----------+---------+----------+
|                            | Included | Excluded|   Total  |
|                            +--+-------+-+-------+--+-------+
|                            | N|Percent|N|Percent| N|Percent|
+----------------------------+--+-------+-+-------+--+-------+
|mtbf * factory * environment|30| 100.0%|0|    .0%|30| 100.0%|
+----------------------------+--+-------+-+-------+--+-------+

                                Report
+--------------------------------------------+-----+--+--------------+
|Manufacturing facility Operating Environment| Mean| N|Std. Deviation|
+--------------------------------------------+-----+--+--------------+
|0                      Temperate            | 7.26| 9|          2.57|
|                       Tropical             | 7.47| 7|          2.68|
|                       Total                | 7.35|16|          2.53|
+--------------------------------------------+-----+--+--------------+
|1                      Temperate            |13.38| 6|          7.77|
|                       Tropical             | 8.20| 8|          8.39|
|                       Total                |10.42|14|          8.26|
+--------------------------------------------+-----+--+--------------+
|Total                  Temperate            | 9.71|15|          5.91|
|                       Tropical             | 7.86|15|          6.20|
|                       Total                | 8.78|30|          6.03|
+--------------------------------------------+-----+--+--------------+
</screen>
<para>Note that there is no limit to the number of variables for which you can calculate
statistics, nor to the number of categorical variables per layer, nor the number
of layers.
However, running <literal>MEANS</literal> on a large numbers of variables, or with categorical variables
containing a large number of distinct values may result in an extremely large output, which
will not be easy to interpret.
So you should consider carefully which variables to select for participation in the analysis.
</para>
</sect2>
</sect1>
<sect1 label="15.12" id="NPAR-TESTS">
<title>NPAR TESTS</title>

<indexterm role="vr"><primary>NPAR TESTS</primary></indexterm>
<indexterm role="cp"><primary>nonparametric tests</primary></indexterm>

<literallayout>NPAR TESTS

     nonparametric test subcommands
     .
     .
     .

     [ /STATISTICS={DESCRIPTIVES} ]

     [ /MISSING={ANALYSIS, LISTWISE} {INCLUDE, EXCLUDE} ]

     [ /METHOD=EXACT [ TIMER [(<replaceable>n</replaceable>)] ] ]
</literallayout>
<para><literal>NPAR TESTS</literal> performs nonparametric tests.
Non parametric tests make very few assumptions about the distribution of the
data.
One or more tests may be specified by using the corresponding subcommand.
If the <literal>/STATISTICS</literal> subcommand is also specified, then summary statistics are
produces for each variable that is the subject of any test.
</para>
<para>Certain tests may take a long time to execute, if an exact figure is required.
Therefore, by default asymptotic approximations are used unless the
subcommand <literal>/METHOD=EXACT</literal> is specified.
Exact tests give more accurate results, but may take an unacceptably long
time to perform.  If the <literal>TIMER</literal> keyword is used, it sets a maximum time,
after which the test is abandoned, and a warning message printed.
The time, in minutes, should be specified in parentheses after the <literal>TIMER</literal> keyword.
If the <literal>TIMER</literal> keyword is given without this figure, then a default value of 5 minutes
is used.
</para>



<sect2 label="15.12.1" id="BINOMIAL">
<title>Binomial test</title>
<indexterm role="vr"><primary>BINOMIAL</primary></indexterm>
<indexterm role="cp"><primary>binomial test</primary></indexterm>

<literallayout>     [ /BINOMIAL[(<replaceable>p</replaceable>)]=<replaceable>var_list</replaceable>[(<replaceable>value1</replaceable>[, <replaceable>value2</replaceable>)] ] ]
</literallayout>
<para>The <literal>/BINOMIAL</literal> subcommand compares the observed distribution of a dichotomous
variable with that of a binomial distribution.
The variable <replaceable>p</replaceable> specifies the test proportion of the binomial
distribution.
The default value of 0.5 is assumed if <replaceable>p</replaceable> is omitted.
</para>
<para>If a single value appears after the variable list, then that value is
used as the threshold to partition the observed values. Values less
than or equal to the threshold value form the first category.  Values
greater than the threshold form the second category.
</para>
<para>If two values appear after the variable list, then they are used
as the values which a variable must take to be in the respective
category.
Cases for which a variable takes a value equal to neither of the specified
values, take no part in the test for that variable.
</para>
<para>If no values appear, then the variable must assume dichotomous
values.
If more than two distinct, non-missing values for a variable
under test are encountered then an error occurs.
</para>
<para>If the test proportion is equal to 0.5, then a two-tailed test is
reported.   For any other test proportion, a one-tailed test is
reported.
For one-tailed tests, if the test proportion is less than
or equal to the observed proportion, then the significance of
observing the observed proportion or more is reported.
If the test proportion is more than the observed proportion, then the
significance of observing the observed proportion or less is reported.
That is to say, the test is always performed in the observed
direction.
</para>
<para>PSPP uses a very precise approximation to the gamma function to
compute the binomial significance.  Thus, exact results are reported
even for very large sample sizes.
</para>

</sect2>
<sect2 label="15.12.2" id="CHISQUARE">
<title>Chi-square Test</title>
<indexterm role="vr"><primary>CHISQUARE</primary></indexterm>
<indexterm role="cp"><primary>chi-square test</primary></indexterm>


<literallayout>     [ /CHISQUARE=<replaceable>var_list</replaceable>[(<replaceable>lo</replaceable>,<replaceable>hi</replaceable>)] [/EXPECTED={EQUAL|<replaceable>f1</replaceable>, <replaceable>f2</replaceable> &#8230; <replaceable>fn</replaceable>}] ]
</literallayout>

<para>The <literal>/CHISQUARE</literal> subcommand produces a chi-square statistic for the differences
between the expected and observed frequencies of the categories of a variable.
Optionally, a range of values may appear after the variable list.
If a range is given, then non integer values are truncated, and values
outside the  specified range are excluded from the analysis.
</para>
<para>The <literal>/EXPECTED</literal> subcommand specifies the expected values of each
category.
There must be exactly one non-zero expected value, for each observed
category, or the <literal>EQUAL</literal> keyword must be specified.
You may use the notation <literal><replaceable>n</replaceable>*<replaceable>f</replaceable></literal> to specify <replaceable>n</replaceable>
consecutive expected categories all taking a frequency of <replaceable>f</replaceable>.
The frequencies given are proportions, not absolute frequencies.  The
sum of the frequencies need not be 1.
If no <literal>/EXPECTED</literal> subcommand is given, then equal frequencies
are expected.
</para>
<sect3 label="15.12.2.1">
<title>Chi-square Example</title>

<para>A researcher wishes to investigate whether there are an equal number of
persons of each sex in a population.   The sample chosen for invesigation
is that from the <filename>physiology.sav</filename> dataset.   The null hypothesis for
the test is that the population comprises an equal number of males and females.
The analysis is performed as shown in <link linkend="chisquare_003aex">chisquare:ex</link>.
</para>
<anchor id="chisquare_003aex"/>
<sidebar><screen>get file='physiology.sav'.

npar test
     /chisquare=sex.
</screen></sidebar>
<para>There is only one test variable, <emphasis>viz:</emphasis> <emphasis role="bold">sex</emphasis>.  The other variables in the dataset
are ignored.
</para>
<anchor id="chisquare_003ascr"/>
<sidebar></sidebar>
<para>In <link linkend="chisquare_003ares">chisquare:res</link> the summary box shows that in the sample, there are more males
than females.  However the significance of chi-square result is greater than 0.05
&#8212; the most commonly accepted p-value &#8212; and therefore
there is not enough evidence to reject the null hypothesis and one must conclude
that the evidence does not indicate that there is an imbalance of the sexes
in the population.
</para>
<anchor id="chisquare_003ares"/>
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>             Sex of subject
+------+----------+----------+--------+
|Value |Observed N|Expected N|Residual|
+------+----------+----------+--------+
|Male  |        22|     20.00|    2.00|
|Female|        18|     20.00|   -2.00|
|Total |        40|          |        |
+------+----------+----------+--------+

              Test Statistics
+--------------+----------+--+-----------+
|              |Chi-square|df|Asymp. Sig.|
+--------------+----------+--+-----------+
|Sex of subject|       .40| 1|       .527|
+--------------+----------+--+-----------+
</screen>

</sect3>
</sect2>
<sect2 label="15.12.3" id="COCHRAN">
<title>Cochran Q Test</title>
<indexterm role="vr"><primary>Cochran</primary></indexterm>
<indexterm role="cp"><primary>Cochran Q test</primary></indexterm>
<indexterm role="cp"><primary>Q, Cochran Q</primary></indexterm>

<literallayout>     [ /COCHRAN = <replaceable>var_list</replaceable> ]
</literallayout>
<para>The Cochran Q test is used to test for differences between three or more groups.
The data for <replaceable>var_list</replaceable> in all cases must assume exactly two
distinct values (other than missing values).
</para>
<para>The value of Q is displayed along with its Asymptotic significance
based on a chi-square distribution.
</para>
</sect2>
<sect2 label="15.12.4" id="FRIEDMAN">
<title>Friedman Test</title>
<indexterm role="vr"><primary>FRIEDMAN</primary></indexterm>
<indexterm role="cp"><primary>Friedman test</primary></indexterm>

<literallayout>     [ /FRIEDMAN = <replaceable>var_list</replaceable> ]
</literallayout>
<para>The Friedman test is used to test for differences between repeated measures when
there is no indication that the distributions are normally distributed.
</para>
<para>A list of variables which contain the measured data must be given.  The procedure
prints the sum of ranks for each variable, the test statistic and its significance.
</para>
</sect2>
<sect2 label="15.12.5" id="KENDALL">
<title>Kendall&#8217;s W Test</title>
<indexterm role="vr"><primary>KENDALL</primary></indexterm>
<indexterm role="cp"><primary>Kendall&#8217;s W test</primary></indexterm>
<indexterm role="cp"><primary>coefficient of concordance</primary></indexterm>

<literallayout>     [ /KENDALL = <replaceable>var_list</replaceable> ]
</literallayout>
<para>The Kendall test investigates whether an arbitrary number of related samples come from the
same population.
It is identical to the Friedman test except that the additional statistic W, Kendall&#8217;s Coefficient of Concordance is printed.
It has the range [0,1] &#8212; a value of zero indicates no agreement between the samples whereas a value of
unity indicates complete agreement.
</para>

</sect2>
<sect2 label="15.12.6" id="KOLMOGOROV_002dSMIRNOV">
<title>Kolmogorov-Smirnov Test</title>
<indexterm role="vr"><primary>KOLMOGOROV-SMIRNOV</primary></indexterm>
<indexterm role="vr"><primary>K-S</primary></indexterm>
<indexterm role="cp"><primary>Kolmogorov-Smirnov test</primary></indexterm>

<literallayout>     [ /KOLMOGOROV-SMIRNOV ({NORMAL [<replaceable>mu</replaceable>, <replaceable>sigma</replaceable>], UNIFORM [<replaceable>min</replaceable>, <replaceable>max</replaceable>], POISSON [<replaceable>lambda</replaceable>], EXPONENTIAL [<replaceable>scale</replaceable>] }) = <replaceable>var_list</replaceable> ]
</literallayout>
<para>The one-sample Kolmogorov-Smirnov subcommand is used to test whether or not a dataset is
drawn from a particular distribution.  Four distributions are supported, <emphasis>viz:</emphasis>
Normal, Uniform, Poisson and Exponential.
</para>
<para>Ideally you should provide the parameters of the distribution against
which you wish to test the data. For example, with the normal
distribution  the mean (<replaceable>mu</replaceable>)and standard deviation (<replaceable>sigma</replaceable>)
should be given; with the uniform distribution, the minimum
(<replaceable>min</replaceable>)and maximum (<replaceable>max</replaceable>) value should be provided.
However, if the parameters are omitted they are imputed from the
data.  Imputing the parameters reduces the power of the test so should
be avoided if possible.
</para>
<para>In the following example, two variables <replaceable>score</replaceable> and <replaceable>age</replaceable> are
tested to see if they follow a normal distribution with a mean of 3.5
and a standard deviation of 2.0.
</para><screen>  NPAR TESTS
        /KOLMOGOROV-SMIRNOV (normal 3.5 2.0) = <replaceable>score</replaceable> <replaceable>age</replaceable>.
</screen><para>If the variables need to be tested against different distributions, then a separate
subcommand must be used.  For example the following syntax tests <replaceable>score</replaceable> against
a normal distribution with mean of 3.5 and standard deviation of 2.0 whilst <replaceable>age</replaceable>
is tested against a normal distribution of mean 40 and standard deviation 1.5.
</para><screen>  NPAR TESTS
        /KOLMOGOROV-SMIRNOV (normal 3.5 2.0) = <replaceable>score</replaceable>
        /KOLMOGOROV-SMIRNOV (normal 40 1.5) =  <replaceable>age</replaceable>.
</screen>
<para>The abbreviated subcommand  <literal>K-S</literal> may be used in place of <literal>KOLMOGOROV-SMIRNOV</literal>.
</para>
</sect2>
<sect2 label="15.12.7" id="KRUSKAL_002dWALLIS">
<title>Kruskal-Wallis Test</title>
<indexterm role="vr"><primary>KRUSKAL-WALLIS</primary></indexterm>
<indexterm role="vr"><primary>K-W</primary></indexterm>
<indexterm role="cp"><primary>Kruskal-Wallis test</primary></indexterm>

<literallayout>     [ /KRUSKAL-WALLIS = <replaceable>var_list</replaceable> BY var (<replaceable>lower</replaceable>, <replaceable>upper</replaceable>) ]
</literallayout>
<para>The Kruskal-Wallis test is used to compare data from an
arbitrary number of populations.  It does not assume normality.
The data to be compared are specified by <replaceable>var_list</replaceable>.
The categorical variable determining the groups to which the
data belongs is given by <replaceable>var</replaceable>. The limits <replaceable>lower</replaceable> and
<replaceable>upper</replaceable> specify the valid range of <replaceable>var</replaceable>.
If <replaceable>upper</replaceable> is smaller than <replaceable>lower</replaceable>, the PSPP will assume their values
to be reversed. Any cases for which <replaceable>var</replaceable> falls outside
[<replaceable>lower</replaceable>, <replaceable>upper</replaceable>] are ignored.
</para>
<para>The mean rank of each group as well as the chi-squared value and
significance of the test are printed.
The abbreviated subcommand  <literal>K-W</literal> may be used in place of
<literal>KRUSKAL-WALLIS</literal>.
</para>

</sect2>
<sect2 label="15.12.8" id="MANN_002dWHITNEY">
<title>Mann-Whitney U Test</title>
<indexterm role="vr"><primary>MANN-WHITNEY</primary></indexterm>
<indexterm role="vr"><primary>M-W</primary></indexterm>
<indexterm role="cp"><primary>Mann-Whitney U test</primary></indexterm>
<indexterm role="cp"><primary>U, Mann-Whitney U</primary></indexterm>

<literallayout>     [ /MANN-WHITNEY = <replaceable>var_list</replaceable> BY var (<replaceable>group1</replaceable>, <replaceable>group2</replaceable>) ]
</literallayout>
<para>The Mann-Whitney subcommand is used to test whether two groups of data
come from different populations. The variables to be tested should be
specified in <replaceable>var_list</replaceable> and the grouping variable, that determines
to which group the test variables belong, in <replaceable>var</replaceable>.
<replaceable>Var</replaceable> may be either a string or an alpha variable.
<replaceable>Group1</replaceable> and <replaceable>group2</replaceable> specify the
two values of <replaceable>var</replaceable> which determine the groups of the test data.
Cases for which the <replaceable>var</replaceable> value is neither <replaceable>group1</replaceable> or
<replaceable>group2</replaceable> are ignored.
</para>
<para>The value of the Mann-Whitney U statistic, the Wilcoxon W, and the
significance are printed.
You may abbreviated the subcommand <literal>MANN-WHITNEY</literal> to
<literal>M-W</literal>.
</para>

</sect2>
<sect2 label="15.12.9" id="MCNEMAR">
<title>McNemar Test</title>
<indexterm role="vr"><primary>MCNEMAR</primary></indexterm>
<indexterm role="cp"><primary>McNemar test</primary></indexterm>

<literallayout>     [ /MCNEMAR <replaceable>var_list</replaceable> [ WITH <replaceable>var_list</replaceable> [ (PAIRED) ]]]
</literallayout>
<para>Use McNemar&#8217;s test to analyse the significance of the difference between
pairs of correlated proportions.
</para>
<para>If the <literal>WITH</literal> keyword is omitted, then tests for all
combinations of the listed variables are performed.
If the <literal>WITH</literal> keyword is given, and the <literal>(PAIRED)</literal> keyword
is also given, then the number of variables preceding <literal>WITH</literal>
must be the same as the number following it.
In this case, tests for each respective pair of variables are
performed.
If the <literal>WITH</literal> keyword is given, but the
<literal>(PAIRED)</literal> keyword is omitted, then tests for each combination
of variable preceding <literal>WITH</literal> against variable following
<literal>WITH</literal> are performed.
</para>
<para>The data in each variable must be dichotomous.  If there are more
than two distinct variables an error will occur and the test will
not be run.
</para>
</sect2>
<sect2 label="15.12.10" id="MEDIAN">
<title>Median Test</title>
<indexterm role="vr"><primary>MEDIAN</primary></indexterm>
<indexterm role="cp"><primary>Median test</primary></indexterm>

<literallayout>     [ /MEDIAN [(<replaceable>value</replaceable>)] = <replaceable>var_list</replaceable> BY <replaceable>variable</replaceable> (<replaceable>value1</replaceable>, <replaceable>value2</replaceable>) ]
</literallayout>
<para>The median test is used to test whether independent samples come from
populations with a common median.
The median of the populations against which the samples are to be tested
may be given in parentheses immediately after the
<literal>/MEDIAN</literal> subcommand.  If it is not given, the median is imputed from the
union of all the samples.
</para>
<para>The variables of the samples to be tested should immediately follow the &#8216;<literal>=</literal>&#8217; sign. The
keyword <literal>BY</literal> must come next, and then the grouping variable.  Two values
in parentheses should follow.  If the first value is greater than the second,
then a 2 sample test is performed using these two values to determine the groups.
If however, the first variable is less than the second, then a <emphasis>k</emphasis> sample test is
conducted and the group values used are all values encountered which lie in the
range [<replaceable>value1</replaceable>,<replaceable>value2</replaceable>].
</para>

</sect2>
<sect2 label="15.12.11" id="RUNS">
<title>Runs Test</title>
<indexterm role="vr"><primary>RUNS</primary></indexterm>
<indexterm role="cp"><primary>runs test</primary></indexterm>

<literallayout>     [ /RUNS ({MEAN, MEDIAN, MODE, <replaceable>value</replaceable>})  = <replaceable>var_list</replaceable> ]
</literallayout>
<para>The <literal>/RUNS</literal> subcommand tests whether a data sequence is randomly ordered.
</para>
<para>It works by examining the number of times a variable&#8217;s value crosses a given threshold.
The desired threshold must be specified within parentheses.
It may either be specified as a number or as one of <literal>MEAN</literal>, <literal>MEDIAN</literal> or <literal>MODE</literal>.
Following the threshold specification comes the list of variables whose values are to be
tested.
</para>
<para>The subcommand shows the number of runs, the asymptotic significance based on the
length of the data.
</para>
</sect2>
<sect2 label="15.12.12" id="SIGN">
<title>Sign Test</title>
<indexterm role="vr"><primary>SIGN</primary></indexterm>
<indexterm role="cp"><primary>sign test</primary></indexterm>

<literallayout>     [ /SIGN <replaceable>var_list</replaceable> [ WITH <replaceable>var_list</replaceable> [ (PAIRED) ]]]
</literallayout>
<para>The <literal>/SIGN</literal> subcommand tests for differences between medians of the
variables listed.
The test does not make any assumptions about the
distribution of the data.
</para>
<para>If the <literal>WITH</literal> keyword is omitted, then tests for all
combinations of the listed variables are performed.
If the <literal>WITH</literal> keyword is given, and the <literal>(PAIRED)</literal> keyword
is also given, then the number of variables preceding <literal>WITH</literal>
must be the same as the number following it.
In this case, tests for each respective pair of variables are
performed.
If the <literal>WITH</literal> keyword is given, but the
<literal>(PAIRED)</literal> keyword is omitted, then tests for each combination
of variable preceding <literal>WITH</literal> against variable following
<literal>WITH</literal> are performed.
</para>
</sect2>
<sect2 label="15.12.13" id="WILCOXON">
<title>Wilcoxon Matched Pairs Signed Ranks Test</title>
<indexterm role="vr"><primary>WILCOXON</primary></indexterm>
<indexterm role="cp"><primary>wilcoxon matched pairs signed ranks test</primary></indexterm>

<literallayout>     [ /WILCOXON <replaceable>var_list</replaceable> [ WITH <replaceable>var_list</replaceable> [ (PAIRED) ]]]
</literallayout>
<para>The <literal>/WILCOXON</literal> subcommand tests for differences between medians of the
variables listed.
The test does not make any assumptions about the variances of the samples.
It does however assume that the distribution is symmetrical.
</para>
<para>If the <literal>WITH</literal> keyword is omitted, then tests for all
combinations of the listed variables are performed.
If the <literal>WITH</literal> keyword is given, and the <literal>(PAIRED)</literal> keyword
is also given, then the number of variables preceding <literal>WITH</literal>
must be the same as the number following it.
In this case, tests for each respective pair of variables are
performed.
If the <literal>WITH</literal> keyword is given, but the
<literal>(PAIRED)</literal> keyword is omitted, then tests for each combination
of variable preceding <literal>WITH</literal> against variable following
<literal>WITH</literal> are performed.
</para>
</sect2>
</sect1>
<sect1 label="15.13" id="T_002dTEST">
<title>T-TEST</title>

<indexterm role="vr"><primary>T-TEST</primary></indexterm>

<literallayout>T-TEST
        /MISSING={ANALYSIS,LISTWISE} {EXCLUDE,INCLUDE}
        /CRITERIA=CI(<replaceable>confidence</replaceable>)


(One Sample mode.)
        TESTVAL=<replaceable>test_value</replaceable>
        /VARIABLES=<replaceable>var_list</replaceable>


(Independent Samples mode.)
        GROUPS=var(<replaceable>value1</replaceable> [, <replaceable>value2</replaceable>])
        /VARIABLES=<replaceable>var_list</replaceable>


(Paired Samples mode.)
        PAIRS=<replaceable>var_list</replaceable> [WITH <replaceable>var_list</replaceable> [(PAIRED)] ]

</literallayout>

<para>The <literal>T-TEST</literal> procedure outputs tables used in testing hypotheses about
means.
It operates in one of three modes:
</para><itemizedlist><listitem><para>One Sample mode.
</para></listitem><listitem><para>Independent Groups mode.
</para></listitem><listitem><para>Paired mode.
</para></listitem></itemizedlist>
<para>Each of these modes are described in more detail below.
There are two optional subcommands which are common to all modes.
</para>
<para>The <literal>/CRITERIA</literal> subcommand tells PSPP the confidence interval used
in the tests.  The default value is 0.95.
</para>

<para>The <literal>MISSING</literal> subcommand determines the handling of missing
variables.
If <literal>INCLUDE</literal> is set, then user-missing values are included in the
calculations, but system-missing values are not.
If <literal>EXCLUDE</literal> is set, which is the default, user-missing
values are excluded as well as system-missing values.
This is the default.
</para>
<para>If <literal>LISTWISE</literal> is set, then the entire case is excluded from analysis
whenever any variable  specified in the <literal>/VARIABLES</literal>, <literal>/PAIRS</literal> or
<literal>/GROUPS</literal> subcommands contains a missing value.
If <literal>ANALYSIS</literal> is set, then missing values are excluded only in the analysis for
which they would be needed. This is the default.
</para>


<sect2 label="15.13.1" id="One-Sample-Mode">
<title>One Sample Mode</title>

<para>The <literal>TESTVAL</literal> subcommand invokes the One Sample mode.
This mode is used to test a population mean against a hypothesized
mean.
The value given to the <literal>TESTVAL</literal> subcommand is the value against
which you wish to test.
In this mode, you must also use the <literal>/VARIABLES</literal> subcommand to
tell PSPP which variables you wish to test.
</para>
<sect3 label="15.13.1.1">
<title>Example - One-Sample T-test</title>

<para>A researcher wishes to know whether the weight of persons in a population
is different from the national average.
The samples are drawn from the population under investigation and recorded
in the file <filename>physiology.sav</filename>.
From the Department of Health, she
knows that the national average weight of healthy adults is 76.8kg.
Accordingly the <literal>TESTVAL</literal> is set to 76.8.
The null hypothesis therefore is that the mean average weight of the
population from which the sample was drawn is 76.8kg.
</para>
<para>As previously noted (see <link linkend="Identifying-incorrect-data">Identifying incorrect data</link>), one
sample in the dataset contains a weight value
which is clearly incorrect.  So this is excluded from the analysis
using the <literal>SELECT</literal> command.
</para>
<anchor id="one_002dsample_002dt_003aex"/>
<sidebar><screen>get file='physiology.sav'.

select if (weight &gt; 0).

t-test testval = 76.8
	/variables = weight.
</screen></sidebar>
<anchor id="one_002dsample_002dt_003ascr"/>
<sidebar></sidebar>

<para><link linkend="one_002dsample_002dt_003ares">one-sample-t:res</link> shows that the mean of our sample differs from the test value
by -1.40kg.  However the significance is very high (0.610).  So one cannot
reject the null hypothesis, and must conclude there is not enough evidence
to suggest that the mean weight of the persons in our population is different
from 76.8kg.
</para>
<anchor id="one_002dsample_002dt_003ares"/>
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                 One-Sample Statistics
+-------------------+--+-----+--------------+---------+
|                   | N| Mean|Std. Deviation|S.E. Mean|
+-------------------+--+-----+--------------+---------+
|Weight in kilograms|39|75.40|         17.08|     2.73|
+-------------------+--+-----+--------------+---------+

                                One-Sample Test
+--------------+--------------------------------------------------------------+
|              |                       Test Value = 76.8                      |
|              +----+--+------------+------------+----------------------------+
|              |    |  |            |            | 95% Confidence Interval of |
|              |    |  |            |            |       the Difference       |
|              |    |  |  Sig. (2-  |    Mean    +--------------+-------------+
|              |  t |df|   tailed)  | Difference |     Lower    |    Upper    |
+--------------+----+--+------------+------------+--------------+-------------+
|Weight in     |-.51|38|        .610|       -1.40|         -6.94|         4.13|
|kilograms     |    |  |            |            |              |             |
+--------------+----+--+------------+------------+--------------+-------------+
</screen>
</sect3>
</sect2>
<sect2 label="15.13.2" id="Independent-Samples-Mode">
<title>Independent Samples Mode</title>

<para>The <literal>GROUPS</literal> subcommand invokes Independent Samples mode or
&#8216;Groups&#8217; mode.
This mode is used to test whether two groups of values have the
same population mean.
In this mode, you must also use the <literal>/VARIABLES</literal> subcommand to
tell PSPP the dependent variables you wish to test.
</para>
<para>The variable given in the <literal>GROUPS</literal> subcommand is the independent
variable which determines to which group the samples belong.
The values in parentheses are the specific values of the independent
variable for each group.
If the parentheses are omitted and no values are given, the default values
of 1.0 and 2.0 are assumed.
</para>
<para>If the independent variable is numeric,
it is acceptable to specify only one value inside the parentheses.
If you do this, cases where the independent variable is
greater than or equal to this value belong to the first group, and cases
less than this value belong to the second group.
When using this form of the <literal>GROUPS</literal> subcommand, missing values in
the independent variable are excluded on a listwise basis, regardless
of whether <literal>/MISSING=LISTWISE</literal> was specified.
</para>
<sect3 label="15.13.2.1">
<title>Example - Independent Samples T-test</title>

<para>A researcher wishes to know whether within a population, adult males
are taller than adult females.
The samples are drawn from the population under investigation and recorded
in the file <filename>physiology.sav</filename>.
</para>
<para>As previously noted (see <link linkend="Identifying-incorrect-data">Identifying incorrect data</link>), one
sample in the dataset contains a height value
which is clearly incorrect.  So this is excluded from the analysis
using the <literal>SELECT</literal> command.
</para>

<anchor id="indepdendent_002dsamples_002dt_003aex"/>
<sidebar><screen>get file='physiology.sav'.

select if (height &gt;= 200).

t-test /variables = height
       /groups = sex(0,1).
</screen></sidebar>

<para>The null hypothesis is that both males and females are on average
of equal height.
</para>
<anchor id="independent_002dsamples_002dt_003ascr"/>
<sidebar></sidebar>

<para>In this case, the grouping variable is <emphasis role="bold">sex</emphasis>, so this is entered
as the variable for the <literal>GROUP</literal> subcommand.  The group values are  0 (male) and
1 (female).
</para>
<para>If you are running the proceedure using syntax, then you need to enter
the values corresponding to each group within parentheses.
If you are using the graphic user interface, then you have to open
the &#8220;Define Groups&#8221; dialog box and enter the values corresponding
to each group as shown in <link linkend="define_002dgroups_002dt_003ascr">define-groups-t:scr</link>.  If, as in this case, the dataset has defined value
labels for the group variable, then you can enter them by label
or by value.
</para>
<anchor id="define_002dgroups_002dt_003ascr"/>
<sidebar></sidebar>
<para>From <link linkend="independent_002dsamples_002dt_003ares">independent-samples-t:res</link>, one can clearly see that the <emphasis>sample</emphasis> mean height
is greater for males than for females.  However in order to see if this
is a significant result, one must consult the T-Test table.
</para>
<para>The T-Test table contains two rows; one for use if the variance of the samples
in each group may be safely assumed to be equal, and the second row
if the variances in each group may not be safely assumed to be equal.
</para>
<para>In this case however, both rows show a 2-tailed significance less than 0.001 and
one must therefore reject the null hypothesis and conclude that within
the population the mean height of males and of females are unequal.
</para>
<anchor id="independent_002dsamples_002dt_003ares"/>
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>                         Group Statistics
+----------------------------+--+-------+--------------+---------+
|                      Group | N|  Mean |Std. Deviation|S.E. Mean|
+----------------------------+--+-------+--------------+---------+
|Height in millimeters Male  |22|1796.49|         49.71|    10.60|
|                      Female|17|1610.77|         25.43|     6.17|
+----------------------------+--+-------+--------------+---------+

                          Independent Samples Test
+---------------------+----------+------------------------------------------
|                     | Levene's |
|                     | Test for |
|                     | Equality |
|                     |    of    |
|                     | Variances|              T-Test for Equality of Means
|                     +----+-----+-----+-----+-------+----------+----------+
|                     |    |     |     |     |       |          |          |
|                     |    |     |     |     |       |          |          |
|                     |    |     |     |     |       |          |          |
|                     |    |     |     |     |       |          |          |
|                     |    |     |     |     |  Sig. |          |          |
|                     |    |     |     |     |  (2-  |   Mean   |Std. Error|
|                     |  F | Sig.|  t  |  df |tailed)|Difference|Difference|
+---------------------+----+-----+-----+-----+-------+----------+----------+
|Height in   Equal    | .97| .331|14.02|37.00|   .000|    185.72|     13.24|
|millimeters variances|    |     |     |     |       |          |          |
|            assumed  |    |     |     |     |       |          |          |
|            Equal    |    |     |15.15|32.71|   .000|    185.72|     12.26|
|            variances|    |     |     |     |       |          |          |
|            not      |    |     |     |     |       |          |          |
|            assumed  |    |     |     |     |       |          |          |
+---------------------+----+-----+-----+-----+-------+----------+----------+

+---------------------+-------------+
|                     |             |
|                     |             |
|                     |             |
|                     |             |
|                     |             |
|                     +-------------+
|                     |     95%     |
|                     |  Confidence |
|                     | Interval of |
|                     |     the     |
|                     |  Difference |
|                     +------+------+
|                     | Lower| Upper|
+---------------------+------+------+
|Height in   Equal    |158.88|212.55|
|millimeters variances|      |      |
|            assumed  |      |      |
|            Equal    |160.76|210.67|
|            variances|      |      |
|            not      |      |      |
|            assumed  |      |      |
+---------------------+------+------+
</screen>
</sect3>
</sect2>
<sect2 label="15.13.3" id="Paired-Samples-Mode">
<title>Paired Samples Mode</title>

<para>The <literal>PAIRS</literal> subcommand introduces Paired Samples mode.
Use this mode when repeated measures have been taken from the same
samples.
If the <literal>WITH</literal> keyword is omitted, then tables for all
combinations of variables given in the <literal>PAIRS</literal> subcommand are
generated.
If the <literal>WITH</literal> keyword is given, and the <literal>(PAIRED)</literal> keyword
is also given, then the number of variables preceding <literal>WITH</literal>
must be the same as the number following it.
In this case, tables for each respective pair of variables are
generated.
In the event that the <literal>WITH</literal> keyword is given, but the
<literal>(PAIRED)</literal> keyword is omitted, then tables for each combination
of variable preceding <literal>WITH</literal> against variable following
<literal>WITH</literal> are generated.
</para>

</sect2>
</sect1>
<sect1 label="15.14" id="ONEWAY">
<title>ONEWAY</title>

<indexterm role="vr"><primary>ONEWAY</primary></indexterm>
<indexterm role="cp"><primary>analysis of variance</primary></indexterm>
<indexterm role="cp"><primary>ANOVA</primary></indexterm>

<literallayout>ONEWAY
        [/VARIABLES = ] <replaceable>var_list</replaceable> BY <replaceable>var</replaceable>
        /MISSING={ANALYSIS,LISTWISE} {EXCLUDE,INCLUDE}
        /CONTRAST= <replaceable>value1</replaceable> [, <replaceable>value2</replaceable>] ... [,<replaceable>valueN</replaceable>]
        /STATISTICS={DESCRIPTIVES,HOMOGENEITY}
        /POSTHOC={BONFERRONI, GH, LSD, SCHEFFE, SIDAK, TUKEY, ALPHA ([<replaceable>value</replaceable>])}
</literallayout>
<para>The <literal>ONEWAY</literal> procedure performs a one-way analysis of variance of
variables factored by a single independent variable.
It is used to compare the means of a population
divided into more than two groups.
</para>
<para>The dependent variables to be analysed should be given in the <literal>VARIABLES</literal>
subcommand.
The list of variables must be followed by the <literal>BY</literal> keyword and
the name of the independent (or factor) variable.
</para>
<para>You can use the <literal>STATISTICS</literal> subcommand to tell PSPP to display
ancillary information.  The options accepted are:
</para><itemizedlist><listitem><para>DESCRIPTIVES
Displays descriptive statistics about the groups factored by the independent
variable.
</para></listitem><listitem><para>HOMOGENEITY
Displays the Levene test of Homogeneity of Variance for the
variables and their groups.
</para></listitem></itemizedlist>
<para>The <literal>CONTRAST</literal> subcommand is used when you anticipate certain
differences between the groups.
The subcommand must be followed by a list of numerals which are the
coefficients of the groups to be tested.
The number of coefficients must correspond to the number of distinct
groups (or values of the independent variable).
If the total sum of the coefficients are not zero, then PSPP will
display a warning, but will proceed with the analysis.
The <literal>CONTRAST</literal> subcommand may be given up to 10 times in order
to specify different contrast tests.
The <literal>MISSING</literal> subcommand defines how missing values are handled.
If <literal>LISTWISE</literal> is specified then cases which have missing values for
the independent variable or any dependent variable are ignored.
If <literal>ANALYSIS</literal> is specified, then cases are ignored if the independent
variable is missing or if the dependent variable currently being
analysed is missing.  The default is <literal>ANALYSIS</literal>.
A setting of <literal>EXCLUDE</literal> means that variables whose values are
user-missing are to be excluded from the analysis. A setting of
<literal>INCLUDE</literal> means they are to be included.  The default is <literal>EXCLUDE</literal>.
</para>
<para>Using the <literal>POSTHOC</literal> subcommand you can perform multiple
pairwise comparisons on the data. The following comparison methods
are available:
</para><itemizedlist><listitem><para><literal>LSD</literal>
Least Significant Difference.
</para></listitem><listitem><para><literal>TUKEY</literal>
Tukey Honestly Significant Difference.
</para></listitem><listitem><para><literal>BONFERRONI</literal>
Bonferroni test.
</para></listitem><listitem><para><literal>SCHEFFE</literal>
Scheff&#233;&#8217;s test.
</para></listitem><listitem><para><literal>SIDAK</literal>
Sidak test.
</para></listitem><listitem><para><literal>GH</literal>
The Games-Howell test.
</para></listitem></itemizedlist>
<para>Use the optional syntax <literal>ALPHA(<replaceable>value</replaceable>)</literal> to indicate that
<literal>ONEWAY</literal> should perform the posthoc tests at a confidence level of
<replaceable>value</replaceable>.  If <literal>ALPHA(<replaceable>value</replaceable>)</literal> is not specified, then the
confidence level used is 0.05.
</para>
</sect1>
<sect1 label="15.15" id="QUICK-CLUSTER">
<title>QUICK CLUSTER</title>
<indexterm role="vr"><primary>QUICK CLUSTER</primary></indexterm>

<indexterm role="cp"><primary>K-means clustering</primary></indexterm>
<indexterm role="cp"><primary>clustering</primary></indexterm>

<literallayout>QUICK CLUSTER <replaceable>var_list</replaceable>
      [/CRITERIA=CLUSTERS(<replaceable>k</replaceable>) [MXITER(<replaceable>max_iter</replaceable>)] CONVERGE(<replaceable>epsilon</replaceable>) [NOINITIAL]]
      [/MISSING={EXCLUDE,INCLUDE} {LISTWISE, PAIRWISE}]
      [/PRINT={INITIAL} {CLUSTER}]
      [/SAVE[=[CLUSTER[(<replaceable>membership_var</replaceable>)]] [DISTANCE[(<replaceable>distance_var</replaceable>)]]]
</literallayout>
<para>The <literal>QUICK CLUSTER</literal> command performs k-means clustering on the
dataset.  This is useful when you wish to allocate cases into clusters
of similar values and you already know the number of clusters.
</para>
<para>The minimum specification is &#8216;<literal>QUICK CLUSTER</literal>&#8217; followed by the names
of the variables which contain the cluster data.  Normally you will also
want to specify <literal>/CRITERIA=CLUSTERS(<replaceable>k</replaceable>)</literal> where <replaceable>k</replaceable> is the
number of clusters.  If this is not specified, then <replaceable>k</replaceable> defaults to 2.
</para>
<para>If you use <literal>/CRITERIA=NOINITIAL</literal> then a naive algorithm to select
the initial clusters is used.   This will provide for faster execution but
less well separated initial clusters and hence possibly an inferior final
result.
</para>

<para><literal>QUICK CLUSTER</literal> uses an iterative algorithm to select the clusters centers.
The subcommand  <literal>/CRITERIA=MXITER(<replaceable>max_iter</replaceable>)</literal> sets the maximum number of iterations.
During classification, PSPP will continue iterating until until <replaceable>max_iter</replaceable>
iterations have been done or the convergence criterion (see below) is fulfilled.
The default value of <replaceable>max_iter</replaceable> is 2.
</para>
<para>If however, you specify <literal>/CRITERIA=NOUPDATE</literal> then after selecting the initial centers,
no further update to the cluster centers is done.  In this case, <replaceable>max_iter</replaceable>, if specified.
is ignored.
</para>
<para>The subcommand  <literal>/CRITERIA=CONVERGE(<replaceable>epsilon</replaceable>)</literal> is used
to set the convergence criterion.  The value of convergence criterion is  <replaceable>epsilon</replaceable>
times the minimum distance between the <emphasis>initial</emphasis> cluster centers.  Iteration stops when
the  mean cluster distance between  one iteration and the next
is less than the convergence criterion.  The default value of <replaceable>epsilon</replaceable> is zero.
</para>
<para>The <literal>MISSING</literal> subcommand determines the handling of missing variables.
If <literal>INCLUDE</literal> is set, then user-missing values are considered at their face
value and not as missing values.
If <literal>EXCLUDE</literal> is set, which is the default, user-missing
values are excluded as well as system-missing values.
</para>
<para>If <literal>LISTWISE</literal> is set, then the entire case is excluded from the analysis
whenever any of the clustering variables contains a missing value.
If <literal>PAIRWISE</literal> is set, then a case is considered missing only if all the
clustering variables contain missing values.  Otherwise it is clustered
on the basis of the non-missing values.
The default is <literal>LISTWISE</literal>.
</para>
<para>The <literal>PRINT</literal> subcommand requests additional output to be printed.
If <literal>INITIAL</literal> is set, then the initial cluster memberships will
be printed.
If <literal>CLUSTER</literal> is set, the cluster memberships of the individual
cases are displayed (potentially generating lengthy output).
</para>
<para>You can specify the subcommand <literal>SAVE</literal> to ask that each case&#8217;s cluster membership
and the euclidean distance between the case and its cluster center be saved to
a new variable in the active dataset.   To save the cluster membership use the
<literal>CLUSTER</literal> keyword and to save the distance use the <literal>DISTANCE</literal> keyword.
Each keyword may optionally be followed by a variable name in parentheses to specify
the new variable which is to contain the saved parameter.  If no variable name is specified,
then PSPP will create one.
</para>
</sect1>
<sect1 label="15.16" id="RANK">
<title>RANK</title>

<indexterm role="vr"><primary>RANK</primary></indexterm>
<literallayout>RANK
        [VARIABLES=] <replaceable>var_list</replaceable> [{A,D}] [BY <replaceable>var_list</replaceable>]
        /TIES={MEAN,LOW,HIGH,CONDENSE}
        /FRACTION={BLOM,TUKEY,VW,RANKIT}
        /PRINT[={YES,NO}
        /MISSING={EXCLUDE,INCLUDE}

        /RANK [INTO <replaceable>var_list</replaceable>]
        /NTILES(k) [INTO <replaceable>var_list</replaceable>]
        /NORMAL [INTO <replaceable>var_list</replaceable>]
        /PERCENT [INTO <replaceable>var_list</replaceable>]
        /RFRACTION [INTO <replaceable>var_list</replaceable>]
        /PROPORTION [INTO <replaceable>var_list</replaceable>]
        /N [INTO <replaceable>var_list</replaceable>]
        /SAVAGE [INTO <replaceable>var_list</replaceable>]
</literallayout>
<para>The <literal>RANK</literal> command ranks variables and stores the results into new
variables.
</para>
<para>The <literal>VARIABLES</literal> subcommand, which is mandatory, specifies one or
more variables whose values are to be ranked.
After each variable, &#8216;<literal>A</literal>&#8217; or &#8216;<literal>D</literal>&#8217; may appear, indicating that
the variable is to be ranked in ascending or descending order.
Ascending is the default.
If a <literal>BY</literal> keyword appears, it should be followed by a list of variables
which are to serve as group variables.
In this case, the cases are gathered into groups, and ranks calculated
for each group.
</para>
<para>The <literal>TIES</literal> subcommand specifies how tied values are to be treated.  The
default is to take the mean value of all the tied cases.
</para>
<para>The <literal>FRACTION</literal> subcommand specifies how proportional ranks are to be
calculated.  This only has any effect if <literal>NORMAL</literal> or <literal>PROPORTIONAL</literal> rank
functions are requested.
</para>
<para>The <literal>PRINT</literal> subcommand may be used to specify that a summary of the rank
variables created should appear in the output.
</para>
<para>The function subcommands are <literal>RANK</literal>, <literal>NTILES</literal>, <literal>NORMAL</literal>, <literal>PERCENT</literal>, <literal>RFRACTION</literal>,
<literal>PROPORTION</literal> and <literal>SAVAGE</literal>.  Any number of function subcommands may appear.
If none are given, then the default is RANK.
The <literal>NTILES</literal> subcommand must take an integer specifying the number of
partitions into which values should be ranked.
Each subcommand may be followed by the <literal>INTO</literal> keyword and a list of
variables which are the variables to be created and receive the rank
scores.  There may be as many variables specified as there are
variables named on the <literal>VARIABLES</literal> subcommand.  If fewer are specified,
then the variable names are automatically created.
</para>
<para>The <literal>MISSING</literal> subcommand determines how user missing values are to be
treated. A setting of <literal>EXCLUDE</literal> means that variables whose values are
user-missing are to be excluded from the rank scores. A setting of
<literal>INCLUDE</literal> means they are to be included.  The default is <literal>EXCLUDE</literal>.
</para>
<!-- PSPP - a program for statistical analysis. -->
<!-- Copyright (C) 2017, 2020 Free Software Foundation, Inc. -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.3 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<!-- A copy of the license is included in the section entitled "GNU -->
<!-- Free Documentation License". -->
<!-- -->
</sect1>
<sect1 label="15.17" id="REGRESSION">
<title>REGRESSION</title>

<indexterm role="cp"><primary>regression</primary></indexterm>
<indexterm role="cp"><primary>linear regression</primary></indexterm>
<para>The <literal>REGRESSION</literal> procedure fits linear models to data via least-squares
estimation. The procedure is appropriate for data which satisfy those
assumptions typical in linear regression:
</para>
<itemizedlist><listitem><para>The data set contains <inlineequation><mathphrase>n</mathphrase></inlineequation> observations of a dependent variable, say
<inlineequation><mathphrase>Y_1,&#8230;,Y_n</mathphrase></inlineequation>, and <inlineequation><mathphrase>n</mathphrase></inlineequation> observations of one or more explanatory
variables.
Let <inlineequation><mathphrase>X_{11}, X_{12}</mathphrase></inlineequation>, &#8230;, <inlineequation><mathphrase>X_{1n}</mathphrase></inlineequation> denote the <inlineequation><mathphrase>n</mathphrase></inlineequation> observations
of the first explanatory variable;
<inlineequation><mathphrase>X_{21}</mathphrase></inlineequation>,&#8230;,<inlineequation><mathphrase>X_{2n}</mathphrase></inlineequation> denote the <inlineequation><mathphrase>n</mathphrase></inlineequation> observations of the second
explanatory variable;
<inlineequation><mathphrase>X_{k1}</mathphrase></inlineequation>,&#8230;,<inlineequation><mathphrase>X_{kn}</mathphrase></inlineequation> denote the <inlineequation><mathphrase>n</mathphrase></inlineequation> observations of
the <inlineequation><mathphrase>k</mathphrase></inlineequation>th explanatory variable.
</para>
</listitem><listitem><para>The dependent variable <inlineequation><mathphrase>Y</mathphrase></inlineequation> has the following relationship to the
explanatory variables:
<inlineequation><mathphrase>Y_i = b_0 + b_1 X_{1i} + ... + b_k X_{ki} + Z_i</mathphrase></inlineequation>
where <inlineequation><mathphrase>b_0, b_1, &#8230;, b_k</mathphrase></inlineequation> are unknown
coefficients, and <inlineequation><mathphrase>Z_1,&#8230;,Z_n</mathphrase></inlineequation> are independent, normally
distributed <firstterm>noise</firstterm> terms with mean zero and common variance.
The noise, or <firstterm>error</firstterm> terms are unobserved.
This relationship is called the <firstterm>linear model</firstterm>.
</para></listitem></itemizedlist>
<para>The <literal>REGRESSION</literal> procedure estimates the coefficients
<inlineequation><mathphrase>b_0,&#8230;,b_k</mathphrase></inlineequation> and produces output relevant to inferences for the
linear model.
</para>

<sect2 label="15.17.1" id="Syntax">
<title>Syntax</title>

<indexterm role="vr"><primary>REGRESSION</primary></indexterm>
<literallayout>REGRESSION
        /VARIABLES=<replaceable>var_list</replaceable>
        /DEPENDENT=<replaceable>var_list</replaceable>
        /STATISTICS={ALL, DEFAULTS, R, COEFF, ANOVA, BCOV, CI[<replaceable>conf</replaceable>, TOL]}
        { /ORIGIN | /NOORIGIN }
        /SAVE={PRED, RESID}
</literallayout>
<para>The <literal>REGRESSION</literal> procedure reads the active dataset and outputs
statistics relevant to the linear model specified by the user.
</para>
<para>The <literal>VARIABLES</literal> subcommand, which is required, specifies the list of
variables to be analyzed.  Keyword <literal>VARIABLES</literal> is required. The
<literal>DEPENDENT</literal> subcommand specifies the dependent variable of the linear
model. The <literal>DEPENDENT</literal> subcommand is required. All variables listed in
the <literal>VARIABLES</literal> subcommand, but not listed in the <literal>DEPENDENT</literal> subcommand,
are treated as explanatory variables in the linear model.
</para>
<para>All other subcommands are optional:
</para>
<para>The <literal>STATISTICS</literal> subcommand specifies which statistics are to be displayed.
The following keywords are accepted:
</para>
<variablelist><varlistentry><term><literal>ALL</literal>
</term><listitem><para>All of the statistics below.
</para></listitem></varlistentry><varlistentry><term><literal>R</literal>
</term><listitem><para>The ratio of the sums of squares due to the model to the total sums of
squares for the dependent variable.
</para></listitem></varlistentry><varlistentry><term><literal>COEFF</literal>
</term><listitem><para>A table containing the estimated model coefficients and their standard errors.
</para></listitem></varlistentry><varlistentry><term><literal>CI (<replaceable>conf</replaceable>)</literal>
</term><listitem><para>This item is only relevant if COEFF has also been selected.  It specifies that the
confidence interval for the coefficients should be printed.  The optional value <replaceable>conf</replaceable>,
which must be in parentheses, is the desired confidence level expressed as a percentage.
</para></listitem></varlistentry><varlistentry><term><literal>ANOVA</literal>
</term><listitem><para>Analysis of variance table for the model.
</para></listitem></varlistentry><varlistentry><term><literal>BCOV</literal>
</term><listitem><para>The covariance matrix for the estimated model coefficients.
</para></listitem></varlistentry><varlistentry><term><literal>TOL</literal>
</term><listitem><para>The variance inflation factor and its reciprocal.  This has no effect unless COEFF is also given.
</para></listitem></varlistentry><varlistentry><term><literal>DEFAULT</literal>
</term><listitem><para>The same as if R, COEFF, and ANOVA had been selected.
This is what you get if the /STATISTICS command is not specified,
or if it is specified without any parameters.
</para></listitem></varlistentry></variablelist>
<para>The <literal>ORIGIN</literal> and <literal>NOORIGIN</literal> subcommands are mutually
exclusive.  <literal>ORIGIN</literal> indicates that the regression should be
performed through the origin.  You should use this option if, and
only if you have reason to believe that the regression does indeed
pass through the origin &#8212; that is to say, the value <inlineequation><mathphrase>b_0</mathphrase></inlineequation> above,
is zero.  The default is <literal>NOORIGIN</literal>.
</para>
<para>The <literal>SAVE</literal> subcommand causes PSPP to save the residuals or predicted
values from the fitted
model to the active dataset. PSPP will store the residuals in a variable
called &#8216;<literal>RES1</literal>&#8217; if no such variable exists, &#8216;<literal>RES2</literal>&#8217; if &#8216;<literal>RES1</literal>&#8217;
already exists,
&#8216;<literal>RES3</literal>&#8217; if &#8216;<literal>RES1</literal>&#8217; and &#8216;<literal>RES2</literal>&#8217; already exist, etc. It will
choose the name of
the variable for the predicted values similarly, but with &#8216;<literal>PRED</literal>&#8217; as a
prefix.
When <literal>SAVE</literal> is used, PSPP ignores <literal>FILTER</literal>, processing
every case, and <literal>TEMPORARY</literal>, treating temporary transformations as
permanent.
</para>
</sect2>
<sect2 label="15.17.2" id="Examples">
<title>Examples</title>
<para>The following PSPP syntax will generate the default output and save the
predicted values and residuals to the active dataset.
</para>
<screen>title 'Demonstrate REGRESSION procedure'.
data list / v0 1-2 (A) v1 v2 3-22 (10).
begin data.
b  7.735648 -23.97588
b  6.142625 -19.63854
a  7.651430 -25.26557
c  6.125125 -16.57090
a  8.245789 -25.80001
c  6.031540 -17.56743
a  9.832291 -28.35977
c  5.343832 -16.79548
a  8.838262 -29.25689
b  6.200189 -18.58219
end data.
list.
regression /variables=v0 v1 v2 /statistics defaults /dependent=v2
           /save pred resid /method=enter.
</screen>

</sect2>
</sect1>
<sect1 label="15.18" id="RELIABILITY">
<title>RELIABILITY</title>

<indexterm role="vr"><primary>RELIABILITY</primary></indexterm>
<literallayout>RELIABILITY
        /VARIABLES=<replaceable>var_list</replaceable>
        /SCALE (<replaceable>name</replaceable>) = {<replaceable>var_list</replaceable>, ALL}
        /MODEL={ALPHA, SPLIT[(<replaceable>n</replaceable>)]}
        /SUMMARY={TOTAL,ALL}
        /MISSING={EXCLUDE,INCLUDE}
</literallayout>
<indexterm role="cp"><primary>Cronbach&#8217;s Alpha</primary></indexterm>
<para>The <literal>RELIABILITY</literal> command performs reliability analysis on the data.
</para>
<para>The <literal>VARIABLES</literal> subcommand is required. It determines the set of variables
upon which analysis is to be performed.
</para>
<para>The <literal>SCALE</literal> subcommand determines the  variables for which
reliability is to be calculated.  If <literal>SCALE</literal> is omitted, then analysis for
all variables named in the <literal>VARIABLES</literal> subcommand are used.
Optionally, the <replaceable>name</replaceable> parameter may be specified to set a string name
for the scale.
</para>
<para>The <literal>MODEL</literal> subcommand determines the type of analysis. If <literal>ALPHA</literal> is specified,
then Cronbach&#8217;s Alpha is calculated for the scale.  If the model is <literal>SPLIT</literal>,
then the variables  are divided into 2 subsets.  An optional parameter
<replaceable>n</replaceable> may be given, to specify how many variables to be in the first subset.
If <replaceable>n</replaceable> is omitted, then it defaults to one half of the variables in the
scale, or one half minus one if there are an odd number of variables.
The default model is <literal>ALPHA</literal>.
</para>
<para>By default, any cases with user missing, or system missing values for
any variables given in the <literal>VARIABLES</literal> subcommand are omitted
from the analysis.  The <literal>MISSING</literal> subcommand determines whether
user missing values are included or excluded in the analysis.
</para>
<para>The <literal>SUMMARY</literal> subcommand determines the type of summary analysis to be performed.
Currently there is only one type: <literal>SUMMARY=TOTAL</literal>, which displays per-item
analysis tested against the totals.
</para>
<sect2 label="15.18.1">
<title>Example - Reliability</title>

<para>Before analysing the results of a survey &#8211; particularly for a multiple choice survey &#8211;
it is desireable to know whether the respondents have considered their answers
or simply provided random answers.
</para>
<para>In the following example the survey results from the file <filename>hotel.sav</filename> are used.
All five survey questions are included in the reliability analysis.
However, before running the analysis, the data must be preprocessed.
An examination of the survey questions reveals that two questions, <emphasis>viz:</emphasis> v3 and v5
are negatively worded, whereas the others are positively worded.
All questions must be based upon the same scale for the analysis to be meaningful.
One could use the <literal>RECODE</literal> command (see <link linkend="RECODE">RECODE</link>), however a simpler way is
to use <literal>COMPUTE</literal> (see <link linkend="COMPUTE">COMPUTE</link>) and this is what is done in <link linkend="reliability_003aex">reliability:ex</link>.
</para>
<anchor id="reliability_003aex"/>
<sidebar><screen>get file=&quot;hotel.sav&quot;.

* Recode V3 and V5 inverting the sense of the values.
compute v3 = 6 - v3.
compute v5 = 6 - v5.

reliability
	/variables= all
	/model=alpha.
</screen></sidebar>
<para>In this case, all variables in the data set are used.  So we can use the special
keyword &#8216;<literal>ALL</literal>&#8217; (see <link linkend="BNF">BNF</link>).
</para>
<anchor id="reliability_003asrc"/>
<sidebar></sidebar>
<para><link linkend="reliability_003ares">reliability:res</link> shows that Cronbach&#8217;s Alpha is 0.11  which is a value normally considered too
low to indicate consistency within the data.  This is possibly due to the small number of
survey questions.  The survey should be redesigned before serious use of the results are
applied.
</para>
<anchor id="reliability_003ares"/>
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>Scale: ANY

Case Processing Summary
+--------+--+-------+
|Cases   | N|Percent|
+--------+--+-------+
|Valid   |17| 100.0%|
|Excluded| 0|    .0%|
|Total   |17| 100.0%|
+--------+--+-------+

    Reliability Statistics
+----------------+----------+
|Cronbach's Alpha|N of Items|
+----------------+----------+
|             .11|         5|
+----------------+----------+
</screen>

</sect2>
</sect1>
<sect1 label="15.19" id="ROC">
<title>ROC</title>

<indexterm role="vr"><primary>ROC</primary></indexterm>
<indexterm role="cp"><primary>Receiver Operating Characteristic</primary></indexterm>
<indexterm role="cp"><primary>Area under curve</primary></indexterm>

<literallayout>ROC     <replaceable>var_list</replaceable> BY <replaceable>state_var</replaceable> (<replaceable>state_value</replaceable>)
        /PLOT = { CURVE [(REFERENCE)], NONE }
        /PRINT = [ SE ] [ COORDINATES ]
        /CRITERIA = [ CUTOFF({INCLUDE,EXCLUDE}) ]
          [ TESTPOS ({LARGE,SMALL}) ]
          [ CI (<replaceable>confidence</replaceable>) ]
          [ DISTRIBUTION ({FREE, NEGEXPO }) ]
        /MISSING={EXCLUDE,INCLUDE}
</literallayout>

<para>The <literal>ROC</literal> command is used to plot the receiver operating characteristic curve
of a dataset, and to estimate the area under the curve.
This is useful for analysing the efficacy of a variable as a predictor of a state of nature.
</para>
<para>The mandatory <replaceable>var_list</replaceable> is the list of predictor variables.
The variable <replaceable>state_var</replaceable> is the variable whose values represent the actual states,
and <replaceable>state_value</replaceable> is the value of this variable which represents the positive state.
</para>
<para>The optional subcommand <literal>PLOT</literal> is used to determine if and how the <literal>ROC</literal> curve is drawn.
The keyword <literal>CURVE</literal> means that the <literal>ROC</literal> curve should be drawn, and the optional keyword <literal>REFERENCE</literal>,
which should be enclosed in parentheses, says that the diagonal reference line should be drawn.
If the keyword <literal>NONE</literal> is given, then no <literal>ROC</literal> curve is drawn.
By default, the curve is drawn with no reference line.
</para>
<para>The optional subcommand <literal>PRINT</literal> determines which additional
tables should be printed.  Two additional tables are available.  The
<literal>SE</literal> keyword says that standard error of the area under the
curve should be printed as well as the area itself.  In addition, a
p-value for the null hypothesis that the area under the curve equals
0.5 is printed.   The <literal>COORDINATES</literal> keyword says that a
table of coordinates of the <literal>ROC</literal> curve should be printed.
</para>
<para>The <literal>CRITERIA</literal> subcommand has four optional parameters:
</para><itemizedlist><listitem><para>The <literal>TESTPOS</literal> parameter may be <literal>LARGE</literal> or <literal>SMALL</literal>.
<literal>LARGE</literal> is the default, and says that larger values in the predictor variables are to be
considered positive.  <literal>SMALL</literal> indicates that smaller values should be considered positive.
</para>
</listitem><listitem><para>The <literal>CI</literal> parameter specifies the confidence interval that should be printed.
It has no effect if the <literal>SE</literal> keyword in the <literal>PRINT</literal> subcommand has not been given.
</para>
</listitem><listitem><para>The <literal>DISTRIBUTION</literal> parameter determines the method to be used when estimating the area
under the curve.
There are two possibilities, <emphasis>viz</emphasis>: <literal>FREE</literal> and <literal>NEGEXPO</literal>.
The <literal>FREE</literal> method uses a non-parametric estimate, and the <literal>NEGEXPO</literal> method a bi-negative
exponential distribution estimate.
The <literal>NEGEXPO</literal> method should only be used when the number of positive actual states is
equal to the number of negative actual states.
The default is <literal>FREE</literal>.
</para>
</listitem><listitem><para>The <literal>CUTOFF</literal> parameter is for compatibility and is ignored.
</para></listitem></itemizedlist>
<para>The <literal>MISSING</literal> subcommand determines whether user missing values are to
be included or excluded in the analysis.  The default behaviour is to
exclude them.
Cases are excluded on a listwise basis; if any of the variables in <replaceable>var_list</replaceable>
or if the variable <replaceable>state_var</replaceable> is missing, then the entire case is
excluded.
</para>
<!--  LocalWords:  subcmd subcommand -->
<!-- PSPP - a program for statistical analysis. -->
<!-- Copyright (C) 2017, 2020, 2021 Free Software Foundation, Inc. -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.3 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<!-- A copy of the license is included in the section entitled "GNU -->
<!-- Free Documentation License". -->
<!-- -->
</sect1>
</chapter>
<chapter label="16" id="Matrices">
<title>Matrices</title>

<para>Some PSPP procedures work with matrices by producing numeric
matrices that report results of data analysis, or by consuming
matrices as a basis for further analysis.  This chapter documents the
format of data files that store these matrices and commands for
working with them, as well as PSPP&#8217;s general-purpose facility for
matrix operations.
</para>
<sect1 label="16.1" id="Matrix-Files">
<title>Matrix Files</title>
<indexterm role="vr"><primary>Matrix file</primary></indexterm>

<para>A matrix file is an SPSS system file that conforms to the dictionary
and case structure described in this section.  Procedures that read
matrices from files expect them to be in the matrix file format.
Procedures that write matrices also use this format.
</para>
<para>Text files that contain matrices can be converted to matrix file
format.  See <link linkend="MATRIX-DATA">MATRIX DATA</link>, for a command to read a text file as a
matrix file.
</para>
<para>A matrix file&#8217;s dictionary must have the following variables in the
specified order:
</para>
<orderedlist numeration="arabic"><listitem><para>Zero or more numeric split variables.  These are included by
procedures when <literal>SPLIT FILE</literal> is active.  <literal>MATRIX DATA</literal> assigns
split variables format F4.0.
</para>
</listitem><listitem><para><literal>ROWTYPE_</literal>, a string variable with width 8.  This variable
indicates the kind of matrix or vector that a given case represents.
The supported row types are listed below.
</para>
</listitem><listitem><para>Zero or more numeric factor variables.  These are included by
procedures that divide data into cells.  For within-cell data, factor
variables are filled with non-missing values; for pooled data, they
are missing.  <literal>MATRIX DATA</literal> assigns factor variables format F4.0.
</para>
</listitem><listitem><para><literal>VARNAME_</literal>, a string variable.  Matrix data includes one row per
continuous variable (see below), naming each continuous variable in
order.  This column is blank for vector data.  <literal>MATRIX DATA</literal> makes
<literal>VARNAME_</literal> wide enough for the name of any of the continuous
variables, but at least 8 bytes.
</para>
</listitem><listitem><para>One or more numeric continuous variables.  These are the variables
whose data was analyzed to produce the matrices.  <literal>MATRIX DATA</literal>
assigns continuous variables format F10.4.
</para></listitem></orderedlist>
<para>Case weights are ignored in matrix files.
</para>
<bridgehead renderas="sect2">Row Types</bridgehead>
<anchor id="Matrix-File-Row-Types"/>
<para>Matrix files support a fixed set of types of matrix and vector data.
The <literal>ROWTYPE_</literal> variable in each case of a matrix file indicates
its row type.
</para>
<para>The supported matrix row types are listed below.  Each type is listed
with the keyword that identifies it in <literal>ROWTYPE_</literal>.  All supported
types of matrices are square, meaning that each matrix must include
one row per continuous variable, with the <literal>VARNAME_</literal> variable
indicating each continuous variable in turn in the same order as the
dictionary.
</para>
<variablelist><varlistentry><term><literal>CORR</literal>
</term><listitem><para>Correlation coefficients.
</para>
</listitem></varlistentry><varlistentry><term><literal>COV</literal>
</term><listitem><para>Covariance coefficients.
</para>
</listitem></varlistentry><varlistentry><term><literal>MAT</literal>
</term><listitem><para>General-purpose matrix.
</para>
</listitem></varlistentry><varlistentry><term><literal>N_MATRIX</literal>
</term><listitem><para>Counts.
</para>
</listitem></varlistentry><varlistentry><term><literal>PROX</literal>
</term><listitem><para>Proximities matrix.
</para></listitem></varlistentry></variablelist>
<para>The supported vector row types are listed below, along with their
associated keyword.  Vector row types only require a single row, whose
<literal>VARNAME_</literal> is blank:
</para>
<variablelist><varlistentry><term><literal>COUNT</literal>
</term><listitem><para>Unweighted counts.
</para>
</listitem></varlistentry><varlistentry><term><literal>DFE</literal>
</term><listitem><para>Degrees of freedom.
</para>
</listitem></varlistentry><varlistentry><term><literal>MEAN</literal>
</term><listitem><para>Means.
</para>
</listitem></varlistentry><varlistentry><term><literal>MSE</literal>
</term><listitem><para>Mean squared errors.
</para>
</listitem></varlistentry><varlistentry><term><literal>N</literal>
</term><listitem><para>Counts.
</para>
</listitem></varlistentry><varlistentry><term><literal>STDDEV</literal>
</term><listitem><para>Standard deviations.
</para></listitem></varlistentry></variablelist>
<para>Only the row types listed above may appear in matrix files.  The
<literal>MATRIX DATA</literal> command, however, accepts the additional row types
listed below, which it changes into matrix file row types as part of
its conversion process:
</para>
<variablelist><varlistentry><term><literal>N_VECTOR</literal>
</term><listitem><para>Synonym for <literal>N</literal>.
</para>
</listitem></varlistentry><varlistentry><term><literal>SD</literal>
</term><listitem><para>Synonym for <literal>STDDEV</literal>.
</para>
</listitem></varlistentry><varlistentry><term><literal>N_SCALAR</literal>
</term><listitem><para>Accepts a single number from the <literal>MATRIX DATA</literal> input and writes
it as an <literal>N</literal> row with the number replicated across all the
continuous variables.
</para></listitem></varlistentry></variablelist>
</sect1>
<sect1 label="16.2" id="MATRIX-DATA">
<title>MATRIX DATA</title>
<indexterm role="vr"><primary>MATRIX DATA</primary></indexterm>

<literallayout>MATRIX DATA
        VARIABLES=<replaceable>variables</replaceable>
        [FILE={&#8217;<replaceable>file_name</replaceable>&#8217; | INLINE}
        [/FORMAT=[{LIST | FREE}]
                 [{UPPER | LOWER | FULL}]
                 [{DIAGONAL | NODIAGONAL}]]
        [/SPLIT=<replaceable>split_vars</replaceable>]
        [/FACTORS=<replaceable>factor_vars</replaceable>]
        [/N=<replaceable>n</replaceable>]

The following subcommands are only needed when ROWTYPE_ is not
specified on the VARIABLES subcommand:
        [/CONTENTS={CORR,COUNT,COV,DFE,MAT,MEAN,MSE,
                    N_MATRIX,N|N_VECTOR,N_SCALAR,PROX,SD|STDDEV}]
        [/CELLS=<replaceable>n_cells</replaceable>]
</literallayout>
<para>The <literal>MATRIX DATA</literal> command convert matrices and vectors from text
format into the matrix file format (See <link linkend="Matrix-Files">Matrix Files</link>) for use by
procedures that read matrices.  It reads a text file or inline data
and outputs to the active file, replacing any data already in the
active dataset.  The matrix file may then be used by other commands
directly from the active file, or it may be written to a <filename>.sav</filename>
file using the <literal>SAVE</literal> command.
</para>
<para>The text data read by <literal>MATRIX DATA</literal> can be delimited by spaces or
commas.  A plus or minus sign, except immediately following a &#8216;<literal>d</literal>&#8217;
or &#8216;<literal>e</literal>&#8217;, also begins a new value.  Optionally, values may be
enclosed in single or double quotes.
</para>
<para><literal>MATRIX DATA</literal> can read the types of matrix and vector data
supported in matrix files (see <link linkend="Matrix-File-Row-Types">Matrix File Row Types</link>).
</para>
<para>The <literal>FILE</literal> subcommand specifies the source of the command&#8217;s
input.  To read input from a text file, specify its name in quotes.
To supply input inline, omit <literal>FILE</literal> or specify <literal>INLINE</literal>.
Inline data must directly follow <literal>MATRIX DATA</literal>, inside <literal>BEGIN
DATA</literal> (see <link linkend="BEGIN-DATA">BEGIN DATA</link>).
</para>
<para><literal>VARIABLES</literal> is the only required subcommand.  It names the
variables present in each input record in the order that they appear.
(<literal>MATRIX DATA</literal> reorders the variables in the matrix file it
produces, if needed to fit the matrix file format.)  The variable list
must include split variables and factor variables, if they are present
in the data, in addition to the continuous variables that form matrix
rows and columns.  It may also include a special variable named
<literal>ROWTYPE_</literal>.
</para>
<para>Matrix data may include split variables or factor variables or both.
List split variables, if any, on the <literal>SPLIT</literal> subcommand and
factor variables, if any, on the <literal>FACTORS</literal> subcommand.  Split
and factor variables must be numeric.  Split and factor variables must
also be listed on <literal>VARIABLES</literal>, with one exception: if
<literal>VARIABLES</literal> does not include <literal>ROWTYPE_</literal>, then
<literal>SPLIT</literal> may name a single variable that is not in
<literal>VARIABLES</literal> (see <link linkend="MATRIX-DATA-Example-8">MATRIX DATA Example 8</link>).
</para>
<para>The <literal>FORMAT</literal> subcommand accepts settings to describe the format
of the input data:
</para>
<variablelist><varlistentry><term><literal>LIST</literal> (default)
</term><term><literal>FREE</literal>
</term><listitem><para>LIST requires each row to begin at the start of a new input line.
FREE allows rows to begin in the middle of a line.  Either setting
allows a single row to continue across multiple input lines.
</para>
</listitem></varlistentry><varlistentry><term><literal>LOWER</literal> (default)
</term><term><literal>UPPER</literal>
</term><term><literal>FULL</literal>
</term><listitem><para>With LOWER, only the lower triangle is read from the input data and
the upper triangle is mirrored across the main diagonal.  UPPER
behaves similarly for the upper triangle.  FULL reads the entire
matrix.
</para>
</listitem></varlistentry><varlistentry><term><literal>DIAGONAL</literal> (default)
</term><term><literal>NODIAGONAL</literal>
</term><listitem><para>With DIAGONAL, the main diagonal is read from the input data.  With
NODIAGONAL, which is incompatible with FULL, the main diagonal is not
read from the input data but instead set to 1 for correlation matrices
and system-missing for others.
</para></listitem></varlistentry></variablelist>
<para>The <literal>N</literal> subcommand is a way to specify the size of the
population.  It is equivalent to specifying an <literal>N</literal> vector with
the specified value for each split file.
</para>
<para><literal>MATRIX DATA</literal> supports two different ways to indicate the kinds of
matrices and vectors present in the data, depending on whether a
variable with the special name <literal>ROWTYPE_</literal> is present in
<literal>VARIABLES</literal>.  The following subsections explain <literal>MATRIX DATA</literal>
syntax and behavior in each case.
</para>
<sect2 label="16.2.1" id="MATRIX-DATA-with-ROWTYPE_005f">
<title>With <literal>ROWTYPE_</literal></title>

<para>If <literal>VARIABLES</literal> includes <literal>ROWTYPE_</literal>, each case&#8217;s
<literal>ROWTYPE_</literal> indicates the type of data contained in the row.
See <link linkend="Matrix-File-Row-Types">Matrix File Row Types</link>, for a list of supported row types.
</para>
<bridgehead renderas="sect3">Example 1: Defaults with <literal>ROWTYPE_</literal></bridgehead>
<anchor id="MATRIX-DATA-Example-1"/>
<para>This example shows a simple use of <literal>MATRIX DATA</literal> with
<literal>ROWTYPE_</literal> plus 8 variables named <literal>var01</literal> through
<literal>var08</literal>.
</para>
<para>Because <literal>ROWTYPE_</literal> is the first variable in <literal>VARIABLES</literal>,
it appears first on each line. The first three lines in the example
data have <literal>ROWTYPE_</literal> values of &#8216;<literal>MEAN</literal>&#8217;, &#8216;<literal>SD</literal>&#8217;, and
&#8216;<literal>N</literal>&#8217;.  These indicate that these lines contain vectors of means,
standard deviations, and counts, respectively, for <literal>var01</literal>
through <literal>var08</literal> in order.
</para>
<para>The remaining 8 lines have a ROWTYPE_ of &#8216;<literal>CORR</literal>&#8217; which indicates
that the values are correlation coefficients.  Each of the lines
corresponds to a row in the correlation matrix: the first line is for
<literal>var01</literal>, the next line for <literal>var02</literal>, and so on.  The input
only contains values for the lower triangle, including the diagonal,
since <literal>FORMAT=LOWER DIAGONAL</literal> is the default.
</para>
<para>With <literal>ROWTYPE_</literal>, the <literal>CONTENTS</literal> subcommand is optional and
the <literal>CELLS</literal> subcommand may not be used.
</para>
<screen>MATRIX DATA
    VARIABLES=ROWTYPE_ var01 TO var08.
BEGIN DATA.
MEAN  24.3   5.4  69.7  20.1  13.4   2.7  27.9   3.7
SD     5.7   1.5  23.5   5.8   2.8   4.5   5.4   1.5
N       92    92    92    92    92    92    92    92
CORR  1.00
CORR   .18  1.00
CORR  -.22  -.17  1.00
CORR   .36   .31  -.14  1.00
CORR   .27   .16  -.12   .22  1.00
CORR   .33   .15  -.17   .24   .21  1.00
CORR   .50   .29  -.20   .32   .12   .38  1.00
CORR   .17   .29  -.05   .20   .27   .20   .04  1.00
END DATA.
</screen>
<bridgehead renderas="sect3">Example 2: <literal>FORMAT=UPPER NODIAGONAL</literal></bridgehead>

<para>This syntax produces the same matrix file as example 1, but it uses
<literal>FORMAT=UPPER NODIAGONAL</literal> to specify the upper triangle and omit
the diagonal.  Because the matrix&#8217;s <literal>ROWTYPE_</literal> is <literal>CORR</literal>,
PSPP automatically fills in the diagonal with 1.
</para>
<screen>MATRIX DATA
    VARIABLES=ROWTYPE_ var01 TO var08
    /FORMAT=UPPER NODIAGONAL.
BEGIN DATA.
MEAN  24.3   5.4  69.7  20.1  13.4   2.7  27.9   3.7
SD     5.7   1.5  23.5   5.8   2.8   4.5   5.4   1.5
N       92    92    92    92    92    92    92    92
CORR         .17   .50  -.33   .27   .36  -.22   .18
CORR               .29   .29  -.20   .32   .12   .38
CORR                     .05   .20  -.15   .16   .21
CORR                           .20   .32  -.17   .12
CORR                                 .27   .12  -.24
CORR                                      -.20  -.38
CORR                                             .04
END DATA.
</screen>
<bridgehead renderas="sect3">Example 3: <literal>N</literal> subcommand</bridgehead>

<para>This syntax uses the <literal>N</literal> subcommand in place of an <literal>N</literal>
vector.  It produces the same matrix file as examples 1 and 2.
</para>
<screen>MATRIX DATA
    VARIABLES=ROWTYPE_ var01 TO var08
    /FORMAT=UPPER NODIAGONAL
    /N 92.
BEGIN DATA.
MEAN  24.3   5.4  69.7  20.1  13.4   2.7  27.9   3.7
SD     5.7   1.5  23.5   5.8   2.8   4.5   5.4   1.5
CORR         .17   .50  -.33   .27   .36  -.22   .18
CORR               .29   .29  -.20   .32   .12   .38
CORR                     .05   .20  -.15   .16   .21
CORR                           .20   .32  -.17   .12
CORR                                 .27   .12  -.24
CORR                                      -.20  -.38
CORR                                             .04
END DATA.
</screen>
<bridgehead renderas="sect3">Example 4: Split variables</bridgehead>
<anchor id="MATRIX-DATA-Example-4"/>
<para>This syntax defines two matrices, using the variable &#8216;<literal>s1</literal>&#8217; to
distinguish between them.  Notice how the order of variables in the
input matches their order on <literal>VARIABLES</literal>.  This example also
uses <literal>FORMAT=FULL</literal>.
</para>
<screen>MATRIX DATA
    VARIABLES=s1 ROWTYPE_  var01 TO var04
    /SPLIT=s1
    /FORMAT=FULL.
BEGIN DATA.
0 MEAN 34 35 36 37
0 SD   22 11 55 66
0 N    99 98 99 92
0 CORR  1 .9 .8 .7
0 CORR .9  1 .6 .5
0 CORR .8 .6  1 .4
0 CORR .7 .5 .4  1
1 MEAN 44 45 34 39
1 SD   23 15 51 46
1 N    98 34 87 23
1 CORR  1 .2 .3 .4
1 CORR .2  1 .5 .6
1 CORR .3 .5  1 .7
1 CORR .4 .6 .7  1
END DATA.
</screen>
<bridgehead renderas="sect3">Example 5: Factor variables</bridgehead>
<anchor id="MATRIX-DATA-Example-5"/>
<para>This syntax defines a matrix file that includes a factor variable
&#8216;<literal>f1</literal>&#8217;.  The data includes mean, standard deviation, and count
vectors for two values of the factor variable, plus a correlation
matrix for pooled data.
</para>
<screen>MATRIX DATA
    VARIABLES=ROWTYPE_ f1 var01 TO var04
    /FACTOR=f1.
BEGIN DATA.
MEAN 0 34 35 36 37
SD   0 22 11 55 66
N    0 99 98 99 92
MEAN 1 44 45 34 39
SD   1 23 15 51 46
N    1 98 34 87 23
CORR .  1
CORR . .9  1
CORR . .8 .6  1
CORR . .7 .5 .4  1
END DATA.
</screen>
</sect2>
<sect2 label="16.2.2" id="MATRIX-DATA-without-ROWTYPE_005f">
<title>Without <literal>ROWTYPE_</literal></title>

<para>If <literal>VARIABLES</literal> does not contain <literal>ROWTYPE_</literal>, the
<literal>CONTENTS</literal> subcommand defines the row types that appear in the
file and their order.  If <literal>CONTENTS</literal> is omitted,
<literal>CONTENTS=CORR</literal> is assumed.
</para>
<para>Factor variables without <literal>ROWTYPE_</literal> introduce special
requirements, illustrated below in Examples 8 and 9.
</para>
<bridgehead renderas="sect3">Example 6: Defaults without <literal>ROWTYPE_</literal></bridgehead>

<para>This example shows a simple use of <literal>MATRIX DATA</literal> with 8 variables
named <literal>var01</literal> through <literal>var08</literal>, without <literal>ROWTYPE_</literal>.
This yields the same matrix file as Example 1 (see <link linkend="MATRIX-DATA-Example-1">MATRIX DATA
Example 1</link>).
</para>
<screen>MATRIX DATA
    VARIABLES=var01 TO var08
   /CONTENTS=MEAN SD N CORR.
BEGIN DATA.
24.3   5.4  69.7  20.1  13.4   2.7  27.9   3.7
 5.7   1.5  23.5   5.8   2.8   4.5   5.4   1.5
  92    92    92    92    92    92    92    92
1.00
 .18  1.00
-.22  -.17  1.00
 .36   .31  -.14  1.00
 .27   .16  -.12   .22  1.00
 .33   .15  -.17   .24   .21  1.00
 .50   .29  -.20   .32   .12   .38  1.00
 .17   .29  -.05   .20   .27   .20   .04  1.00
END DATA.
</screen>
<bridgehead renderas="sect3">Example 7: Split variables with explicit values</bridgehead>

<para>This syntax defines two matrices, using the variable <literal>s1</literal> to
distinguish between them.  Each line of data begins with <literal>s1</literal>.
This yields the same matrix file as Example 4 (see <link linkend="MATRIX-DATA-Example-4">MATRIX DATA
Example 4</link>).
</para>
<screen>MATRIX DATA
    VARIABLES=s1 var01 TO var04
    /SPLIT=s1
    /FORMAT=FULL
    /CONTENTS=MEAN SD N CORR.
BEGIN DATA.
0 34 35 36 37
0 22 11 55 66
0 99 98 99 92
0  1 .9 .8 .7
0 .9  1 .6 .5
0 .8 .6  1 .4
0 .7 .5 .4  1
1 44 45 34 39
1 23 15 51 46
1 98 34 87 23
1  1 .2 .3 .4
1 .2  1 .5 .6
1 .3 .5  1 .7
1 .4 .6 .7  1
END DATA.
</screen>
<bridgehead renderas="sect3">Example 8: Split variable with sequential values</bridgehead>
<anchor id="MATRIX-DATA-Example-8"/>
<para>Like this previous example, this syntax defines two matrices with
split variable <literal>s1</literal>.  In this case, though, <literal>s1</literal> is not
listed in <literal>VARIABLES</literal>, which means that its value does not
appear in the data.  Instead, <literal>MATRIX DATA</literal> reads matrix data
until the input is exhausted, supplying 1 for the first split, 2 for
the second, and so on.
</para>
<screen>MATRIX DATA
    VARIABLES=var01 TO var04
    /SPLIT=s1
    /FORMAT=FULL
    /CONTENTS=MEAN SD N CORR.
BEGIN DATA.
34 35 36 37
22 11 55 66
99 98 99 92
 1 .9 .8 .7
.9  1 .6 .5
.8 .6  1 .4
.7 .5 .4  1
44 45 34 39
23 15 51 46
98 34 87 23
 1 .2 .3 .4
.2  1 .5 .6
.3 .5  1 .7
.4 .6 .7  1
END DATA.
</screen>
<sect3 label="16.2.2.1">
<title>Factor variables without <literal>ROWTYPE_</literal></title>

<para>Without <literal>ROWTYPE_</literal>, factor variables introduce two new wrinkles
to <literal>MATRIX DATA</literal> syntax.  First, the <literal>CELLS</literal> subcommand
must declare the number of combinations of factor variables present in
the data.  If there is, for example, one factor variable for which the
data contains three values, one would write <literal>CELLS=3</literal>; if there
are two (or more) factor variables for which the data contains five
combinations, one would use <literal>CELLS=5</literal>; and so on.
</para>
<para>Second, the <literal>CONTENTS</literal> subcommand must distinguish within-cell
data from pooled data by enclosing within-cell row types in
parentheses.  When different within-cell row types for a single factor
appear in subsequent lines, enclose the row types in a single set of
parentheses; when different factors&#8217; values for a given within-cell
row type appear in subsequent lines, enclose each row type in
individual parentheses.
</para>
<para>Without <literal>ROWTYPE_</literal>, input lines for pooled data do not include
factor values, not even as missing values, but input lines for
within-cell data do.
</para>
<para>The following examples aim to clarify this syntax.
</para>
<bridgehead renderas="sect3">Example 9: Factor variables, grouping within-cell records by factor</bridgehead>

<para>This syntax defines the same matrix file as Example 5 (see <link linkend="MATRIX-DATA-Example-5">MATRIX
DATA Example 5</link>), without using <literal>ROWTYPE_</literal>.  It declares
<literal>CELLS=2</literal> because the data contains two values (0 and 1) for
factor variable <literal>f1</literal>.  Within-cell vector row types <literal>MEAN</literal>,
<literal>SD</literal>, and <literal>N</literal> are in a single set of parentheses on
<literal>CONTENTS</literal> because they are grouped together in subsequent
lines for a single factor value.  The data lines with the pooled
correlation matrix do not have any factor values.
</para>
<screen>MATRIX DATA
    VARIABLES=f1 var01 TO var04
    /FACTOR=f1
    /CELLS=2
    /CONTENTS=(MEAN SD N) CORR.
BEGIN DATA.
0 34 35 36 37
0 22 11 55 66
0 99 98 99 92
1 44 45 34 39
1 23 15 51 46
1 98 34 87 23
   1
  .9  1
  .8 .6  1
  .7 .5 .4  1
END DATA.
</screen>
<bridgehead renderas="sect3">Example 10: Factor variables, grouping within-cell records by row type</bridgehead>

<para>This syntax defines the same matrix file as the previous example.  The
only difference is that the within-cell vector rows are grouped
differently: two rows of means (one for each factor), followed by two
rows of standard deviations, followed by two rows of counts.
</para>
<screen>MATRIX DATA
    VARIABLES=f1 var01 TO var04
    /FACTOR=f1
    /CELLS=2
    /CONTENTS=(MEAN) (SD) (N) CORR.
BEGIN DATA.
0 34 35 36 37
1 44 45 34 39
0 22 11 55 66
1 23 15 51 46
0 99 98 99 92
1 98 34 87 23
   1
  .9  1
  .8 .6  1
  .7 .5 .4  1
END DATA.
</screen>
</sect3>
</sect2>
</sect1>
<sect1 label="16.3" id="MCONVERT">
<title>MCONVERT</title>
<indexterm role="vr"><primary>MCONVERT</primary></indexterm>

<literallayout>MCONVERT
    [[MATRIX=]
     [IN({&#8216;<literal>*</literal>&#8217;|&#8217;<replaceable>file</replaceable>&#8217;})]
     [OUT({&#8216;<literal>*</literal>&#8217;|&#8217;<replaceable>file</replaceable>&#8217;})]]
    [/{REPLACE,APPEND}].
</literallayout>
<para>The <literal>MCONVERT</literal> command converts matrix data from a correlation
matrix and a vector of standard deviations into a covariance matrix,
or vice versa.
</para>
<para>By default, <literal>MCONVERT</literal> both reads and writes the active file.  Use
the <literal>MATRIX</literal> subcommand to specify other files.  To read a matrix
file, specify its name inside parentheses following <literal>IN</literal>.  To
write a matrix file, specify its name inside parentheses following
<literal>OUT</literal>.  Use &#8216;<literal>*</literal>&#8217; to explicitly specify the active file for
input or output.
</para>
<para>When <literal>MCONVERT</literal> reads the input, by default it substitutes a
correlation matrix and a vector of standard deviations each time it
encounters a covariance matrix, and vice versa.  Specify
<literal>/APPEND</literal> to instead have <literal>MCONVERT</literal> add the other form of
data without removing the existing data.  Use <literal>/REPLACE</literal> to
explicitly request removing the existing data.
</para>
<para>The <literal>MCONVERT</literal> command requires its input to be a matrix file.
Use <literal>MATRIX DATA</literal> to convert text input into matrix file format.
See <link linkend="MATRIX-DATA">MATRIX DATA</link>, for details.
</para>
</sect1>
<sect1 label="16.4" id="MATRIX">
<title>MATRIX</title>
<indexterm role="vr"><primary>MATRIX</primary></indexterm>
<indexterm role="vr"><primary>END MATRIX</primary></indexterm>

<literallayout><literal>MATRIX.</literal>
&#8230;<emphasis>matrix commands</emphasis>&#8230;
<literal>END MATRIX.</literal>
</literallayout>
<para>The following basic matrix commands are supported:
</para>
<literallayout><literal>COMPUTE</literal> <emphasis>variable</emphasis>[<literal>(</literal><emphasis>index</emphasis>[<literal>,</literal><emphasis>index</emphasis>]<literal>)</literal>]<literal>=</literal><emphasis>expression</emphasis><literal>.</literal>
<literal>CALL</literal> <emphasis>procedure</emphasis><literal>(</literal><emphasis>argument</emphasis><literal>,</literal> &#8230;).
<literal>PRINT</literal> [<emphasis>expression</emphasis>]
      [<literal>/FORMAT</literal><literal>=</literal><emphasis>format</emphasis>]
      [<literal>/TITLE</literal><literal>=</literal><emphasis>title</emphasis>]
      [<literal>/SPACE</literal><literal>=</literal>{<literal>NEWPAGE</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <emphasis>n</emphasis>}]
      [{<literal>/RLABELS</literal><literal>=</literal><emphasis>string</emphasis>&#8230; <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>/RNAMES</literal><literal>=</literal><emphasis>expression</emphasis>}]
      [{<literal>/CLABELS</literal><literal>=</literal><emphasis>string</emphasis>&#8230; <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>/CNAMES</literal><literal>=</literal><emphasis>expression</emphasis>}]<literal>.</literal>
</literallayout>
<para>The following matrix commands offer support for flow control:
</para>
<literallayout><literal>DO IF</literal> <emphasis>expression</emphasis><literal>.</literal>
  &#8230;<emphasis>matrix commands</emphasis>&#8230;
[<literal>ELSE IF</literal> <emphasis>expression</emphasis><literal>.</literal>
  &#8230;<emphasis>matrix commands</emphasis>&#8230;]&#8230;
[<literal>ELSE</literal>
  &#8230;<emphasis>matrix commands</emphasis>&#8230;]
<literal>END IF</literal><literal>.</literal>

<literal>LOOP</literal> [<emphasis>var</emphasis><literal>=</literal><emphasis>first</emphasis> <literal>TO</literal> <emphasis>last</emphasis> [<literal>BY</literal> <emphasis>step</emphasis>]] [<literal>IF</literal> <emphasis>expression</emphasis>]<literal>.</literal>
  &#8230;<emphasis>matrix commands</emphasis>&#8230;
<literal>END LOOP</literal> [<literal>IF</literal> <emphasis>expression</emphasis>]<literal>.</literal>

<literal>BREAK</literal><literal>.</literal>
</literallayout>
<para>The following matrix commands support matrix input and output:
</para>
<literallayout><literal>READ</literal> <emphasis>variable</emphasis>[<literal>(</literal><emphasis>index</emphasis>[<literal>,</literal><emphasis>index</emphasis>]<literal>)</literal>]
     [<literal>/FILE</literal><literal>=</literal><emphasis>file</emphasis>]
     <literal>/FIELD</literal><literal>=</literal><emphasis>first</emphasis> <literal>TO</literal> <emphasis>last</emphasis> [<literal>BY</literal> <emphasis>width</emphasis>]
     [<literal>/FORMAT</literal><literal>=</literal><emphasis>format</emphasis>]
     [<literal>/SIZE</literal><literal>=</literal><emphasis>expression</emphasis>]
     [<literal>/MODE</literal><literal>=</literal>{<literal>RECTANGULAR</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>SYMMETRIC</literal>}]
     [<literal>/REREAD</literal>]<literal>.</literal>
<literal>WRITE</literal> <emphasis>expression</emphasis>
      [<literal>/OUTFILE</literal><literal>=</literal><emphasis>file</emphasis>]
      <literal>/FIELD</literal><literal>=</literal><emphasis>first</emphasis> <literal>TO</literal> <emphasis>last</emphasis> [<literal>BY</literal> <emphasis>width</emphasis>]
      [<literal>/MODE</literal><literal>=</literal>{<literal>RECTANGULAR</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>TRIANGULAR</literal>}]
      [<literal>/HOLD</literal>]
      [<literal>/FORMAT</literal><literal>=</literal><emphasis>format</emphasis>]<literal>.</literal>
<literal>GET</literal> <emphasis>variable</emphasis>[<literal>(</literal><emphasis>index</emphasis>[<literal>,</literal><emphasis>index</emphasis>]<literal>)</literal>]
    [<literal>/FILE</literal><literal>=</literal>{<emphasis>file</emphasis> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>*</literal>}]
    [<literal>/VARIABLES</literal><literal>=</literal><emphasis>variable</emphasis>&#8230;]
    [<literal>/NAMES</literal><literal>=</literal><emphasis>expression</emphasis>]
    [<literal>/MISSING</literal><literal>=</literal>{<literal>ACCEPT</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>OMIT</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <emphasis>number</emphasis>}]
    [<literal>/SYSMIS</literal><literal>=</literal>{<literal>OMIT</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <emphasis>number</emphasis>}]<literal>.</literal>
<literal>SAVE</literal> <emphasis>expression</emphasis>
     [<literal>/OUTFILE</literal><literal>=</literal>{<emphasis>file</emphasis> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>*</literal>}]
     [<literal>/VARIABLES</literal><literal>=</literal><emphasis>variable</emphasis>&#8230;]
     [<literal>/NAMES</literal><literal>=</literal><emphasis>expression</emphasis>]
     [<literal>/STRINGS</literal><literal>=</literal><emphasis>variable</emphasis>&#8230;]<literal>.</literal>
<literal>MGET</literal> [<literal>/FILE</literal><literal>=</literal><emphasis>file</emphasis>]
     [<literal>/TYPE</literal><literal>=</literal>{<literal>COV</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>CORR</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>MEAN</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>STDDEV</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>N</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>COUNT</literal>}]<literal>.</literal>
<literal>MSAVE</literal> <emphasis>expression</emphasis>
      <literal>/TYPE</literal><literal>=</literal>{<literal>COV</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>CORR</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>MEAN</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>STDDEV</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>N</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>COUNT</literal>}
      [<literal>/OUTFILE</literal><literal>=</literal><emphasis>file</emphasis>]
      [<literal>/VARIABLES</literal><literal>=</literal><emphasis>variable</emphasis>&#8230;]
      [<literal>/SNAMES</literal><literal>=</literal><emphasis>variable</emphasis>&#8230;]
      [<literal>/SPLIT</literal><literal>=</literal><emphasis>expression</emphasis>]
      [<literal>/FNAMES</literal><literal>=</literal><emphasis>variable</emphasis>&#8230;]
      [<literal>/FACTOR</literal><literal>=</literal><emphasis>expression</emphasis>]<literal>.</literal>
</literallayout>
<para>The following matrix commands provide additional support:
</para>
<literallayout><literal>DISPLAY</literal> [{<literal>DICTIONARY</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>STATUS</literal>}]<literal>.</literal>
<literal>RELEASE</literal> <emphasis>variable</emphasis>&#8230;<literal>.</literal>
</literallayout>
<para><literal>MATRIX</literal> and <literal>END MATRIX</literal> enclose a special PSPP
sub-language, called the matrix language.  The matrix language does
not require an active dataset to be defined and only a few of the
matrix language commands work with any datasets that are defined.
Each instance of <literal>MATRIX</literal>&#8230;<literal>END MATRIX</literal> is a separate
program whose state is independent of any instance, so that variables
declared within a matrix program are forgotten at its end.
</para>
<para>The matrix language works with matrices, where a <firstterm>matrix</firstterm> is a
rectangular array of real numbers.  An <inlineequation><mathphrase><replaceable>n</replaceable>×<replaceable>m</replaceable></mathphrase></inlineequation>
matrix has <replaceable>n</replaceable> rows and <replaceable>m</replaceable> columns.  Some special cases are
important: a <inlineequation><mathphrase><replaceable>n</replaceable>×1</mathphrase></inlineequation> matrix is a <firstterm>column vector</firstterm>,
a <inlineequation><mathphrase>1×<replaceable>n</replaceable></mathphrase></inlineequation> is a <firstterm>row vector</firstterm>, and a
<inlineequation><mathphrase>1×1</mathphrase></inlineequation> matrix is a <firstterm>scalar</firstterm>.
</para>
<para>The matrix language also has limited support for matrices that contain
8-byte strings instead of numbers.  Strings longer than 8 bytes are
truncated, and shorter strings are padded with spaces.  String
matrices are mainly useful for labeling rows and columns when printing
numerical matrices with the <literal>MATRIX PRINT</literal> command.  Arithmetic
operations on string matrices will not produce useful results.  The
user should not mix strings and numbers within a matrix.
</para>
<para>The matrix language does not work with cases.  A variable in the
matrix language represents a single matrix.
</para>
<para>The matrix language does not support missing values.
</para>
<para><literal>MATRIX</literal> is a procedure, so it cannot be enclosed inside <literal>DO
IF</literal>, <literal>LOOP</literal>, etc.
</para>
<para>Macros may be used within a matrix program, and macros may expand to
include entire matrix programs.  The <literal>DEFINE</literal> command may not
appear within a matrix program.  See <link linkend="DEFINE">DEFINE</link>, for more information
about macros.
</para>
<para>The following sections describe the details of the matrix language:
first, the syntax of matrix expressions, then each of the supported
commands.  The <literal>COMMENT</literal> command (see <link linkend="COMMENT">COMMENT</link>) is also
supported.
</para>
<sect2 label="16.4.1" id="Matrix-Expressions">
<title>Matrix Expressions</title>

<para>Many matrix commands use expressions.  A matrix expression may use the
following operators, listed in descending order of operator
precedence.  Within a single level, operators associate from left to
right.
</para>
<itemizedlist><listitem><para>Function call <literal>()</literal> and matrix construction <literal>{}</literal>
</para>
</listitem><listitem><para>Indexing <literal>()</literal>
</para>
</listitem><listitem><para>Unary <literal>+</literal> and <literal>-</literal>
</para>
</listitem><listitem><para>Integer sequence <literal>:</literal>
</para>
</listitem><listitem><para>Exponentiation <literal>**</literal> and <literal>&amp;**</literal>
</para>
</listitem><listitem><para>Multiplication <literal>*</literal> and <literal>&amp;*</literal>, and division <literal>/</literal> and <literal>&amp;/</literal>
</para>
</listitem><listitem><para>Addition <literal>+</literal> and subtraction <literal>-</literal>
</para>
</listitem><listitem><para>Relational <literal>&lt; &lt;= = &gt;= &gt; &lt;&gt;</literal>
</para>
</listitem><listitem><para>Logical <literal>NOT</literal>
</para>
</listitem><listitem><para>Logical <literal>AND</literal>
</para>
</listitem><listitem><para>Logical <literal>OR</literal> and <literal>XOR</literal>
</para></listitem></itemizedlist>
<para>See <link linkend="Matrix-Functions">Matrix Functions</link>, for the available matrix functions.  The
remaining operators are described in more detail below.
</para>
<indexterm role="cp"><primary>restricted expressions</primary></indexterm>
<para>Expressions appear in the matrix language in some contexts where there
would be ambiguity whether &#8216;<literal>/</literal>&#8217; is an operator or a separator
between subcommands.  In these contexts, only the operators with
higher precedence than &#8216;<literal>/</literal>&#8217; are allowed outside parentheses.
Later sections call these <firstterm>restricted expressions</firstterm>.
</para>
<sect3 label="16.4.1.1" id="Matrix-Construction-Operator">
<title>Matrix Construction Operator <literal>{}</literal></title>

<para>Use the <literal>{</literal><literal>}</literal> operator to construct matrices.  Within
the curly braces, commas separate elements within a row and semicolons
separate rows.  The following examples show a <inlineequation><mathphrase>2×3</mathphrase></inlineequation>
matrix, a <inlineequation><mathphrase>1×4</mathphrase></inlineequation> row vector, a <inlineequation><mathphrase>3×1</mathphrase></inlineequation> column
vector, and a scalar.
</para>
<informaltable><tgroup cols="3"><colspec colwidth="40*"></colspec><colspec colwidth="5*"></colspec><colspec colwidth="40*"></colspec><tbody><row><entry><para><literal>{1, 2, 3; 4, 5, 6}</literal>
</para></entry><entry><para>&#8658;
</para></entry><entry><para><literal>[1  2  3] 
 [4  5  6]</literal>
&#160;</para></entry></row><row><entry><para><literal>{3.14, 6.28, 9.24, 12.57}</literal>
</para></entry><entry><para>&#8658;
</para></entry><entry><para>[3.14  6.28  9.42  12.57]
&#160;</para></entry></row><row><entry><para><literal>{1.41; 1.73; 2}</literal>
</para></entry><entry><para>&#8658;
</para></entry><entry><para><literal>[1.41] 
 [1.73] 
 [2.00]</literal>
&#160;</para></entry></row><row><entry><para><literal>{5}</literal>
</para></entry><entry><para>&#8658;
</para></entry><entry><para>5
</para></entry></row></tbody></tgroup></informaltable>
<para>Curly braces are not limited to holding numeric literals.  They can
contain calculations, and they can paste together matrices and vectors
in any way as long as the result is rectangular.  For example, if
&#8216;<literal>m</literal>&#8217; is matrix <literal>{1, 2; 3, 4}</literal>, &#8216;<literal>r</literal>&#8217; is row vector
<literal>{5, 6}</literal>, and &#8216;<literal>c</literal>&#8217; is column vector <literal>{7, 8}</literal>, then
curly braces can be used as follows:
</para>
<informaltable><tgroup cols="3"><colspec colwidth="40*"></colspec><colspec colwidth="5*"></colspec><colspec colwidth="40*"></colspec><tbody><row><entry><para><literal>{m, c; r, 10}</literal>
</para></entry><entry><para>&#8658;
</para></entry><entry><para><literal>[1 2  7] 
 [3 4  8] 
 [5 6 10]</literal>
&#160;</para></entry></row><row><entry><para><literal>{c, 2 * c, T(r)}</literal>
</para></entry><entry><para>&#8658;
</para></entry><entry><para><literal>[7 14 5] 
 [8 16 6]</literal>
</para></entry></row></tbody></tgroup></informaltable>
<para>The final example above uses the transposition function <literal>T</literal>.
</para>
</sect3>
<sect3 label="16.4.1.2" id="Matrix-Sequence-Operator">
<title>Integer Sequence Operator &#8216;<literal>:</literal>&#8217;</title>

<para>The syntax <literal><replaceable>first</replaceable>:<replaceable>last</replaceable>:<replaceable>step</replaceable></literal> yields a row
vector of consecutive integers from <replaceable>first</replaceable> to <replaceable>last</replaceable> counting
by <replaceable>step</replaceable>.  The final <literal>:<replaceable>step</replaceable></literal> is optional and
defaults to 1 when omitted.
</para>
<para>Each of <replaceable>first</replaceable>, <replaceable>last</replaceable>, and <replaceable>step</replaceable> must be a scalar and
should be an integer (any fractional part is discarded).  Because
&#8216;<literal>:</literal>&#8217; has a high precedence, operands other than numeric literals
must usually be parenthesized.
</para>
<para>When <replaceable>step</replaceable> is positive (or omitted) and <inlineequation><mathphrase><replaceable>end</replaceable> &lt;
<replaceable>start</replaceable></mathphrase></inlineequation>, or if <replaceable>step</replaceable> is negative and <inlineequation><mathphrase><replaceable>end</replaceable> &gt;
<replaceable>start</replaceable></mathphrase></inlineequation>, then the result is an empty matrix.  If <replaceable>step</replaceable> is 0,
then PSPP reports an error.
</para>
<para>Here are some examples:
</para>
<informaltable><tgroup cols="3"><colspec colwidth="40*"></colspec><colspec colwidth="5*"></colspec><colspec colwidth="40*"></colspec><tbody><row><entry><para><literal>1:6</literal>      </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>{1, 2, 3, 4, 5, 6}</literal>
</para></entry></row><row><entry><para><literal>1:6:2</literal>    </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>{1, 3, 5}</literal>
</para></entry></row><row><entry><para><literal>-1:-5:-1</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>{-1, -2, -3, -4, -5}</literal>
</para></entry></row><row><entry><para><literal>-1:-5</literal>    </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>{}</literal>
</para></entry></row><row><entry><para><literal>2:1:0</literal>    </para></entry><entry><para>&#8658; </para></entry><entry><para>(error)
</para></entry></row></tbody></tgroup></informaltable>
</sect3>
<sect3 label="16.4.1.3" id="Matrix-Index-Operator">
<title>Index Operator <literal>()</literal></title>

<para>The result of the submatrix or indexing operator, written
<literal><replaceable>m</replaceable>(<replaceable>rindex</replaceable>, <replaceable>cindex</replaceable>)</literal>, contains the rows of
<replaceable>m</replaceable> whose indexes are given in vector <replaceable>rindex</replaceable> and the columns
whose indexes are given in vector <replaceable>cindex</replaceable>.
</para>
<para>In the simplest case, if <replaceable>rindex</replaceable> and <replaceable>cindex</replaceable> are both
scalars, the result is also a scalar:
</para>
<informaltable><tgroup cols="3"><colspec colwidth="40*"></colspec><colspec colwidth="5*"></colspec><colspec colwidth="40*"></colspec><tbody><row><entry><para><literal>{10, 20; 30, 40}(1, 1)</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>10</literal>
</para></entry></row><row><entry><para><literal>{10, 20; 30, 40}(1, 2)</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>20</literal>
</para></entry></row><row><entry><para><literal>{10, 20; 30, 40}(2, 1)</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>30</literal>
</para></entry></row><row><entry><para><literal>{10, 20; 30, 40}(2, 2)</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>40</literal>
</para></entry></row></tbody></tgroup></informaltable>
<para>If the index arguments have multiple elements, then the result
includes multiple rows or columns:
</para>
<informaltable><tgroup cols="3"><colspec colwidth="40*"></colspec><colspec colwidth="5*"></colspec><colspec colwidth="40*"></colspec><tbody><row><entry><para><literal>{10, 20; 30, 40}(1:2, 1)</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>{10; 30}</literal>
</para></entry></row><row><entry><para><literal>{10, 20; 30, 40}(2, 1:2)</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>{30, 40}</literal>
</para></entry></row><row><entry><para><literal>{10, 20; 30, 40}(1:2, 1:2)</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>{10, 20; 30, 40}</literal>
</para></entry></row></tbody></tgroup></informaltable>
<para>The special argument &#8216;<literal>:</literal>&#8217; may stand in for all the rows or columns
in the matrix being indexed, like this:
</para>
<informaltable><tgroup cols="3"><colspec colwidth="40*"></colspec><colspec colwidth="5*"></colspec><colspec colwidth="40*"></colspec><tbody><row><entry><para><literal>{10, 20; 30, 40}(:, 1)</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>{10; 30}</literal>
</para></entry></row><row><entry><para><literal>{10, 20; 30, 40}(2, :)</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>{30, 40}</literal>
</para></entry></row><row><entry><para><literal>{10, 20; 30, 40}(:, :)</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>{10, 20; 30, 40}</literal>
</para></entry></row></tbody></tgroup></informaltable>
<para>The index arguments do not have to be in order, and they may contain
repeated values, like this:
</para>
<informaltable><tgroup cols="3"><colspec colwidth="40*"></colspec><colspec colwidth="5*"></colspec><colspec colwidth="40*"></colspec><tbody><row><entry><para><literal>{10, 20; 30, 40}({2, 1}, 1)</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>{30; 10}</literal>
</para></entry></row><row><entry><para><literal>{10, 20; 30, 40}(2, {2; 2; 1})</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>{40, 40, 30}</literal>
</para></entry></row><row><entry><para><literal>{10, 20; 30, 40}(2:1:-1, :)</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>{30, 40; 10, 20}</literal>
</para></entry></row></tbody></tgroup></informaltable>
<para>When the matrix being indexed is a row or column vector, only a single
index argument is needed, like this:
</para>
<informaltable><tgroup cols="3"><colspec colwidth="40*"></colspec><colspec colwidth="5*"></colspec><colspec colwidth="40*"></colspec><tbody><row><entry><para><literal>{11, 12, 13, 14, 15}(2:4)</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>{12, 13, 14}</literal>
</para></entry></row><row><entry><para><literal>{11; 12; 13; 14; 15}(2:4)</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>{12; 13; 14}</literal>
</para></entry></row></tbody></tgroup></informaltable>
<para>When an index is not an integer, PSPP discards the fractional part.
It is an error for an index to be less than 1 or greater than the
number of rows or columns:
</para>
<informaltable><tgroup cols="3"><colspec colwidth="40*"></colspec><colspec colwidth="5*"></colspec><colspec colwidth="40*"></colspec><tbody><row><entry><para><literal>{11, 12, 13, 14}({2.5, 4.6})</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>{12, 14}</literal>
</para></entry></row><row><entry><para><literal>{11; 12; 13; 14}(0)</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para>(error)
</para></entry></row></tbody></tgroup></informaltable>
</sect3>
<sect3 label="16.4.1.4" id="Matrix-Unary-Operators">
<title>Unary Operators</title>

<para>The unary operators take a single operand of any dimensions and
operate on each of its elements independently.  The unary operators
are:
</para>
<variablelist><varlistentry><term><literal>-</literal>
</term><listitem><para>Inverts the sign of each element.
</para>
</listitem></varlistentry><varlistentry><term><literal>+</literal>
</term><listitem><para>No change.
</para>
</listitem></varlistentry><varlistentry><term><literal>NOT</literal>
</term><listitem><para>Logical inversion: each positive value becomes 0 and each zero or
negative value becomes 1.
</para></listitem></varlistentry></variablelist>
<para>Examples:
</para>
<informaltable><tgroup cols="3"><colspec colwidth="40*"></colspec><colspec colwidth="5*"></colspec><colspec colwidth="40*"></colspec><tbody><row><entry><para><literal>-{1, -2; 3, -4}</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>{-1, 2; -3, 4}</literal>
</para></entry></row><row><entry><para><literal>+{1, -2; 3, -4}</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>{1, -2; 3, -4}</literal>
</para></entry></row><row><entry><para><literal>NOT {1, 0; -1, 1}</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>{0, 1; 1, 0}</literal>
</para></entry></row></tbody></tgroup></informaltable>
</sect3>
<sect3 label="16.4.1.5" id="Matrix-Elementwise-Binary-Operators">
<title>Elementwise Binary Operators</title>

<para>The elementwise binary operators require their operands to be matrices
with the same dimensions.  Alternatively, if one operand is a scalar,
then its value is treated as if it were duplicated to the dimensions
of the other operand.  The result is a matrix of the same size as the
operands, in which each element is the result of the applying the
operator to the corresponding elements of the operands.
</para>
<para>The elementwise binary operators are listed below.
</para>
<itemizedlist><listitem><para>The arithmetic operators, for familiar arithmetic operations:
</para>
<variablelist><varlistentry><term><literal>+</literal>
</term><listitem><para>Addition.
</para>
</listitem></varlistentry><varlistentry><term><literal>-</literal>
</term><listitem><para>Subtraction.
</para>
</listitem></varlistentry><varlistentry><term><literal>*</literal>
</term><listitem><para>Multiplication, if one operand is a scalar.  (Otherwise this is matrix
multiplication, described below.)
</para>
</listitem></varlistentry><varlistentry><term><literal>/</literal> or <literal>&amp;/</literal>
</term><listitem><para>Division.
</para>
</listitem></varlistentry><varlistentry><term><literal>&amp;*</literal>
</term><listitem><para>Multiplication.
</para>
</listitem></varlistentry><varlistentry><term><literal>&amp;**</literal>
</term><listitem><para>Exponentiation.
</para></listitem></varlistentry></variablelist>
</listitem><listitem><para>The relational operators, whose results are 1 when a comparison is
true and 0 when it is false:
</para>
<variablelist><varlistentry><term><literal>&lt;</literal> or <literal>LT</literal>
</term><listitem><para>Less than.
</para>
</listitem></varlistentry><varlistentry><term><literal>&lt;=</literal> or <literal>LE</literal>
</term><listitem><para>Less than or equal.
</para>
</listitem></varlistentry><varlistentry><term><literal>=</literal> or <literal>EQ</literal>
</term><listitem><para>Equal.
</para>
</listitem></varlistentry><varlistentry><term><literal>&gt;</literal> or <literal>GT</literal>
</term><listitem><para>Greater than.
</para>
</listitem></varlistentry><varlistentry><term><literal>&gt;=</literal> or <literal>GE</literal>
</term><listitem><para>Greater than or equal.
</para>
</listitem></varlistentry><varlistentry><term><literal>&lt;&gt;</literal> or <literal>~=</literal> or <literal>NE</literal>
</term><listitem><para>Not equal.
</para></listitem></varlistentry></variablelist>
</listitem><listitem><para>The logical operators, which treat positive operands as true and
nonpositive operands as false.  They yield 0 for false and 1 for true:
</para>
<variablelist><varlistentry><term><literal>AND</literal>
</term><listitem><para>True if both operands are true.
</para>
</listitem></varlistentry><varlistentry><term><literal>OR</literal>
</term><listitem><para>True if at least one operand is true.
</para>
</listitem></varlistentry><varlistentry><term><literal>XOR</literal>
</term><listitem><para>True if exactly one operand is true.
</para></listitem></varlistentry></variablelist></listitem></itemizedlist>
<para>Examples:
</para>
<informaltable><tgroup cols="3"><colspec colwidth="40*"></colspec><colspec colwidth="5*"></colspec><colspec colwidth="40*"></colspec><tbody><row><entry><para><literal>1 + 2</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>3</literal>
</para></entry></row><row><entry><para><literal>1 + {3; 4}</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>{4; 5}</literal>
</para></entry></row><row><entry><para><literal>{66, 77; 88, 99} + 5</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>{71, 82; 93, 104}</literal>
</para></entry></row><row><entry><para><literal>{4, 8; 3, 7} + {1, 0; 5, 2}</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>{5, 8; 8, 9}</literal>
</para></entry></row><row><entry><para><literal>{1, 2; 3, 4} &lt; {4, 3; 2, 1}</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>{1, 1; 0, 0}</literal>
</para></entry></row><row><entry><para><literal>{1, 3; 2, 4} &gt;= 3</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>{0, 1; 0, 1}</literal>
</para></entry></row><row><entry><para><literal>{0, 0; 1, 1} AND {0, 1; 0, 1}</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>{0, 0; 0, 1}</literal>
</para></entry></row></tbody></tgroup></informaltable>
</sect3>
<sect3 label="16.4.1.6" id="Matrix-Multiplication-Operator">
<title>Matrix Multiplication Operator &#8216;<literal>*</literal>&#8217;</title>

<para>If <literal>A</literal> is an <inlineequation><mathphrase><replaceable>m</replaceable>×<replaceable>n</replaceable></mathphrase></inlineequation> matrix and <literal>B</literal> is
an <inlineequation><mathphrase><replaceable>n</replaceable>×<replaceable>p</replaceable></mathphrase></inlineequation> matrix, then <literal>A*B</literal> is the
<inlineequation><mathphrase><replaceable>m</replaceable>×<replaceable>p</replaceable></mathphrase></inlineequation> matrix multiplication product <literal>C</literal>.
PSPP reports an error if the number of columns in <literal>A</literal> differs
from the number of rows in <literal>B</literal>.
</para>
<para>The <literal>*</literal> operator performs elementwise multiplication (see above)
if one of its operands is a scalar.
</para>
<para>No built-in operator yields the inverse of matrix multiplication.
Instead, multiply by the result of <literal>INV</literal> or <literal>GINV</literal>.
</para>
<para>Some examples:
</para>
<informaltable><tgroup cols="3"><colspec colwidth="40*"></colspec><colspec colwidth="5*"></colspec><colspec colwidth="40*"></colspec><tbody><row><entry><para><literal>{1, 2, 3} * {4; 5; 6}</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>32</literal>
</para></entry></row><row><entry><para><literal>{4; 5; 6} * {1, 2, 3}</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>{4,&amp;#160;<!-- /@w --> 8, 12; 
&amp;#160;<!-- /@w -->5, 10, 15; 
&amp;#160;<!-- /@w -->6, 12, 18}</literal>
</para></entry></row></tbody></tgroup></informaltable>
</sect3>
<sect3 label="16.4.1.7" id="Matrix-Exponentiation-Operator">
<title>Matrix Exponentiation Operator <literal>**</literal></title>

<para>The result of <literal>A**B</literal> is defined as follows when <literal>A</literal> is a
square matrix and <literal>B</literal> is an integer scalar:
</para>
<itemizedlist><listitem><para>For <literal>B &gt; 0</literal>, <literal>A**B</literal> is <literal>A*&#8230;*A</literal>, where there are
<literal>B</literal> &#8216;<literal>A</literal>&#8217;s.  (PSPP implements this efficiently for large
<literal>B</literal>, using exponentiation by squaring.)
</para>
</listitem><listitem><para>For <literal>B &lt; 0</literal>, <literal>A**B</literal> is <literal>INV(A**(-B))</literal>.
</para>
</listitem><listitem><para>For <literal>B = 0</literal>, <literal>A**B</literal> is the identity matrix.
</para></listitem></itemizedlist>
<para>PSPP reports an error if <literal>A</literal> is not square or <literal>B</literal> is not
an integer.
</para>
<para>Examples:
</para>
<informaltable><tgroup cols="3"><colspec colwidth="40*"></colspec><colspec colwidth="5*"></colspec><colspec colwidth="40*"></colspec><tbody><row><entry><para><literal>{2, 5; 1, 4}**3</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>{48, 165; 33, 114}</literal>
</para></entry></row><row><entry><para><literal>{2, 5; 1, 4}**0</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>{1, 0; 0, 1}</literal>
</para></entry></row><row><entry><para><literal>10*{4, 7; 2, 6}**-1</literal> </para></entry><entry><para>&#8658; </para></entry><entry><para><literal>{6, -7; -2, 4}</literal>
</para></entry></row></tbody></tgroup></informaltable>
</sect3>
</sect2>
<sect2 label="16.4.2" id="Matrix-Functions">
<title>Matrix Functions</title>

<para>The matrix language support numerous functions in multiple categories.
The following subsections document each of the currently supported
functions.  The first letter of each parameter&#8217;s name indicate the
required argument type:
</para>
<variablelist><varlistentry><term><replaceable>s</replaceable>
</term><listitem><para>A scalar.
</para>
</listitem></varlistentry><varlistentry><term><replaceable>n</replaceable>
</term><listitem><para>A nonnegative integer scalar.  (Non-integers are accepted and silently
rounded down to the nearest integer.)
</para>
</listitem></varlistentry><varlistentry><term><replaceable>V</replaceable>
</term><listitem><para>A row or column vector.
</para>
</listitem></varlistentry><varlistentry><term><replaceable>M</replaceable>
</term><listitem><para>A matrix.
</para></listitem></varlistentry></variablelist>
<sect3 label="16.4.2.1" id="Matrix-Elementwise-Functions">
<title>Elementwise Functions</title>

<para>These functions act on each element of their argument independently,
like the elementwise operators (see <link linkend="Matrix-Elementwise-Binary-Operators">Matrix Elementwise Binary
Operators</link>).
</para>
<synopsis><indexterm role="fn"><primary>ABS</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>ABS</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<blockquote><para>Takes the absolute value of each element of <replaceable>M</replaceable>.
</para>
<para><literal>ABS({-1, 2; -3, 0}) &#8658; {1, 2; 3, 0}</literal>
</para></blockquote>
<synopsis><indexterm role="fn"><primary>ARSIN</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>ARSIN</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>ARTAN</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>ARTAN</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<blockquote><para>Computes the inverse sine or tangent, respectively, of each element in
<replaceable>M</replaceable>.  The results are in radians, between <inlineequation><mathphrase>-\pi/2</mathphrase></inlineequation> and
<inlineequation><mathphrase>+\pi/2</mathphrase></inlineequation>, inclusive.
</para>
<para>The value of <inlineequation><mathphrase>\pi</mathphrase></inlineequation> can be computed as <literal>4*ARTAN(1)</literal>.
</para>
<para><literal>ARSIN({-1, 0, 1}) &#8658; {-1.57, 0, 1.57}</literal> (approximately)
</para>
<para><literal>ARTAN({-5, -1, 1, 5}) &#8658; {-1.37, -.79, .79, 1.37}</literal> (approximately)
</para></blockquote>
<synopsis><indexterm role="fn"><primary>COS</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>COS</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>SIN</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>SIN</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<blockquote><para>Computes the cosine or sine, respectively, of each element in <replaceable>M</replaceable>,
which must be in radians.
</para>
<para><literal>COS({0.785, 1.57; 3.14, 1.57 + 3.14}) &#8658; {.71, 0; -1, 0}</literal> (approximately)
</para></blockquote>
<synopsis><indexterm role="fn"><primary>EXP</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>EXP</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<blockquote><para>Computes <inlineequation><mathphrase>e^x</mathphrase></inlineequation> for each element <replaceable>x</replaceable> in <replaceable>M</replaceable>.
</para>
<para><literal>EXP({2, 3; 4, 5}) &#8658; {7.39, 20.09; 54.6, 148.4}</literal> (approximately)
</para></blockquote>
<synopsis><indexterm role="fn"><primary>LG10</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>LG10</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>LN</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>LN</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<blockquote><para>Takes the logarithm with base 10 or base <inlineequation><mathphrase>e</mathphrase></inlineequation>, respectively, of
each element in <replaceable>M</replaceable>.
</para>
<para><literal>LG10({1, 10, 100, 1000}) &#8658; {0, 1, 2, 3}</literal> 

<literal>LG10(0) &#8658;</literal> (error)
</para>
<para><literal>LN({EXP(1), 1, 2, 3, 4}) &#8658; {1, 0, .69, 1.1, 1.39}</literal> (approximately) 

<literal>LN(0) &#8658;</literal> (error)
</para></blockquote>
<synopsis><indexterm role="fn"><primary>MOD</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>MOD</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>, <emphasis role="arg"><replaceable>s</replaceable></emphasis>)</synopsis>
<blockquote><para>Takes each element in <replaceable>M</replaceable> modulo nonzero scalar value <replaceable>s</replaceable>,
that is, the remainder of division by <replaceable>s</replaceable>.  The sign of the result
is the same as the sign of the dividend.
</para>
<para><literal>MOD({5, 4, 3, 2, 1, 0}, 3) &#8658; {2, 1, 0, 2, 1, 0}</literal> 

<literal>MOD({5, 4, 3, 2, 1, 0}, -3) &#8658; {2, 1, 0, 2, 1, 0}</literal> 

<literal>MOD({-5, -4, -3, -2, -1, 0}, 3) &#8658; {-2, -1, 0, -2, -1, 0}</literal> 

<literal>MOD({-5, -4, -3, -2, -1, 0}, -3) &#8658; {-2, -1, 0, -2, -1, 0}</literal> 

<literal>MOD({5, 4, 3, 2, 1, 0}, 1.5) &#8658; {.5, 1.0, .0, .5, 1.0, .0}</literal> 

<literal>MOD({5, 4, 3, 2, 1, 0}, 0) &#8658;</literal> (error)
</para></blockquote>
<synopsis><indexterm role="fn"><primary>RND</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>RND</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>TRUNC</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>TRUNC</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<blockquote><para>Rounds each element of <replaceable>M</replaceable> to an integer.  <literal>RND</literal> rounds to
the nearest integer, with halves rounded to even integers, and
<literal>TRUNC</literal> rounds toward zero.
</para>
<para><literal>RND({-1.6, -1.5, -1.4}) &#8658; {-2, -2, -1}</literal> 

<literal>RND({-.6, -.5, -.4}) &#8658; {-1, 0, 0}</literal> 

<literal>RND({.4, .5, .6} &#8658; {0, 0, 1}</literal> 

<literal>RND({1.4, 1.5, 1.6}) &#8658; {1, 2, 2}</literal>
</para>
<para><literal>TRUNC({-1.6, -1.5, -1.4}) &#8658; {-1, -1, -1}</literal> 

<literal>TRUNC({-.6, -.5, -.4}) &#8658; {0, 0, 0}</literal> 

<literal>TRUNC({.4, .5, .6} &#8658; {0, 0, 0}</literal> 

<literal>TRUNC({1.4, 1.5, 1.6}) &#8658; {1, 1, 1}</literal>
</para></blockquote>
<synopsis><indexterm role="fn"><primary>SQRT</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>SQRT</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<blockquote><para>Takes the square root of each element of <replaceable>M</replaceable>, which must not be
negative.
</para>
<para><literal>SQRT({0, 1, 2, 4, 9, 81}) &#8658; {0, 1, 1.41, 2, 3, 9}</literal> (approximately) 

<literal>SQRT(-1) &#8658;</literal> (error)
</para></blockquote>
</sect3>
<sect3 label="16.4.2.2" id="Matrix-Logical-Functions">
<title>Logical Functions</title>

<synopsis><indexterm role="fn"><primary>ALL</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>ALL</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns a scalar with value 1 if all of the elements in <replaceable>M</replaceable> are
nonzero, or 0 if at least one element is zero.
</para>
<para><literal>ALL({1, 2, 3} &lt; {2, 3, 4}) &#8658; 1</literal> 

<literal>ALL({2, 2, 3} &lt; {2, 3, 4}) &#8658; 0</literal> 

<literal>ALL({2, 3, 3} &lt; {2, 3, 4}) &#8658; 0</literal> 

<literal>ALL({2, 3, 4} &lt; {2, 3, 4}) &#8658; 0</literal>
</para></blockquote>
<synopsis><indexterm role="fn"><primary>ANY</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>ANY</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns a scalar with value 1 if any of the elements in <replaceable>M</replaceable> is
nonzero, or 0 if all of them are zero.
</para>
<para><literal>ANY({1, 2, 3} &lt; {2, 3, 4}) &#8658; 1</literal> 

<literal>ANY({2, 2, 3} &lt; {2, 3, 4}) &#8658; 1</literal> 

<literal>ANY({2, 3, 3} &lt; {2, 3, 4}) &#8658; 1</literal> 

<literal>ANY({2, 3, 4} &lt; {2, 3, 4}) &#8658; 0</literal>
</para></blockquote>
</sect3>
<sect3 label="16.4.2.3" id="Matrix-Construction-Functions">
<title>Matrix Construction Functions</title>

<synopsis><indexterm role="fn"><primary>BLOCK</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>BLOCK</function> (<emphasis role="arg"><replaceable>M1</replaceable></emphasis>, <emphasis role="arg">&#8230;</emphasis>, <emphasis role="arg"><replaceable>Mn</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns a block diagonal matrix with as many rows as the sum of its
arguments&#8217; row counts and as many columns as the sum of their columns.
Each argument matrix is placed along the main diagonal of the result,
and all other elements are zero.
</para>
<literallayout><literal>BLOCK({1, 2; 3, 4}, 5, {7; 8; 9}, {10, 11}) &#8658;
   1   2   0   0   0   0
   3   4   0   0   0   0
   0   0   5   0   0   0
   0   0   0   7   0   0
   0   0   0   8   0   0
   0   0   0   9   0   0
   0   0   0   0  10  11</literal>
</literallayout></blockquote>
<synopsis><indexterm role="fn"><primary>IDENT</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>IDENT</function> (<emphasis role="arg"><replaceable>n</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDENT</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>IDENT</function> (<emphasis role="arg"><replaceable>nr</replaceable></emphasis>, <emphasis role="arg"><replaceable>nc</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns an identity matrix, whose main diagonal elements are one and
whose other elements are zero.  The returned matrix has <replaceable>n</replaceable> rows
and columns or <replaceable>nr</replaceable> rows and <replaceable>nc</replaceable> columns, respectively.
</para>
<literallayout><literal>IDENT(1) &#8658; 1
IDENT(2) &#8658;
  1  0
  0  1
IDENT(3, 5) &#8658;
  1  0  0  0  0
  0  1  0  0  0
  0  0  1  0  0
IDENT(5, 3) &#8658;
  1  0  0
  0  1  0
  0  0  1
  0  0  0
  0  0  0</literal>
</literallayout></blockquote>
<synopsis><indexterm role="fn"><primary>MAGIC</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>MAGIC</function> (<emphasis role="arg"><replaceable>n</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns an <inlineequation><mathphrase><replaceable>n</replaceable>×<replaceable>n</replaceable></mathphrase></inlineequation> matrix that contains each of
the integers <inlineequation><mathphrase>1&#8230;<replaceable>n</replaceable></mathphrase></inlineequation> once, in which each column, each
row, and each diagonal sums to <inlineequation><mathphrase>n(n^2+1)/2</mathphrase></inlineequation>.  There are many
magic squares with given dimensions, but this function always returns
the same one for a given value of <replaceable>n</replaceable>.
</para>
<para><literal>MAGIC(3) &#8658; {8, 1, 6; 3, 5, 7; 4, 9, 2}</literal> 

<literal>MAGIC(4) &#8658; {1, 5, 12, 16; 15, 11, 6, 2; 14, 8, 9, 3; 4, 10, 7, 13}</literal>
</para></blockquote>
<synopsis><indexterm role="fn"><primary>MAKE</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>MAKE</function> (<emphasis role="arg"><replaceable>nr</replaceable></emphasis>, <emphasis role="arg"><replaceable>nc</replaceable></emphasis>, <emphasis role="arg"><replaceable>s</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns an <inlineequation><mathphrase><replaceable>nr</replaceable>×<replaceable>nc</replaceable></mathphrase></inlineequation> matrix whose elements are
all <replaceable>s</replaceable>.
</para>
<para><literal>MAKE(1, 2, 3) &#8658; {3, 3}</literal> 

<literal>MAKE(2, 1, 4) &#8658; {4; 4}</literal> 

<literal>MAKE(2, 3, 5) &#8658; {5, 5, 5; 5, 5, 5}</literal>
</para></blockquote>
<synopsis><indexterm role="fn"><primary>MDIAG</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>MDIAG</function> (<emphasis role="arg"><replaceable>V</replaceable></emphasis>)</synopsis>
<blockquote><anchor id="MDIAG"/><para>Given <replaceable>n</replaceable>-element vector <replaceable>V</replaceable>, returns a
<inlineequation><mathphrase><replaceable>n</replaceable>×<replaceable>n</replaceable></mathphrase></inlineequation> matrix whose main diagonal is copied
from <replaceable>V</replaceable>.  The other elements in the returned vector are zero.
</para>
<para>Use <literal>CALL SETDIAG</literal> (see <link linkend="CALL-SETDIAG">CALL SETDIAG</link>) to replace the main
diagonal of a matrix in-place.
</para>
<literallayout><literal>MDIAG({1, 2, 3, 4}) &#8658;
  1  0  0  0
  0  2  0  0
  0  0  3  0
  0  0  0  4</literal>
</literallayout></blockquote>
<synopsis><indexterm role="fn"><primary>RESHAPE</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>RESHAPE</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>, <emphasis role="arg"><replaceable>nr</replaceable></emphasis>, <emphasis role="arg"><replaceable>nc</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns an <inlineequation><mathphrase><replaceable>nr</replaceable>×<replaceable>nc</replaceable></mathphrase></inlineequation> matrix whose elements come
from <replaceable>M</replaceable>, which must have the same number of elements as the new
matrix, copying elements from <replaceable>M</replaceable> to the new matrix row by row.
</para>
<literallayout><literal>RESHAPE(1:12, 1, 12) &#8658;
   1   2   3   4   5   6   7   8   9  10  11  12
RESHAPE(1:12, 2, 6) &#8658;
   1   2   3   4   5   6
   7   8   9  10  11  12
RESHAPE(1:12, 3, 4) &#8658;
   1   2   3   4
   5   6   7   8
   9  10  11  12
RESHAPE(1:12, 4, 3) &#8658;
   1   2   3
   4   5   6
   7   8   9
  10  11  12</literal>
</literallayout></blockquote>
<synopsis><indexterm role="fn"><primary>T</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>T</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>TRANSPOS</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>TRANSPOS</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns <replaceable>M</replaceable> with rows exchanged for columns.
</para>
<para><literal>T({1, 2, 3}) &#8658; {1; 2; 3}</literal> 

<literal>T({1; 2; 3}) &#8658; {1, 2, 3}</literal>
</para></blockquote>
<synopsis><indexterm role="fn"><primary>UNIFORM</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>UNIFORM</function> (<emphasis role="arg"><replaceable>nr</replaceable></emphasis>, <emphasis role="arg"><replaceable>nc</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns a <inlineequation><mathphrase><replaceable>nr</replaceable>×<replaceable>nc</replaceable></mathphrase></inlineequation> matrix in which each element
is randomly chosen from a uniform distribution of real numbers between
0 and 1.  Random number generation honors the current seed setting
(see <link linkend="SET-SEED">SET SEED</link>).
</para>
<para>The following example shows one possible output, but of course every
result will be different (given different seeds):
</para>
<literallayout><literal>UNIFORM(4, 5)*10 &#8658;
  7.71  2.99   .21  4.95  6.34
  4.43  7.49  8.32  4.99  5.83
  2.25   .25  1.98  7.09  7.61
  2.66  1.69  2.64   .88  1.50</literal>
</literallayout></blockquote>
</sect3>
<sect3 label="16.4.2.4" id="Matrix-Minimum-and-Maximum-and-Sum-Functions">
<title>Minimum, Maximum, and Sum Functions</title>

<synopsis><indexterm role="fn"><primary>CMIN</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>CMIN</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>CMAX</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>CMAX</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>CSUM</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>CSUM</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>CSSQ</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>CSSQ</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns a row vector with the same number of columns as <replaceable>M</replaceable>, in
which each element is the minimum, maximum, sum, or sum of squares,
respectively, of the elements in the same column of <replaceable>M</replaceable>.
</para>
<para><literal>CMIN({1, 2, 3; 4, 5, 6; 7, 8, 9} &#8658; {1, 2, 3}</literal> 

<literal>CMAX({1, 2, 3; 4, 5, 6; 7, 8, 9} &#8658; {7, 8, 9}</literal> 

<literal>CSUM({1, 2, 3; 4, 5, 6; 7, 8, 9} &#8658; {12, 15, 18}</literal> 

<literal>CSSQ({1, 2, 3; 4, 5, 6; 7, 8, 9} &#8658; {66, 93, 126}</literal>
</para></blockquote>
<synopsis><indexterm role="fn"><primary>MMIN</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>MMIN</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>MMAX</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>MMAX</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>MSUM</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>MSUM</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>MSSQ</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>MSSQ</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns the minimum, maximum, sum, or sum of squares, respectively, of
the elements of <replaceable>M</replaceable>.
</para>
<para><literal>MMIN({1, 2, 3; 4, 5, 6; 7, 8, 9} &#8658; 1</literal> 

<literal>MMAX({1, 2, 3; 4, 5, 6; 7, 8, 9} &#8658; 9</literal> 

<literal>MSUM({1, 2, 3; 4, 5, 6; 7, 8, 9} &#8658; 45</literal> 

<literal>MSSQ({1, 2, 3; 4, 5, 6; 7, 8, 9} &#8658; 285</literal>
</para></blockquote>
<synopsis><indexterm role="fn"><primary>RMIN</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>RMIN</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RMAX</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>RMAX</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RSUM</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>RSUM</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>RSSQ</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>RSSQ</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns a column vector with the same number of rows as <replaceable>M</replaceable>, in
which each element is the minimum, maximum, sum, or sum of squares,
respectively, of the elements in the same row of <replaceable>M</replaceable>.
</para>
<para><literal>RMIN({1, 2, 3; 4, 5, 6; 7, 8, 9} &#8658; {1; 4; 7}</literal> 

<literal>RMAX({1, 2, 3; 4, 5, 6; 7, 8, 9} &#8658; {3; 6; 9}</literal> 

<literal>RSUM({1, 2, 3; 4, 5, 6; 7, 8, 9} &#8658; {6; 15; 24}</literal> 

<literal>RSSQ({1, 2, 3; 4, 5, 6; 7, 8, 9} &#8658; {14; 77; 194}</literal>
</para></blockquote>
<synopsis><indexterm role="fn"><primary>SSCP</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>SSCP</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns <inlineequation><mathphrase><replaceable>M</replaceable>^T × <replaceable>M</replaceable></mathphrase></inlineequation>.
</para>
<para><literal>SSCP({1, 2, 3; 4, 5, 6}) &#8658; {17, 22, 27; 22, 29, 36; 27, 36, 45}</literal>
</para></blockquote>
<synopsis><indexterm role="fn"><primary>TRACE</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>TRACE</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns the sum of the elements along <replaceable>M</replaceable>&#8217;s main diagonal,
equivalent to <literal>MSUM(DIAG(<replaceable>M</replaceable>))</literal>.
</para>
<para><literal>TRACE(MDIAG(1:5)) &#8658; 15</literal>
</para></blockquote>
</sect3>
<sect3 label="16.4.2.5" id="Matrix-Property-Functions">
<title>Matrix Property Functions</title>

<synopsis><indexterm role="fn"><primary>NROW</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>NROW</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<synopsis><indexterm role="fn"><primary>NCOL</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>NCOL</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns the number of row or columns, respectively, in <replaceable>M</replaceable>.
</para>
<literallayout><literal>NROW({1, 0; -2, -3; 3, 3}) &#8658; 3
NROW(1:5) &#8658; 1

NCOL({1, 0; -2, -3; 3, 3}) &#8658; 2
NCOL(1:5) &#8658; 5</literal>
</literallayout></blockquote>
<synopsis><indexterm role="fn"><primary>DIAG</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>DIAG</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns a column vector containing a copy of <replaceable>M</replaceable>&#8217;s main diagonal.
The vector&#8217;s length is the lesser of <literal>NCOL(<replaceable>M</replaceable>)</literal> and
<literal>NROW(<replaceable>M</replaceable>)</literal>.
</para>
<para><literal>DIAG({1, 0; -2, -3; 3, 3}) &#8658; {1; -3}</literal>
</para></blockquote>
</sect3>
<sect3 label="16.4.2.6" id="Matrix-Rank-Ordering-Functions">
<title>Matrix Rank Ordering Functions</title>

<para>The <literal>GRADE</literal> and <literal>RANK</literal> functions each take a matrix <replaceable>M</replaceable>
and return a matrix <replaceable>r</replaceable> with the same dimensions.  Each element in
<replaceable>r</replaceable> ranges between 1 and the number of elements <replaceable>n</replaceable> in
<replaceable>M</replaceable>, inclusive.  When the elements in <replaceable>M</replaceable> all have unique
values, both of these functions yield the same results: the smallest
element in <replaceable>M</replaceable> corresponds to value 1 in <replaceable>r</replaceable>, the next
smallest to 2, and so on, up to the largest to <replaceable>n</replaceable>.  When multiple
elements in <replaceable>M</replaceable> have the same value, these functions use different
rules for handling the ties.
</para>
<synopsis><indexterm role="fn"><primary>GRADE</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>GRADE</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns a ranking of <replaceable>M</replaceable>, turning duplicate values into sequential
ranks.  The returned matrix always contains each of the integers 1
through the number of elements in the matrix exactly once.
</para>
<para><literal>GRADE({1, 0, 3; 3, 1, 2; 3, 0, 5})</literal> &#8658; <literal>{3, 1, 6; 7, 4, 5; 8, 2, 9}</literal>
</para></blockquote>
<synopsis><indexterm role="fn"><primary>RNKORDER</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>RNKORDER</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns a ranking of <replaceable>M</replaceable>, turning duplicate values into the mean
of their sequential ranks.
</para>
<para><literal>RNKORDER({1, 0, 3; 3, 1, 2; 3, 0, 5})</literal> 
&amp;#160;<!-- /@w -->&#8658; <literal>{3.5, 1.5, 7; 7, 3.5, 5; 7, 1.5, 9}</literal>
</para></blockquote>
<para>One may use <literal>GRADE</literal> to sort a vector:
</para>
<screen>COMPUTE v(GRADE(v))=v.   /* Sort v in ascending order.
COMPUTE v(GRADE(-v))=v.  /* Sort v in descending order.
</screen>
</sect3>
<sect3 label="16.4.2.7" id="Matrix-Algebra-Functions">
<title>Matrix Algebra Functions</title>

<synopsis><indexterm role="fn"><primary>CHOL</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>CHOL</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<blockquote><para>Matrix <replaceable>M</replaceable> must be an <inlineequation><mathphrase><replaceable>n</replaceable>×<replaceable>n</replaceable></mathphrase></inlineequation> symmetric
positive-definite matrix.  Returns an <inlineequation><mathphrase><replaceable>n</replaceable>×<replaceable>n</replaceable></mathphrase></inlineequation>
matrix <replaceable>B</replaceable> such that <inlineequation><mathphrase><replaceable>B</replaceable>^T×<replaceable>B</replaceable>=<replaceable>M</replaceable></mathphrase></inlineequation>.
</para>
<literallayout><literal>CHOL({4, 12, -16; 12, 37, -43; -16, -43, 98}) &#8658;
  2  6 -8
  0  1  5
  0  0  3</literal>
</literallayout></blockquote>
<synopsis><indexterm role="fn"><primary>DESIGN</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>DESIGN</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns a design matrix for <replaceable>M</replaceable>.  The design matrix has the same
number of rows as <replaceable>M</replaceable>.  Each column <replaceable>c</replaceable> in <replaceable>M</replaceable>, from left
to right, yields a group of columns in the output.  For each unique
value <replaceable>v</replaceable> in <replaceable>c</replaceable>, from top to bottom, add a column to the
output in which <replaceable>v</replaceable> becomes 1 and other values become 0.
</para>
<para>PSPP issues a warning if a column only contains a single unique value.
</para>
<literallayout><literal>DESIGN({1; 2; 3}) &#8658; {1, 0, 0; 0, 1, 0; 0, 0, 1}</literal>
<literal>DESIGN({5; 8; 5}) &#8658; {1, 0; 0, 1; 1, 0}</literal>
<literal>DESIGN({1, 5; 2, 8; 3, 5})</literal>
 &#8658; <literal>{1, 0, 0, 1, 0; 0, 1, 0, 0, 1; 0, 0, 1, 1, 0}</literal>
<literal>DESIGN({5; 5; 5})</literal> &#8658; (warning)
</literallayout></blockquote>
<synopsis><indexterm role="fn"><primary>DET</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>DET</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns the determinant of square matrix <replaceable>M</replaceable>.
</para>
<para><literal>DET({3, 7; 1, -4}) &#8658; -19</literal>
</para></blockquote>
<synopsis><indexterm role="fn"><primary>EVAL</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>EVAL</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<blockquote><anchor id="EVAL"/><para>Returns a column vector containing the eigenvalues of symmetric matrix
<replaceable>M</replaceable>, sorted in ascending order.
</para>
<para>Use <literal>CALL EIGEN</literal> (see <link linkend="CALL-EIGEN">CALL EIGEN</link>) to compute eigenvalues and
eigenvectors of a matrix.
</para>
<para><literal>EVAL({2, 0, 0; 0, 3, 4; 0, 4, 9}) &#8658; {11; 2; 1}</literal>
</para></blockquote>
<synopsis><indexterm role="fn"><primary>GINV</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>GINV</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns the <inlineequation><mathphrase><replaceable>k</replaceable>×<replaceable>n</replaceable></mathphrase></inlineequation> matrix <replaceable>A</replaceable> that is the
<firstterm>generalized inverse</firstterm> of <inlineequation><mathphrase><replaceable>n</replaceable>×<replaceable>k</replaceable></mathphrase></inlineequation> matrix
<replaceable>M</replaceable>, defined such that
<inlineequation><mathphrase><replaceable>M</replaceable>×<replaceable>A</replaceable>×<replaceable>M</replaceable>=<replaceable>M</replaceable></mathphrase></inlineequation> and
<inlineequation><mathphrase><replaceable>A</replaceable>×<replaceable>M</replaceable>×<replaceable>A</replaceable>=<replaceable>A</replaceable></mathphrase></inlineequation>.
</para>
<para><literal>GINV({1, 2}) &#8658; {.2; .4}</literal> (approximately) 

<literal>{1:9} * GINV(1:9) * {1:9} &#8658; {1:9}</literal> (approximately)
</para></blockquote>
<synopsis><indexterm role="fn"><primary>GSCH</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>GSCH</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<blockquote><para><replaceable>M</replaceable> must be a <inlineequation><mathphrase><replaceable>n</replaceable>×<replaceable>m</replaceable></mathphrase></inlineequation> matrix, <inlineequation><mathphrase><replaceable>m</replaceable>
&#8805; <replaceable>n</replaceable></mathphrase></inlineequation>, with rank <replaceable>n</replaceable>.  Returns an
<inlineequation><mathphrase><replaceable>n</replaceable>×<replaceable>n</replaceable></mathphrase></inlineequation> orthonormal basis for <replaceable>M</replaceable>, obtained
using the Gram-Schmidt process.
</para>
<para><literal>GSCH({3, 2; 1, 2}) * SQRT(10) &#8658; {3, -1; 1, 3}</literal> (approximately)
</para></blockquote>
<synopsis><indexterm role="fn"><primary>INV</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>INV</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns the <inlineequation><mathphrase><replaceable>n</replaceable>×<replaceable>n</replaceable></mathphrase></inlineequation> matrix <replaceable>A</replaceable> that is the
inverse of <inlineequation><mathphrase><replaceable>n</replaceable>×<replaceable>n</replaceable></mathphrase></inlineequation> matrix <replaceable>M</replaceable>, defined such
that <inlineequation><mathphrase><replaceable>M</replaceable>×<replaceable>A</replaceable> = <replaceable>A</replaceable>×<replaceable>M</replaceable> = I</mathphrase></inlineequation>, where
<replaceable>I</replaceable> is the identity matrix.  <replaceable>M</replaceable> must not be singular, that
is, <inlineequation><mathphrase>\det(<replaceable>M</replaceable>) ≠ 0</mathphrase></inlineequation>.
</para>
<para><literal>INV({4, 7; 2, 6}) &#8658; {.6, -.7; -.2, .4}</literal> (approximately)
</para></blockquote>
<synopsis><indexterm role="fn"><primary>KRONEKER</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>KRONEKER</function> (<emphasis role="arg"><replaceable>Ma</replaceable></emphasis>, <emphasis role="arg"><replaceable>Mb</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns the <inlineequation><mathphrase><replaceable>pm</replaceable>×<replaceable>qn</replaceable></mathphrase></inlineequation> matrix <replaceable>P</replaceable> that is the
<firstterm>Kroneker product</firstterm> of <inlineequation><mathphrase><replaceable>m</replaceable>×<replaceable>n</replaceable></mathphrase></inlineequation> matrix
<replaceable>Ma</replaceable> and <inlineequation><mathphrase><replaceable>p</replaceable>×<replaceable>q</replaceable></mathphrase></inlineequation> matrix <replaceable>Mb</replaceable>.  One may
view <replaceable>P</replaceable> as the concatenation of multiple
<inlineequation><mathphrase><replaceable>p</replaceable>×<replaceable>q</replaceable></mathphrase></inlineequation> blocks, each of which is the scalar
product of <replaceable>Mb</replaceable> by a different element of <replaceable>Ma</replaceable>.  For example,
when <literal>A</literal> is a <inlineequation><mathphrase>2×2</mathphrase></inlineequation> matrix, <literal>KRONEKER(A, B)</literal> is
equivalent to <literal>{A(1,1)*B, A(1,2)*B; A(2,1)*B, A(2,2)*B}</literal>.
</para>
<literallayout><literal>KRONEKER({1, 2; 3, 4}, {0, 5; 6, 7}) &#8658;
   0   5   0  10
   6   7  12  14
   0  15   0  20
  18  21  24  28</literal>
</literallayout></blockquote>
<synopsis><indexterm role="fn"><primary>RANK</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>RANK</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<blockquote><para>Returns the rank of matrix <replaceable>M</replaceable>, an integer scalar whose value is
the dimension of the vector space spanned by its columns or,
equivalently, by its rows.
</para>
<literallayout><literal>RANK({1, 0, 1; -2, -3, 1; 3, 3, 0}) &#8658; 2
RANK({1, 1, 0, 2; -1, -1, 0, -2}) &#8658; 1
RANK({1, -1; 1, -1; 0, 0; 2, -2}) &#8658; 1
RANK({1, 2, 1; -2, -3, 1; 3, 5, 0}) &#8658; 2
RANK({1, 0, 2; 2, 1, 0; 3, 2, 1}) &#8658; 3</literal>
</literallayout></blockquote>
<synopsis><indexterm role="fn"><primary>SOLVE</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>SOLVE</function> (<emphasis role="arg"><replaceable>Ma</replaceable></emphasis>, <emphasis role="arg"><replaceable>Mb</replaceable></emphasis>)</synopsis>
<blockquote><para><replaceable>Ma</replaceable> must be an <inlineequation><mathphrase><replaceable>n</replaceable>×<replaceable>n</replaceable></mathphrase></inlineequation> matrix, with
<inlineequation><mathphrase>\det(<replaceable>Ma</replaceable>) ≠ 0</mathphrase></inlineequation>, and <replaceable>Mb</replaceable> an
<inlineequation><mathphrase><replaceable>n</replaceable>×<replaceable>k</replaceable></mathphrase></inlineequation> matrix.  Returns an
<inlineequation><mathphrase><replaceable>n</replaceable>×<replaceable>k</replaceable></mathphrase></inlineequation> matrix <replaceable>X</replaceable> such that <inlineequation><mathphrase><replaceable>Ma</replaceable>
× <replaceable>X</replaceable> = <replaceable>Mb</replaceable></mathphrase></inlineequation>.
</para>
<para>All of the following examples show approximate results:
</para>
<literallayout><literal>SOLVE({2, 3; 4, 9}, {6, 2; 15, 5}) &#8658;
   1.50    .50
   1.00    .33
SOLVE({1, 3, -2; 3, 5, 6; 2, 4, 3}, {5; 7; 8}) &#8658;
 -15.00
   8.00
   2.00
SOLVE({2, 1, -1; -3, -1, 2; -2, 1, 2}, {8; -11; -3}) &#8658;
   2.00
   3.00
  -1.00</literal>
</literallayout></blockquote>
<synopsis><indexterm role="fn"><primary>SVAL</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>SVAL</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>)</synopsis>
<blockquote><anchor id="SVAL"/>
<para>Given <inlineequation><mathphrase><replaceable>n</replaceable>×<replaceable>k</replaceable></mathphrase></inlineequation> matrix <replaceable>M</replaceable>, returns a
<inlineequation><mathphrase>\min(<replaceable>n</replaceable>,<replaceable>k</replaceable>)</mathphrase></inlineequation>-element column vector containing the
singular values of <replaceable>M</replaceable> in descending order.
</para>
<para>Use <literal>CALL SVD</literal> (see <link linkend="CALL-SVD">CALL SVD</link>) to compute the full singular
value decomposition of a matrix.
</para>
<literallayout><literal>SVAL({1, 1; 0, 0}) &#8658; {1.41; .00}
SVAL({1, 0, 1; 0, 1, 1; 0, 0, 0}) &#8658; {1.73; 1.00; .00}
SVAL({2, 4; 1, 3; 0, 0; 0, 0}) &#8658; {5.46; .37}</literal>
</literallayout></blockquote>
<synopsis><indexterm role="fn"><primary>SWEEP</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>SWEEP</function> (<emphasis role="arg"><replaceable>M</replaceable></emphasis>, <emphasis role="arg"><replaceable>nk</replaceable></emphasis>)</synopsis>
<blockquote><para>Given <inlineequation><mathphrase><replaceable>r</replaceable>×<replaceable>c</replaceable></mathphrase></inlineequation> matrix <replaceable>M</replaceable> and integer scalar
<inlineequation><mathphrase>k = <replaceable>nk</replaceable></mathphrase></inlineequation> such that <inlineequation><mathphrase>1 &#8804; k &#8804;
\min(<replaceable>r</replaceable>,<replaceable>c</replaceable>)</mathphrase></inlineequation>, returns the <inlineequation><mathphrase><replaceable>r</replaceable>×<replaceable>c</replaceable></mathphrase></inlineequation>
sweep matrix <replaceable>A</replaceable>.
</para>
<para>If <inlineequation><mathphrase><replaceable>M</replaceable>_{kk} ≠ 0</mathphrase></inlineequation>, then:
</para>
<literallayout><inlineequation><mathphrase><replaceable>A</replaceable>_{kk} = 1/<replaceable>M</replaceable>_{kk}</mathphrase></inlineequation>,
<inlineequation><mathphrase><replaceable>A</replaceable>_{ik} = -<replaceable>M</replaceable>_{ik}/<replaceable>M</replaceable>_{kk} for i ≠ k</mathphrase></inlineequation>,
<inlineequation><mathphrase><replaceable>A</replaceable>_{kj} = <replaceable>M</replaceable>_{kj}/<replaceable>M</replaceable>_{kk} for j ≠ k, and</mathphrase></inlineequation>
<inlineequation><mathphrase><replaceable>A</replaceable>_{ij} = <replaceable>M</replaceable>_{ij} - <replaceable>M</replaceable>_{ik}<replaceable>M</replaceable>_{kj}/<replaceable>M</replaceable>_{kk} for i ≠ k and j ≠ k</mathphrase></inlineequation>.
</literallayout>
<para>If <inlineequation><mathphrase><replaceable>M</replaceable>_{kk} = 0</mathphrase></inlineequation>, then:
</para>
<literallayout><inlineequation><mathphrase><replaceable>A</replaceable>_{ik} = <replaceable>A</replaceable>_{ki} = 0 and</mathphrase></inlineequation>
<inlineequation><mathphrase><replaceable>A</replaceable>_{ij} = <replaceable>M</replaceable>_{ij}, for i ≠ k and j ≠ k</mathphrase></inlineequation>.
</literallayout>
<para>Given <literal>M = {0, 1, 2; 3, 4, 5; 6, 7, 8}</literal>, then (approximately):
</para>
<literallayout><literal>SWEEP(M, 1) &#8658;
   .00   .00   .00
   .00  4.00  5.00
   .00  7.00  8.00
SWEEP(M, 2) &#8658;
  -.75  -.25   .75
   .75   .25  1.25
   .75 -1.75  -.75
SWEEP(M, 3) &#8658;
 -1.50  -.75  -.25
  -.75  -.38  -.63
   .75   .88   .13</literal>
</literallayout></blockquote>
</sect3>
<sect3 label="16.4.2.8" id="Matrix-Statistical-Distribution-Functions">
<title>Matrix Statistical Distribution Functions</title>

<para>The matrix language can calculate several functions of standard
statistical distributions using the same syntax and semantics as in
PSPP transformation expressions.  See <link linkend="Statistical-Distribution-Functions">Statistical Distribution
Functions</link>, for details.
</para>
<para>The matrix language extends the PDF, CDF, SIG, IDF, NPDF, and NCDF
functions by allowing the first parameters to each of these functions
to be a vector or matrix with any dimensions.  In addition,
<literal>CDF.BVNOR</literal> and <literal>PDF.BVNOR</literal> allow either or both of their
first two parameters to be vectors or matrices; if both are non-scalar
then they must have the same dimensions.  In each case, the result is
a matrix or vector with the same dimensions as the input populated
with elementwise calculations.
</para>
</sect3>
<sect3 label="16.4.2.9" id="Matrix-EOF-Function">
<title>EOF Function</title>

<para>This function works with files being used on the <literal>READ</literal> statement.
</para>
<synopsis><indexterm role="fn"><primary>EOF</primary></indexterm><phrase role="category"><emphasis role="bold">Matrix Function</emphasis>:</phrase> <function>EOF</function> (<emphasis role="arg"><replaceable>file</replaceable></emphasis>)</synopsis>
<blockquote><anchor id="EOF-Matrix-Function"/>
<para>Given a file handle or file name <replaceable>file</replaceable>, returns an integer scalar
1 if the last line in the file has been read or 0 if more lines are
available.  Determining this requires attempting to read another line,
which means that <literal>REREAD</literal> on the next <literal>READ</literal> command
following <literal>EOF</literal> on the same file will be ineffective.
</para></blockquote>
<para>The <literal>EOF</literal> function gives a matrix program the flexibility to read
a file with text data without knowing the length of the file in
advance.  For example, the following program will read all the lines
of data in <filename>data.txt</filename>, each consisting of three numbers, as rows
in matrix <literal>data</literal>:
</para>
<screen>MATRIX.
COMPUTE data={}.
LOOP IF NOT EOF('data.txt').
  READ row/FILE='data.txt'/FIELD=1 TO 1000/SIZE={1,3}.
  COMPUTE data={data; row}.
END LOOP.
PRINT data.
END MATRIX.

</screen>
</sect3>
</sect2>
<sect2 label="16.4.3" id="Matrix-COMPUTE-Command">
<title>The <literal>COMPUTE</literal> Command</title>

<literallayout><literal>COMPUTE</literal> <emphasis>variable</emphasis>[<literal>(</literal><emphasis>index</emphasis>[<literal>,</literal><emphasis>index</emphasis>]<literal>)</literal>]<literal>=</literal><emphasis>expression</emphasis><literal>.</literal>
</literallayout>
<para>The <literal>COMPUTE</literal> command evaluates an expression and assigns the
result to a variable or a submatrix of a variable.  Assigning to a
submatrix uses the same syntax as the index operator (see <link linkend="Matrix-Index-Operator">Matrix
Index Operator</link>).
</para>
</sect2>
<sect2 label="16.4.4" id="Matrix-CALL-command">
<title>The <literal>CALL</literal> Command</title>

<para>A matrix function returns a single result.  The <literal>CALL</literal> command
implements procedures, which take a similar syntactic form to
functions but yield results by modifying their arguments rather than
returning a value.
</para>
<para>Output arguments to a <literal>CALL</literal> procedure must be a single variable
name.
</para>
<para>The following procedures are implemented via <literal>CALL</literal> to allow them
to return multiple results.  For these procedures, the output
arguments need not name existing variables; if they do, then their
previous values are replaced:
</para>
<variablelist><varlistentry><term><literal>CALL EIGEN(<replaceable>M</replaceable>, <replaceable>evec</replaceable>, <replaceable>eval</replaceable>)</literal>
</term><listitem><anchor id="CALL-EIGEN"/>
<para>Computes the eigenvalues and eigenvector of symmetric
<inlineequation><mathphrase><replaceable>n</replaceable>×<replaceable>n</replaceable></mathphrase></inlineequation> matrix <replaceable>M</replaceable>.  Assigns the
eigenvectors of <replaceable>M</replaceable> to the columns of
<inlineequation><mathphrase><replaceable>n</replaceable>×<replaceable>n</replaceable></mathphrase></inlineequation> matrix <replaceable>evec</replaceable> and the eigenvalues in
descending order to <replaceable>n</replaceable>-element column vector <replaceable>eval</replaceable>.
</para>
<para>Use the <literal>EVAL</literal> function (see <link linkend="EVAL">EVAL</link>) to compute just the
eigenvalues of a symmetric matrix.
</para>
<para>For example, the following matrix language commands:
</para><screen>CALL EIGEN({1, 0; 0, 1}, evec, eval).
PRINT evec.
PRINT eval.

CALL EIGEN({3, 2, 4; 2, 0, 2; 4, 2, 3}, evec2, eval2).
PRINT evec2.
PRINT eval2.
</screen>
<para>yield this output:
</para>
<screen>evec
  1  0
  0  1

eval
  1
  1

evec2
  -.6666666667   .0000000000   .7453559925
  -.3333333333  -.8944271910  -.2981423970
  -.6666666667   .4472135955  -.5962847940

eval2
  8.0000000000
 -1.0000000000
 -1.0000000000
</screen>
</listitem></varlistentry><varlistentry><term><literal>CALL SVD(<replaceable>M</replaceable>, <replaceable>U</replaceable>, <replaceable>S</replaceable>, <replaceable>V</replaceable>)</literal>
</term><listitem><anchor id="CALL-SVD"/>
<para>Computes the singular value decomposition of
<inlineequation><mathphrase><replaceable>n</replaceable>×<replaceable>k</replaceable></mathphrase></inlineequation> matrix <replaceable>M</replaceable>, assigning <replaceable>S</replaceable> a
<inlineequation><mathphrase><replaceable>n</replaceable>×<replaceable>k</replaceable></mathphrase></inlineequation> diagonal matrix and to <replaceable>U</replaceable> and
<replaceable>V</replaceable> unitary <inlineequation><mathphrase><replaceable>k</replaceable>×<replaceable>k</replaceable></mathphrase></inlineequation> matrices such that
<inlineequation><mathphrase><replaceable>M</replaceable> = <replaceable>U</replaceable>×<replaceable>S</replaceable>×<replaceable>V</replaceable>^T</mathphrase></inlineequation>.  The main
diagonal of <replaceable>Q</replaceable> contains the singular values of <replaceable>M</replaceable>.
</para>
<para>Use the <literal>SVAL</literal> function (see <link linkend="SVAL">SVAL</link>) to compute just the
singular values of a matrix.
</para>
<para>For example, the following matrix program:
</para>
<screen>CALL SVD({3, 2, 2; 2, 3, -2}, u, s, v).
PRINT (u * s * T(v))/FORMAT F5.1.
</screen>
<para>yields this output:
</para>
<screen>(u * s * T(v))
   3.0   2.0   2.0
   2.0   3.0  -2.0
</screen></listitem></varlistentry></variablelist>
<para>The final procedure is implemented via <literal>CALL</literal> to allow it to
modify a matrix instead of returning a modified version.  For this
procedure, the output argument must name an existing variable.
</para>
<variablelist><varlistentry><term><literal>CALL SETDIAG(<replaceable>M</replaceable>, <replaceable>V</replaceable>)</literal>
</term><listitem><anchor id="CALL-SETDIAG"/>
<para>Replaces the main diagonal of <inlineequation><mathphrase><replaceable>n</replaceable>×<replaceable>p</replaceable></mathphrase></inlineequation> matrix
<replaceable>M</replaceable> by the contents of <replaceable>k</replaceable>-element vector <replaceable>V</replaceable>.  If
<inlineequation><mathphrase><replaceable>k</replaceable> = 1</mathphrase></inlineequation>, so that <replaceable>V</replaceable> is a scalar, replaces all of the
diagonal elements of <replaceable>M</replaceable> by <replaceable>V</replaceable>.  If <inlineequation><mathphrase><replaceable>k</replaceable> &lt;
\min(<replaceable>n</replaceable>,<replaceable>p</replaceable>)</mathphrase></inlineequation>, only the upper <replaceable>k</replaceable> diagonal elements are
replaced; if <inlineequation><mathphrase><replaceable>k</replaceable> &gt; \min(<replaceable>n</replaceable>,<replaceable>p</replaceable>)</mathphrase></inlineequation>, then the
extra elements of <replaceable>V</replaceable> are ignored.
</para>
<para>Use the <literal>MDIAG</literal> function (see <link linkend="MDIAG">MDIAG</link>) to construct a new
matrix with a specified main diagonal.
</para>
<para>For example, this matrix program:
</para>
<screen>COMPUTE x={1, 2, 3; 4, 5, 6; 7, 8, 9}.
CALL SETDIAG(x, 10).
PRINT x.
</screen>
<para>outputs the following:
</para>
<screen>x
  10   2   3
   4  10   6
   7   8  10
</screen></listitem></varlistentry></variablelist>
</sect2>
<sect2 label="16.4.5" id="Matrix-PRINT-Command">
<title>The <literal>PRINT</literal> Command</title>

<literallayout><literal>PRINT</literal> [<emphasis>expression</emphasis>]
      [<literal>/FORMAT</literal><literal>=</literal><emphasis>format</emphasis>]
      [<literal>/TITLE</literal><literal>=</literal><emphasis>title</emphasis>]
      [<literal>/SPACE</literal><literal>=</literal>{<literal>NEWPAGE</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <emphasis>n</emphasis>}]
      [{<literal>/RLABELS</literal><literal>=</literal><emphasis>string</emphasis>&#8230; <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>/RNAMES</literal><literal>=</literal><emphasis>expression</emphasis>}]
      [{<literal>/CLABELS</literal><literal>=</literal><emphasis>string</emphasis>&#8230; <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>/CNAMES</literal><literal>=</literal><emphasis>expression</emphasis>}]<literal>.</literal>
</literallayout>
<para>The <literal>PRINT</literal> command is commonly used to display a matrix.  It
evaluates the restricted <replaceable>expression</replaceable>, if present, and outputs it
either as text or a pivot table, depending on the setting of
<literal>MDISPLAY</literal> (see <link linkend="SET-MDISPLAY">SET MDISPLAY</link>).
</para>
<para>Use the <literal>FORMAT</literal> subcommand to specify a format, such as
<literal>F8.2</literal>, for displaying the matrix elements.  <literal>FORMAT</literal> is
optional for numerical matrices.  When it is omitted, PSPP chooses
how to format entries automatically using <replaceable>m</replaceable>, the magnitude of
the largest-magnitude element in the matrix to be displayed:
</para>
<orderedlist numeration="arabic"><listitem><para>If <inlineequation><mathphrase><replaceable>m</replaceable> &lt; 10^{11}</mathphrase></inlineequation> and the matrix&#8217;s elements are all
integers, PSPP chooses the narrowest <literal>F</literal> format that fits
<replaceable>m</replaceable> plus a sign.  For example, if the matrix is <literal>{1:10}</literal>, then
<inlineequation><mathphrase>m = 10</mathphrase></inlineequation>, which fits in 3 columns with room for a sign, the
format is <literal>F3.0</literal>.
</para>
</listitem><listitem><para>Otherwise, if <inlineequation><mathphrase><replaceable>m</replaceable> &#8805; 10^9</mathphrase></inlineequation> or <inlineequation><mathphrase><replaceable>m</replaceable> &#8804;
10^{-4}</mathphrase></inlineequation>, PSPP scales all of the numbers in the matrix by
<inlineequation><mathphrase>10^x</mathphrase></inlineequation>, where <replaceable>x</replaceable> is the exponent that would be used to
display <replaceable>m</replaceable> in scientific notation.  For example, for
<inlineequation><mathphrase><replaceable>m</replaceable> = 5.123×10^{20}</mathphrase></inlineequation>, the scale factor is
<inlineequation><mathphrase>10^{20}</mathphrase></inlineequation>.  PSPP displays the scaled values in format
<literal>F13.10</literal> and notes the scale factor in the output.
</para>
</listitem><listitem><para>Otherwise, PSPP displays the matrix values, without scaling, in
format <literal>F13.10</literal>.
</para></listitem></orderedlist>
<para>The optional <literal>TITLE</literal> subcommand specifies a title for the output
text or table, as a quoted string.  When it is omitted, the syntax of
the matrix expression is used as the title.
</para>
<para>Use the <literal>SPACE</literal> subcommand to request extra space above the
matrix output.  With a numerical argument, it adds the specified
number of lines of blank space above the matrix.  With <literal>NEWPAGE</literal>
as an argument, it prints the matrix at the top of a new page.  The
<literal>SPACE</literal> subcommand has no effect when a matrix is output as a
pivot table.
</para>
<para>The <literal>RLABELS</literal> and <literal>RNAMES</literal> subcommands, which are mutually
exclusive, can supply a label to accompany each row in the output.
With <literal>RLABELS</literal>, specify the labels as comma-separated strings or
other tokens.  With <literal>RNAMES</literal>, specify a single expression that
evaluates to a vector of strings.  Either way, if there are more
labels than rows, the extra labels are ignored, and if there are more
rows than labels, the extra rows are unlabeled.  For output to a pivot
table with <literal>RLABELS</literal>, the labels can be any length; otherwise,
the labels are truncated to 8 bytes.
</para>
<para>The <literal>CLABELS</literal> and <literal>CNAMES</literal> subcommands work for labeling
columns as <literal>RLABELS</literal> and <literal>RNAMES</literal> do for labeling rows.
</para>
<para>When the <replaceable>expression</replaceable> is omitted, <literal>PRINT</literal> does not output a
matrix.  Instead, it outputs only the text specified on <literal>TITLE</literal>,
if any, preceded by any space specified on the <literal>SPACE</literal>
subcommand, if any.  Any other subcommands are ignored, and the
command acts as if <literal>MDISPLAY</literal> is set to <literal>TEXT</literal> regardless of
its actual setting.
</para>
<para>The following syntax demonstrates two different ways to label the rows
and columns of a matrix with <literal>PRINT</literal>:
</para>
<screen>MATRIX.
COMPUTE m={1, 2, 3; 4, 5, 6; 7, 8, 9}.
PRINT m/RLABELS=a, b, c/CLABELS=x, y, z.

COMPUTE rlabels={&quot;a&quot;, &quot;b&quot;, &quot;c&quot;}.
COMPUTE clabels={&quot;x&quot;, &quot;y&quot;, &quot;z&quot;}.
PRINT m/RNAMES=rlabels/CNAMES=clabels.
END MATRIX.
</screen>
<para>With <literal>MDISPLAY=TEXT</literal> (the default), this program outputs the
following (twice):
</para>
<screen>m
                x        y        z
a               1        2        3
b               4        5        6
c               7        8        9
</screen>
<para>With &#8216;<literal>SET MDISPLAY=TABLES.</literal>&#8217; added above &#8216;<literal>MATRIX.</literal>&#8217;, the
output becomes the following (twice):
</para>
<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
<screen>    m
+-+-+-+-+
| |x|y|z|
+-+-+-+-+
|a|1|2|3|
|b|4|5|6|
|c|7|8|9|
+-+-+-+-+
</screen>
</sect2>
<sect2 label="16.4.6" id="Matrix-DO-IF-Command">
<title>The <literal>DO IF</literal> Command</title>

<literallayout><literal>DO IF</literal> <emphasis>expression</emphasis><literal>.</literal>
  &#8230;<emphasis>matrix commands</emphasis>&#8230;
[<literal>ELSE IF</literal> <emphasis>expression</emphasis><literal>.</literal>
  &#8230;<emphasis>matrix commands</emphasis>&#8230;]&#8230;
[<literal>ELSE</literal>
  &#8230;<emphasis>matrix commands</emphasis>&#8230;]
<literal>END IF</literal><literal>.</literal>
</literallayout>
<para>A <literal>DO IF</literal> command evaluates its expression argument.  If the
<literal>DO IF</literal> expression evaluates to true, then PSPP executes the
associated commands.  Otherwise, PSPP evaluates the expression on
each <literal>ELSE IF</literal> clause (if any) in order, and executes the
commands associated with the first one that yields a true value.
Finally, if the <literal>DO IF</literal> and all the <literal>ELSE IF</literal> expressions
all evaluate to false, PSPP executes the commands following the
<literal>ELSE</literal> clause (if any).
</para>
<para>Each expression on <literal>DO IF</literal> and <literal>ELSE IF</literal> must evaluate to a
scalar.  Positive scalars are considered to be true, and scalars that
are zero or negative are considered to be false.
</para>
<para>The following matrix language fragment sets &#8216;<literal>b</literal>&#8217; to the term
following &#8216;<literal>a</literal>&#8217; in the
<ulink url="https://en.wikipedia.org/wiki/Juggler_sequence">Juggler
sequence</ulink>:
</para>
<screen>DO IF MOD(a, 2) = 0.
  COMPUTE b = TRUNC(a &amp;** (1/2)).
ELSE.
  COMPUTE b = TRUNC(a &amp;** (3/2)).
END IF.
</screen>
</sect2>
<sect2 label="16.4.7" id="Matrix-LOOP-and-BREAK-Commands">
<title>The <literal>LOOP</literal> and <literal>BREAK</literal> Commands</title>

<literallayout><literal>LOOP</literal> [<emphasis>var</emphasis><literal>=</literal><emphasis>first</emphasis> <literal>TO</literal> <emphasis>last</emphasis> [<literal>BY</literal> <emphasis>step</emphasis>]] [<literal>IF</literal> <emphasis>expression</emphasis>]<literal>.</literal>
  &#8230;<emphasis>matrix commands</emphasis>&#8230;
<literal>END LOOP</literal> [<literal>IF</literal> <emphasis>expression</emphasis>]<literal>.</literal>

<literal>BREAK</literal><literal>.</literal>
</literallayout>
<para>The <literal>LOOP</literal> command executes a nested group of matrix commands,
called the loop&#8217;s <firstterm>body</firstterm>, repeatedly.  It has three optional
clauses that control how many times the loop body executes.
Regardless of these clauses, the global <literal>MXLOOPS</literal> setting, which
defaults to 40, also limits the number of iterations of a loop.  To
iterate more times, raise the maximum with <literal>SET MXLOOPS</literal> outside
of the <literal>MATRIX</literal> command (see <link linkend="SET-MXLOOPS">SET MXLOOPS</link>).
</para>
<para>The optional index clause causes <replaceable>var</replaceable> to be assigned successive
values on each trip through the loop: first <replaceable>first</replaceable>, then
<inlineequation><mathphrase><replaceable>first</replaceable> + <replaceable>step</replaceable></mathphrase></inlineequation>, then <inlineequation><mathphrase><replaceable>first</replaceable> + 2 ×
<replaceable>step</replaceable></mathphrase></inlineequation>, and so on.  The loop ends when <inlineequation><mathphrase><replaceable>var</replaceable> &gt;
<replaceable>last</replaceable></mathphrase></inlineequation>, for positive <replaceable>step</replaceable>, or <inlineequation><mathphrase><replaceable>var</replaceable> &lt;
<replaceable>last</replaceable></mathphrase></inlineequation>, for negative <replaceable>step</replaceable>.  If <replaceable>step</replaceable> is not specified,
it defaults to 1.  All the index clause expressions must evaluate to
scalars, and non-integers are rounded toward zero.  If <replaceable>step</replaceable>
evaluates as zero (or rounds to zero), then the loop body never
executes.
</para>
<para>The optional <literal>IF</literal> on <literal>LOOP</literal> is evaluated before each
iteration through the loop body.  If its expression, which must
evaluate to a scalar, is zero or negative, then the loop terminates
without executing the loop body.
</para>
<para>The optional <literal>IF</literal> on <literal>END LOOP</literal> is evaluated after each
iteration through the loop body.  If its expression, which must
evaluate to a scalar, is zero or negative, then the loop terminates.
</para>
<para>The following computes and prints <inlineequation><mathphrase>l(n)</mathphrase></inlineequation>, whose value is the
number of steps in the
<ulink url="https://en.wikipedia.org/wiki/Juggler_sequence">Juggler sequence</ulink>
for <inlineequation><mathphrase>n</mathphrase></inlineequation>, for <inlineequation><mathphrase>n</mathphrase></inlineequation> from 2 to 10 inclusive:
</para>
<screen>COMPUTE l = {}.
LOOP n = 2 TO 10.
  COMPUTE a = n.
  LOOP i = 1 TO 100.
    DO IF MOD(a, 2) = 0.
      COMPUTE a = TRUNC(a &amp;** (1/2)).
    ELSE.
      COMPUTE a = TRUNC(a &amp;** (3/2)).
    END IF.
  END LOOP IF a = 1.
  COMPUTE l = {l; i}.
END LOOP.
PRINT l.
</screen>

<sect3 label="16.4.7.1" id="Matrix-BREAK-Command">
<title>The <literal>BREAK</literal> Command</title>

<para>The <literal>BREAK</literal> command may be used inside a loop body, ordinarily
within a <literal>DO IF</literal> command.  If it is executed, then the loop
terminates immediately, jumping to the command just following
<literal>END LOOP</literal>.  When multiple <literal>LOOP</literal> commands nest,
<literal>BREAK</literal> terminates the innermost loop.
</para>
<para>The following example is a revision of the one above that shows how
<literal>BREAK</literal> could substitute for the index and <literal>IF</literal> clauses on
<literal>LOOP</literal> and <literal>END LOOP</literal>:
</para>
<screen>COMPUTE l = {}.
LOOP n = 2 TO 10.
  COMPUTE a = n.
  COMPUTE i = 1.
  LOOP.
    DO IF MOD(a, 2) = 0.
      COMPUTE a = TRUNC(a &amp;** (1/2)).
    ELSE.
      COMPUTE a = TRUNC(a &amp;** (3/2)).
    END IF.
    DO IF a = 1.
      BREAK.
    END IF.
    COMPUTE i = i + 1.
  END LOOP.
  COMPUTE l = {l; i}.
END LOOP.
PRINT l.
</screen>
</sect3>
</sect2>
<sect2 label="16.4.8" id="Matrix-READ-and-WRITE-Commands">
<title>The <literal>READ</literal> and <literal>WRITE</literal> Commands</title>

<para>The <literal>READ</literal> and <literal>WRITE</literal> commands perform matrix input and
output with text files.  They share the following syntax for
specifying how data is divided among input lines:
</para>
<literallayout><literal>/FIELD</literal><literal>=</literal><emphasis>first</emphasis> <literal>TO</literal> <emphasis>last</emphasis> [<literal>BY</literal> <emphasis>width</emphasis>]
[<literal>/FORMAT</literal><literal>=</literal><emphasis>format</emphasis>]
</literallayout>
<para>Both commands require the <literal>FIELD</literal> subcommand.  It specifies the
range of columns, from <replaceable>first</replaceable> to <replaceable>last</replaceable>, inclusive, that the
data occupies on each line of the file.  The leftmost column is column
1.  The columns must be literal numbers, not expressions.  To use
entire lines, even if they might be very long, specify a column range
such as <literal>1 TO 100000</literal>.
</para>
<para>The <literal>FORMAT</literal> subcommand is optional for numerical matrices.  For
string matrix input and output, specify an <literal>A</literal> format.  In
addition to <literal>FORMAT</literal>, the optional <literal>BY</literal> specification on
<literal>FIELD</literal> determine the meaning of each text line:
</para>
<itemizedlist><listitem><para>With neither <literal>BY</literal> nor <literal>FORMAT</literal>, the numbers in the text file
are in <literal>F</literal> format separated by spaces or commas.  For
<literal>WRITE</literal>, PSPP uses as many digits of precision as needed to
accurately represent the numbers in the matrix.
</para>
</listitem><listitem><para><literal>BY <emphasis>width</emphasis></literal> divides the input area into fixed-width fields
with the given <emphasis>width</emphasis>.  The input area must be a multiple of
<emphasis>width</emphasis> columns wide.  Numbers are read or written as
<literal>F<emphasis>width</emphasis>.0</literal> format.
</para>
</listitem><listitem><para><literal>FORMAT=&quot;<emphasis>count</emphasis>F&quot;</literal> divides the input area into integer <emphasis>count</emphasis>
equal-width fields per line.  The input area must be a multiple of
<emphasis>count</emphasis> columns wide.  Another format type may be substituted for
<literal>F</literal>.
</para>
</listitem><listitem><para><literal>FORMAT=F<emphasis>w</emphasis></literal>[<literal>.<emphasis>d</emphasis></literal>] divides the input area into fixed-width
fields with width <emphasis>w</emphasis>.  The input area must be a multiple of <emphasis>w</emphasis>
columns wide.  Another format type may be substituted for <literal>F</literal>.
The <literal>READ</literal> command disregards <emphasis>d</emphasis>.
</para>
</listitem><listitem><para><literal>FORMAT=F</literal> specifies format <literal>F</literal> without indicating a field
width.  Another format type may be substituted for <literal>F</literal>.  The
<literal>WRITE</literal> command accepts this form, but it has no effect unless
<literal>BY</literal> is also used to specify a field width.
</para></listitem></itemizedlist>
<para>If <literal>BY</literal> and <literal>FORMAT</literal> both specify or imply a field width,
then they must indicate the same field width.
</para>
<sect3 label="16.4.8.1" id="Matrix-READ-Command">
<title>The <literal>READ</literal> Command</title>

<literallayout><literal>READ</literal> <emphasis>variable</emphasis>[<literal>(</literal><emphasis>index</emphasis>[<literal>,</literal><emphasis>index</emphasis>]<literal>)</literal>]
     [<literal>/FILE</literal><literal>=</literal><emphasis>file</emphasis>]
     <literal>/FIELD</literal><literal>=</literal><emphasis>first</emphasis> <literal>TO</literal> <emphasis>last</emphasis> [<literal>BY</literal> <emphasis>width</emphasis>]
     [<literal>/FORMAT</literal><literal>=</literal><emphasis>format</emphasis>]
     [<literal>/SIZE</literal><literal>=</literal><emphasis>expression</emphasis>]
     [<literal>/MODE</literal><literal>=</literal>{<literal>RECTANGULAR</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>SYMMETRIC</literal>}]
     [<literal>/REREAD</literal>]<literal>.</literal>
</literallayout>
<para>The <literal>READ</literal> command reads from a text file into a matrix variable.
Specify the target variable just after the command name, either just a
variable name to create or replace an entire variable, or a variable
name followed by an indexing expression to replace a submatrix of an
existing variable.
</para>
<para>The <literal>FILE</literal> subcommand is required in the first <literal>READ</literal>
command that appears within <literal>MATRIX</literal>.  It specifies the text file
to be read, either as a file name in quotes or a file handle
previously declared on <literal>FILE HANDLE</literal> (see <link linkend="FILE-HANDLE">FILE HANDLE</link>).
Later <literal>READ</literal> commands (in syntax order) use the previous
referenced file if <literal>FILE</literal> is omitted.
</para>
<para>The <literal>FIELD</literal> and <literal>FORMAT</literal> subcommands specify how input lines
are interpreted.  <literal>FIELD</literal> is required, but <literal>FORMAT</literal> is
optional.  See <link linkend="Matrix-READ-and-WRITE-Commands">Matrix READ and WRITE Commands</link>, for details.
</para>
<para>The <literal>SIZE</literal> subcommand is required for reading into an entire
variable.  Its restricted expression argument should evaluate to a
2-element vector <literal>{<replaceable>n</replaceable>,&amp;#160;<!-- /@w --><replaceable>m</replaceable>}</literal> or
<literal>{<replaceable>n</replaceable>;&amp;#160;<!-- /@w --><replaceable>m</replaceable>}</literal>, which indicates a
<inlineequation><mathphrase><replaceable>n</replaceable>×<replaceable>m</replaceable></mathphrase></inlineequation> matrix destination.  A scalar <replaceable>n</replaceable> is
also allowed and indicates a <inlineequation><mathphrase><replaceable>n</replaceable>×1</mathphrase></inlineequation> column vector
destination.  When the destination is a submatrix, <literal>SIZE</literal> is
optional, and if it is present then it must match the size of the
submatrix.
</para>
<para>By default, or with <literal>MODE=RECTANGULAR</literal>, the command reads an
entry for every row and column.  With <literal>MODE=SYMMETRIC</literal>, the
command reads only the entries on and below the matrix&#8217;s main
diagonal, and copies the entries above the main diagonal from the
corresponding symmetric entries below it.  Only square matrices
may use <literal>MODE=SYMMETRIC</literal>.
</para>
<para>Ordinarily, each <literal>READ</literal> command starts from a new line in the
text file.  Specify the <literal>REREAD</literal> subcommand to instead start from
the last line read by the previous <literal>READ</literal> command.  This has no
effect for the first <literal>READ</literal> command to read from a particular
file.  It is also ineffective just after a command that uses the
<literal>EOF</literal> matrix function (see <link linkend="EOF-Matrix-Function">EOF Matrix Function</link>) on a
particular file, because <literal>EOF</literal> has to try to read the next line
from the file to determine whether the file contains more input.
</para>
<bridgehead renderas="sect3">Example 1: Basic Use</bridgehead>

<para>The following matrix program reads the same matrix <literal>{1, 2, 4; 2,
3, 5; 4, 5, 6}</literal> into matrix variables <literal>v</literal>, <literal>w</literal>, and
<literal>x</literal>:
</para>
<screen>READ v /FILE='input.txt' /FIELD=1 TO 100 /SIZE={3, 3}.
READ w /FIELD=1 TO 100 /SIZE={3; 3} /MODE=SYMMETRIC.
READ x /FIELD=1 TO 100 BY 1/SIZE={3, 3} /MODE=SYMMETRIC.
</screen>
<para>given that <filename>input.txt</filename> contains the following:
</para>
<screen>1, 2, 4
2, 3, 5
4, 5, 6
1
2 3
4 5 6
1
23
456
</screen>
<para>The <literal>READ</literal> command will read as many lines of input as needed for
a particular row, so it&#8217;s also acceptable to break any of the lines
above into multiple lines.  For example, the first line <literal>1, 2, 4</literal>
could be written with a line break following either or both commas.
</para>
<bridgehead renderas="sect3">Example 2: Reading into a Submatrix</bridgehead>

<para>The following reads a <inlineequation><mathphrase>5×5</mathphrase></inlineequation> matrix from <filename>input2.txt</filename>,
reversing the order of the rows:
</para>
<screen>COMPUTE m = MAKE(5, 5, 0).
LOOP r = 5 TO 1 BY -1.
  READ m(r, :) /FILE='input2.txt' /FIELD=1 TO 100.
END LOOP.
</screen>
<bridgehead renderas="sect3">Example 3: Using <literal>REREAD</literal></bridgehead>

<para>Suppose each of the 5 lines in a file <filename>input3.txt</filename> starts with an
integer <replaceable>count</replaceable> followed by <replaceable>count</replaceable> numbers, e.g.:
</para>
<screen>1 5
3 1 2 3
5 6 -1 2 5 1
2 8 9
3 1 3 2
</screen>
<para>Then, the following reads this file into a matrix <literal>m</literal>:
</para>
<screen>COMPUTE m = MAKE(5, 5, 0).
LOOP i = 1 TO 5.
  READ count /FILE='input3.txt' /FIELD=1 TO 1 /SIZE=1.
  READ m(i, 1:count) /FIELD=3 TO 100 /REREAD.
END LOOP.
</screen>
</sect3>
<sect3 label="16.4.8.2" id="Matrix-WRITE-Command">
<title>The <literal>WRITE</literal> Command</title>

<literallayout><literal>WRITE</literal> <emphasis>expression</emphasis>
      [<literal>/OUTFILE</literal><literal>=</literal><emphasis>file</emphasis>]
      <literal>/FIELD</literal><literal>=</literal><emphasis>first</emphasis> <literal>TO</literal> <emphasis>last</emphasis> [<literal>BY</literal> <emphasis>width</emphasis>]
      [<literal>/FORMAT</literal><literal>=</literal><emphasis>format</emphasis>]
      [<literal>/MODE</literal><literal>=</literal>{<literal>RECTANGULAR</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>TRIANGULAR</literal>}]
      [<literal>/HOLD</literal>]<literal>.</literal>
</literallayout>
<para>The <literal>WRITE</literal> command evaluates <emphasis>expression</emphasis> and writes its value
to a text file in a specified format.  Write the expression to
evaluate just after the command name.
</para>
<para>The <literal>OUTFILE</literal> subcommand is required in the first <literal>WRITE</literal>
command that appears within <literal>MATRIX</literal>.  It specifies the text file
to be written, either as a file name in quotes or a file handle
previously declared on <literal>FILE HANDLE</literal> (see <link linkend="FILE-HANDLE">FILE HANDLE</link>).
Later <literal>WRITE</literal> commands (in syntax order) use the previous
referenced file if <literal>FILE</literal> is omitted.
</para>
<para>The <literal>FIELD</literal> and <literal>FORMAT</literal> subcommands specify how output
lines are formed.  <literal>FIELD</literal> is required, but <literal>FORMAT</literal> is
optional.  See <link linkend="Matrix-READ-and-WRITE-Commands">Matrix READ and WRITE Commands</link>, for details.
</para>
<para>By default, or with <literal>MODE=RECTANGULAR</literal>, the command writes an
entry for every row and column.  With <literal>MODE=TRIANGULAR</literal>, the
command writes only the entries on and below the matrix&#8217;s main
diagonal.  Entries above the diagonal are not written.  Only square
matrices may be written with <literal>MODE=TRIANGULAR</literal>.
</para>
<para>Ordinarily, each <literal>WRITE</literal> command writes complete lines to the
output file.  With <literal>HOLD</literal>, the final line written by <literal>WRITE</literal>
will be held back for the next <literal>WRITE</literal> command to augment.  This
can be useful to write more than one matrix on a single output line.
</para>
<bridgehead renderas="sect3">Example 1: Basic Usage</bridgehead>

<para>This matrix program:
</para>
<screen>WRITE {1, 2; 3, 4} /OUTFILE='matrix.txt' /FIELD=1 TO 80.
</screen>
<para>writes the following to <filename>matrix.txt</filename>:
</para>
<screen> 1 2
 3 4
</screen>
<bridgehead renderas="sect3">Example 2: Triangular Matrix</bridgehead>

<para>This matrix program:
</para>
<screen>WRITE MAGIC(5) /OUTFILE='matrix.txt' /FIELD=1 TO 80 BY 5 /MODE=TRIANGULAR.
</screen>
<para>writes the following to <filename>matrix.txt</filename>:
</para>
<screen>    17
    23    5
     4    6   13
    10   12   19   21
    11   18   25    2    9
</screen>
</sect3>
</sect2>
<sect2 label="16.4.9" id="Matrix-GET-Command">
<title>The <literal>GET</literal> Command</title>

<literallayout><literal>GET</literal> <emphasis>variable</emphasis>[<literal>(</literal><emphasis>index</emphasis>[<literal>,</literal><emphasis>index</emphasis>]<literal>)</literal>]
    [<literal>/FILE</literal><literal>=</literal>{<emphasis>file</emphasis> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>*</literal>}]
    [<literal>/VARIABLES</literal><literal>=</literal><emphasis>variable</emphasis>&#8230;]
    [<literal>/NAMES</literal><literal>=</literal><emphasis>variable</emphasis>]
    [<literal>/MISSING</literal><literal>=</literal>{<literal>ACCEPT</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>OMIT</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <emphasis>number</emphasis>}]
    [<literal>/SYSMIS</literal><literal>=</literal>{<literal>OMIT</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <emphasis>number</emphasis>}]<literal>.</literal>
</literallayout>
<para>The <literal>READ</literal> command reads numeric data from an SPSS system file,
SPSS/PC+ system file, or SPSS portable file into a matrix variable or
submatrix:
</para>
<itemizedlist><listitem><para>To read data into a variable, specify just its name following
<literal>GET</literal>.  The variable need not already exist; if it does, it is
replaced.  The variable will have as many columns as there are
variables specified on the <literal>VARIABLES</literal> subcommand and as many
rows as there are cases in the input file.
</para>
</listitem><listitem><para>To read data into a submatrix, specify the name of an existing
variable, followed by an indexing expression, just after <literal>GET</literal>.
The submatrix must have as many columns as variables specified on
<literal>VARIABLES</literal> and as many rows as cases in the input file.
</para></listitem></itemizedlist>
<para>Specify the name or handle of the file to be read on <literal>FILE</literal>.  Use
&#8216;<literal>*</literal>&#8217;, or simply omit the <literal>FILE</literal> subcommand, to read from the
active file.  Reading from the active file is only permitted if it was
already defined outside <literal>MATRIX</literal>.
</para>
<para>List the variables to be read as columns in the matrix on the
<literal>VARIABLES</literal> subcommand.  The list can use <literal>TO</literal> for
collections of variables or <literal>ALL</literal> for all variables.  If
<literal>VARIABLES</literal> is omitted, all variables are read.  Only numeric
variables may be read.
</para>
<para>If a variable is named on <literal>NAMES</literal>, then the names of the
variables read as data columns are stored in a string vector within
the given name, replacing any existing matrix variable with that name.
Variable names are truncated to 8 bytes.
</para>
<para>The <literal>MISSING</literal> and <literal>SYSMIS</literal> subcommands control the treatment
of missing values in the input file.  By default, any user- or
system-missing data in the variables being read from the input causes
an error that prevents <literal>GET</literal> from executing.  To accept missing
values, specify one of the following settings on <literal>MISSING</literal>:
</para>
<variablelist><varlistentry><term><literal>ACCEPT</literal>
</term><listitem><para>Accept user-missing values with no change.
</para>
<para>By default, system-missing values still yield an error.  Use the
<literal>SYSMIS</literal> subcommand to change this treatment:
</para>
<variablelist><varlistentry><term><literal>OMIT</literal>
</term><listitem><para>Skip any case that contains a system-missing value.
</para>
</listitem></varlistentry><varlistentry><term><emphasis>number</emphasis>
</term><listitem><para>Recode the system-missing value to <emphasis>number</emphasis>.
</para></listitem></varlistentry></variablelist>
</listitem></varlistentry><varlistentry><term><literal>OMIT</literal>
</term><listitem><para>Skip any case that contains any user- or system-missing value.
</para>
</listitem></varlistentry><varlistentry><term><emphasis>number</emphasis>
</term><listitem><para>Recode all user- and system-missing values to <emphasis>number</emphasis>.
</para></listitem></varlistentry></variablelist>
<para>The <literal>SYSMIS</literal> subcommand has an effect only with
<literal>MISSING=ACCEPT</literal>.
</para>
</sect2>
<sect2 label="16.4.10" id="Matrix-SAVE-Command">
<title>The <literal>SAVE</literal> Command</title>

<literallayout><literal>SAVE</literal> <emphasis>expression</emphasis>
     [<literal>/OUTFILE</literal><literal>=</literal>{<emphasis>file</emphasis> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>*</literal>}]
     [<literal>/VARIABLES</literal><literal>=</literal><emphasis>variable</emphasis>&#8230;]
     [<literal>/NAMES</literal><literal>=</literal><emphasis>expression</emphasis>]
     [<literal>/STRINGS</literal><literal>=</literal><emphasis>variable</emphasis>&#8230;]<literal>.</literal>
</literallayout>
<para>The <literal>SAVE</literal> matrix command evaluates <emphasis>expression</emphasis> and writes the
resulting matrix to an SPSS system file.  In the system file, each
matrix row becomes a case and each column becomes a variable.
</para>
<para>Specify the name or handle of the SPSS system file on the
<literal>OUTFILE</literal> subcommand, or &#8216;<literal>*</literal>&#8217; to write the output as the new
active file.  The <literal>OUTFILE</literal> subcommand is required on the first
<literal>SAVE</literal> command, in syntax order, within <literal>MATRIX</literal>.  For
<literal>SAVE</literal> commands after the first, the default output file is the
same as the previous.
</para>
<para>When multiple <literal>SAVE</literal> commands write to one destination within a
single <literal>MATRIX</literal>, the later commands append to the same output
file.  All the matrices written to the file must have the same number
of columns.  The <literal>VARIABLES</literal>, <literal>NAMES</literal>, and <literal>STRINGS</literal>
subcommands are honored only for the first <literal>SAVE</literal> command that
writes to a given file.
</para>
<para>By default, <literal>SAVE</literal> names the variables in the output file
<literal>COL1</literal> through <literal>COL<emphasis>n</emphasis></literal>.  Use <literal>VARIABLES</literal> or
<literal>NAMES</literal> to give the variables meaningful names.  The
<literal>VARIABLES</literal> subcommand accepts a comma-separated list of variable
names.  Its alternative, <literal>NAMES</literal>, instead accepts an expression
that must evaluate to a row or column string vector of names.  The
number of names need not exactly match the number of columns in the
matrix to be written: extra names are ignored; extra columns use
default names.
</para>
<para>By default, <literal>SAVE</literal> assumes that the matrix to be written is all
numeric.  To write string columns, specify a comma-separated list of
the string columns&#8217; variable names on <literal>STRINGS</literal>.
</para>
</sect2>
<sect2 label="16.4.11" id="Matrix-MGET-Command">
<title>The <literal>MGET</literal> Command</title>

<literallayout><literal>MGET</literal> [<literal>/FILE</literal><literal>=</literal><emphasis>file</emphasis>]
     [<literal>/TYPE</literal><literal>=</literal>{<literal>COV</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>CORR</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>MEAN</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>STDDEV</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>N</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>COUNT</literal>}]<literal>.</literal>
</literallayout>
<para>The <literal>MGET</literal> command reads the data from a matrix file
(see <link linkend="Matrix-Files">Matrix Files</link>) into matrix variables.
</para>
<para>All of <literal>MGET</literal>&#8217;s subcommands are optional.  Specify the name or
handle of the matrix file to be read on the <literal>FILE</literal> subcommand; if
it is omitted, then the command reads the active file.
</para>
<para>By default, <literal>MGET</literal> reads all of the data from the matrix file.
Specify a space-delimited list of matrix types on <literal>TYPE</literal> to limit
the kinds of data to the one specified:
</para>
<variablelist><varlistentry><term><literal>COV</literal>
</term><listitem><para>Covariance matrix.
</para>
</listitem></varlistentry><varlistentry><term><literal>CORR</literal>
</term><listitem><para>Correlation coefficient matrix.
</para>
</listitem></varlistentry><varlistentry><term><literal>MEAN</literal>
</term><listitem><para>Vector of means.
</para>
</listitem></varlistentry><varlistentry><term><literal>STDDEV</literal>
</term><listitem><para>Vector of standard deviations.
</para>
</listitem></varlistentry><varlistentry><term><literal>N</literal>
</term><listitem><para>Vector of case counts.
</para>
</listitem></varlistentry><varlistentry><term><literal>COUNT</literal>
</term><listitem><para>Vector of counts.
</para></listitem></varlistentry></variablelist>
<para><literal>MGET</literal> reads the entire matrix file and automatically names,
creates, and populates matrix variables using its contents.  It
constructs the name of each variable by concatenating the following:
</para>
<itemizedlist><listitem><para>A 2-character prefix that identifies the type of the matrix:
</para>
<variablelist><varlistentry><term><literal>CV</literal>
</term><listitem><para>Covariance matrix.
</para>
</listitem></varlistentry><varlistentry><term><literal>CR</literal>
</term><listitem><para>Correlation coefficient matrix.
</para>
</listitem></varlistentry><varlistentry><term><literal>MN</literal>
</term><listitem><para>Vector of means.
</para>
</listitem></varlistentry><varlistentry><term><literal>SD</literal>
</term><listitem><para>Vector of standard deviations.
</para>
</listitem></varlistentry><varlistentry><term><literal>NC</literal>
</term><listitem><para>Vector of case counts.
</para>
</listitem></varlistentry><varlistentry><term><literal>CN</literal>
</term><listitem><para>Vector of counts.
</para></listitem></varlistentry></variablelist>
</listitem><listitem><para>If the matrix file has factor variables, <literal>F<emphasis>n</emphasis></literal>, where <emphasis>n</emphasis> is
a number identifying a group of factors: <literal>F1</literal> for the first
group, <literal>F2</literal> for the second, and so on.  This part is omitted for
pooled data (where the factors all have the system-missing value).
</para>
</listitem><listitem><para>If the matrix file has split file variables, <literal>S<emphasis>n</emphasis></literal>, where
<emphasis>n</emphasis> is a number identifying a split group: <literal>S1</literal> for the first
group, <literal>S2</literal> for the second, and so on.
</para></listitem></itemizedlist>
<para>If <literal>MGET</literal> chooses the name of an existing variable, it issues a
warning and does not change the variable.
</para>
</sect2>
<sect2 label="16.4.12" id="Matrix-MSAVE-Command">
<title>The <literal>MSAVE</literal> Command</title>

<literallayout><literal>MSAVE</literal> <emphasis>expression</emphasis>
      <literal>/TYPE</literal><literal>=</literal>{<literal>COV</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>CORR</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>MEAN</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>STDDEV</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>N</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>COUNT</literal>}
      [<literal>/FACTOR</literal><literal>=</literal><emphasis>expression</emphasis>]
      [<literal>/SPLIT</literal><literal>=</literal><emphasis>expression</emphasis>]
      [<literal>/OUTFILE</literal><literal>=</literal><emphasis>file</emphasis>]
      [<literal>/VARIABLES</literal><literal>=</literal><emphasis>variable</emphasis>&#8230;]
      [<literal>/SNAMES</literal><literal>=</literal><emphasis>variable</emphasis>&#8230;]
      [<literal>/FNAMES</literal><literal>=</literal><emphasis>variable</emphasis>&#8230;]<literal>.</literal>
</literallayout>
<para>The <literal>MSAVE</literal> command evaluates the <emphasis>expression</emphasis> specified just
after the command name, and writes the resulting matrix to a matrix
file (see <link linkend="Matrix-Files">Matrix Files</link>).
</para>
<para>The <literal>TYPE</literal> subcommand is required.  It specifies the
<literal>ROWTYPE_</literal> to write along with this matrix.
</para>
<para>The <literal>FACTOR</literal> and <literal>SPLIT</literal> subcommands are required on the
first <literal>MSAVE</literal> if and only if the matrix file has factor or split
variables, respectively.  After that, their values are carried along
from one <literal>MSAVE</literal> command to the next in syntax order as defaults.
Each one takes an expression that must evaluate to a vector with the
same number of entries as the matrix has factor or split variables,
respectively.  Each <literal>MSAVE</literal> only writes data for a single
combination of factor and split variables, so many <literal>MSAVE</literal>
commands (or one inside a loop) may be needed to write a complete set.
</para>
<para>The remaining <literal>MSAVE</literal> subcommands define the format of the matrix
file.  All of the <literal>MSAVE</literal> commands within a given matrix program
write to the same matrix file, so these subcommands are only
meaningful on the first <literal>MSAVE</literal> command within a matrix program.
(If they are given again on later <literal>MSAVE</literal> commands, then they
must have the same values as on the first.)
</para>
<para>The <literal>OUTFILE</literal> subcommand specifies the name or handle of the
matrix file to be written.  Output must go to an external file, not a
data set or the active file.
</para>
<para>The <literal>VARIABLES</literal> subcommand specifies a comma-separated list of
the names of the continuous variables to be written to the matrix
file.  The <literal>TO</literal> keyword can be used to define variables named
with consecutive integer suffixes.  These names become column names
and names that appear in <literal>VARNAME_</literal> in the matrix file.
<literal>ROWTYPE_</literal> and <literal>VARNAME_</literal> are not allowed on
<literal>VARIABLES</literal>.  If <literal>VARIABLES</literal> is omitted, then PSPP uses
the names <literal>COL1</literal>, <literal>COL2</literal>, and so on.
</para>
<para>The <literal>FNAMES</literal> subcommand may be used to supply a comma-separated
list of factor variable names.  The default names are <literal>FAC1</literal>,
<literal>FAC2</literal>, and so on.
</para>
<para>The <literal>SNAMES</literal> subcommand can supply a comma-separated list of
split variable names.  The default names are <literal>SPL1</literal>, <literal>SPL2</literal>,
and so on.
</para>
</sect2>
<sect2 label="16.4.13" id="Matrix-DISPLAY-Command">
<title>The <literal>DISPLAY</literal> Command</title>

<literallayout><literal>DISPLAY</literal> [{<literal>DICTIONARY</literal> <inlineequation><mathphrase>|</mathphrase></inlineequation> <literal>STATUS</literal>}]<literal>.</literal>
</literallayout>
<para>The <literal>DISPLAY</literal> command makes PSPP display a table with the name
and dimensions of each matrix variable.  The <literal>DICTIONARY</literal> and
<literal>STATUS</literal> keywords are accepted but have no effect.
</para>
</sect2>
<sect2 label="16.4.14" id="Matrix-RELEASE-Command">
<title>The <literal>RELEASE</literal> Command</title>

<literallayout><literal>RELEASE</literal> <emphasis>variable</emphasis>&#8230;<literal>.</literal>
</literallayout>
<para>The <literal>RELEASE</literal> command accepts a comma-separated list of matrix
variable names.  It deletes each variable and releases the memory
associated with it.
</para>
<para>The <literal>END MATRIX</literal> command releases all matrix variables.
<!-- PSPP - a program for statistical analysis. -->
<!-- Copyright (C) 2017, 2020, 2023 Free Software Foundation, Inc. -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.3 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<!-- A copy of the license is included in the section entitled "GNU -->
<!-- Free Documentation License". -->
<!-- -->
</para></sect2>
</sect1>
</chapter>
<chapter label="17" id="Utilities">
<title>Utilities</title>

<para>Commands that don&#8217;t fit any other category are placed here.
</para>
<para>Most of these commands are not affected by commands like <literal>IF</literal> and
<literal>LOOP</literal>:
they take effect only once, unconditionally, at the time that they are
encountered in the input.
</para>

<sect1 label="17.1" id="ADD-DOCUMENT">
<title>ADD DOCUMENT</title>
<indexterm role="vr"><primary>ADD DOCUMENT</primary></indexterm>

<literallayout>ADD DOCUMENT
    &#8217;line one&#8217; &#8217;line two&#8217; &#8230; &#8217;last line&#8217; .
</literallayout>

<para><literal>ADD DOCUMENT</literal> adds one or more lines of descriptive commentary to
the active dataset.  Documents added in this way are saved to system files.
They can be viewed using <literal>SYSFILE INFO</literal> or <literal>DISPLAY
DOCUMENTS</literal>.  They can be removed from the active dataset with <literal>DROP
DOCUMENTS</literal>.
</para>
<para>Each line of documentary text must be enclosed in quotation marks, and
may not be more than 80 bytes long. See <link linkend="DOCUMENT">DOCUMENT</link>.
</para>
</sect1>
<sect1 label="17.2" id="CACHE">
<title>CACHE</title>
<indexterm role="vr"><primary>CACHE</primary></indexterm>

<literallayout>CACHE.
</literallayout>
<para>This command is accepted, for compatibility, but it has no effect.
</para>
</sect1>
<sect1 label="17.3" id="CD">
<title>CD</title>
<indexterm role="vr"><primary>CD</primary></indexterm>
<indexterm role="cp"><primary>directory</primary></indexterm>
<indexterm role="cp"><primary>changing directory</primary></indexterm>

<literallayout>CD &#8217;new directory&#8217; .
</literallayout>
<para><literal>CD</literal> changes the current directory.  The new directory becomes
that specified by the command.
</para>
</sect1>
<sect1 label="17.4" id="COMMENT">
<title>COMMENT</title>
<indexterm role="vr"><primary>COMMENT</primary></indexterm>
<indexterm role="vr"><primary>*</primary></indexterm>

<literallayout>Comment commands:
    COMMENT comment text &#8230; .
    *comment text &#8230; .

Comments within a line of syntax:
    FREQUENCIES /VARIABLES=v0 v1 v2.  /* All our categorical variables.
</literallayout>
<para><literal>COMMENT</literal> is ignored.  It is used to provide information to
the author and other readers of the PSPP syntax file.
</para>
<para><literal>COMMENT</literal> can extend over any number of lines.  It ends at a dot
at the end of a line or a blank line.  The comment may contain any
characters.
</para>
<para>PSPP also supports comments within a line of syntax, introduced with
&#8216;<literal>/*</literal>&#8217;.  These comments end at the first &#8216;<literal>*/</literal>&#8217; or at the end of
the line, whichever comes first.  A line that contains just this kind
of comment is considered blank and ends the current command.
</para>
</sect1>
<sect1 label="17.5" id="DOCUMENT">
<title>DOCUMENT</title>
<indexterm role="vr"><primary>DOCUMENT</primary></indexterm>

<literallayout>DOCUMENT <replaceable>documentary_text</replaceable>.
</literallayout>
<para><literal>DOCUMENT</literal> adds one or more lines of descriptive commentary to the
active dataset.  Documents added in this way are saved to system files.
They can be viewed using <literal>SYSFILE INFO</literal> or <literal>DISPLAY
DOCUMENTS</literal>.  They can be removed from the active dataset with <literal>DROP
DOCUMENTS</literal>.
</para>
<para>Specify the <replaceable>documentary text</replaceable> following the <literal>DOCUMENT</literal> keyword.
It is interpreted literally&#8212;any quotes or other punctuation marks
are included in the file.
You can extend the documentary text over as many lines as necessary,
including blank lines to separate paragraphs.
Lines are truncated at 80 bytes.  Don&#8217;t forget to terminate
the command with a dot at the end of a line. See <link linkend="ADD-DOCUMENT">ADD DOCUMENT</link>.
</para>
</sect1>
<sect1 label="17.6" id="DISPLAY-DOCUMENTS">
<title>DISPLAY DOCUMENTS</title>
<indexterm role="vr"><primary>DISPLAY DOCUMENTS</primary></indexterm>

<literallayout>DISPLAY DOCUMENTS.
</literallayout>
<para><literal>DISPLAY DOCUMENTS</literal> displays the documents in the active dataset.  Each
document is preceded by a line giving the time and date that it was
added.  See <link linkend="DOCUMENT">DOCUMENT</link>.
</para>
</sect1>
<sect1 label="17.7" id="DISPLAY-FILE-LABEL">
<title>DISPLAY FILE LABEL</title>
<indexterm role="vr"><primary>DISPLAY FILE LABEL</primary></indexterm>

<literallayout>DISPLAY FILE LABEL.
</literallayout>
<para><literal>DISPLAY FILE LABEL</literal> displays the file label contained in the
active dataset,
if any.  See <link linkend="FILE-LABEL">FILE LABEL</link>.
</para>
<para>This command is a PSPP extension.
</para>
</sect1>
<sect1 label="17.8" id="DROP-DOCUMENTS">
<title>DROP DOCUMENTS</title>
<indexterm role="vr"><primary>DROP DOCUMENTS</primary></indexterm>

<literallayout>DROP DOCUMENTS.
</literallayout>
<para><literal>DROP DOCUMENTS</literal> removes all documents from the active dataset.
New documents can be added with <literal>DOCUMENT</literal> (see <link linkend="DOCUMENT">DOCUMENT</link>).
</para>
<para><literal>DROP DOCUMENTS</literal> changes only the active dataset.  It does not modify any
system files stored on disk.
</para>
</sect1>
<sect1 label="17.9" id="ECHO">
<title>ECHO</title>
<indexterm role="vr"><primary>ECHO</primary></indexterm>

<literallayout>ECHO &#8217;arbitrary text&#8217; .
</literallayout>
<para>Use <literal>ECHO</literal> to write arbitrary text to the output stream. The text should be enclosed in quotation marks following the normal rules for string tokens (see <link linkend="Tokens">Tokens</link>).
</para>
</sect1>
<sect1 label="17.10" id="ERASE">
<title>ERASE</title>
<indexterm role="vr"><primary>ERASE</primary></indexterm>

<literallayout>ERASE FILE <replaceable>file_name</replaceable>.
</literallayout>
<para><literal>ERASE FILE</literal> deletes a file from the local file system.
<replaceable>file_name</replaceable> must be quoted.
This command cannot be used if the SAFER (see <link linkend="SET">SET</link>) setting is active.
</para>

</sect1>
<sect1 label="17.11" id="EXECUTE">
<title>EXECUTE</title>
<indexterm role="vr"><primary>EXECUTE</primary></indexterm>

<literallayout>EXECUTE.
</literallayout>
<para><literal>EXECUTE</literal> causes the active dataset to be read and all pending
transformations to be executed.
</para>
</sect1>
<sect1 label="17.12" id="FILE-LABEL">
<title>FILE LABEL</title>
<indexterm role="vr"><primary>FILE LABEL</primary></indexterm>

<literallayout>FILE LABEL <replaceable>file_label</replaceable>.
</literallayout>
<para><literal>FILE LABEL</literal> provides a title for the active dataset.  This
title is saved into system files and portable files that are
created during this PSPP run.
</para>
<para><replaceable>file_label</replaceable> should not be quoted.
If quotes are included, they are literally interpreted and become part of the file label.
</para>
</sect1>
<sect1 label="17.13" id="FINISH">
<title>FINISH</title>
<indexterm role="vr"><primary>FINISH</primary></indexterm>

<literallayout>FINISH.
</literallayout>
<para><literal>FINISH</literal> terminates the current PSPP session and returns
control to the operating system.
</para>
</sect1>
<sect1 label="17.14" id="HOST">
<title>HOST</title>
<indexterm role="vr"><primary>HOST</primary></indexterm>

<para>In the syntax below, the square brackets must be included in the
command syntax and do not indicate that that their contents are
optional.
</para>
<literallayout>HOST COMMAND=[&#8217;<replaceable>command</replaceable>&#8217;...]
     TIMELIMIT=<replaceable>secs</replaceable>.
</literallayout>
<para><literal>HOST</literal> executes one or more commands, each provided as a string in
the required <literal>COMMAND</literal> subcommand, in the shell of the
underlying operating system.  PSPP runs each command in a separate
shell process and waits for it to finish before running the next one.
If a command fails (with a nonzero exit status, or because it is
killed by a signal), then PSPP does not run any remaining commands.
</para>
<para>PSPP provides <filename>/dev/null</filename> as the shell&#8217;s standard input.  If a
process needs to read from stdin, redirect from a file or device, or
use a pipe.
</para>
<para>PSPP displays the shell&#8217;s standard output and standard error as PSPP
output.  Redirect to a file or <literal>/dev/null</literal> or another device if
this is not desired.
</para>
<para>The following example runs <literal>rsync</literal> to copy a file from a remote
server to the local file <filename>data.txt</filename>, writing <literal>rsync</literal>&#8217;s own
output to <filename>rsync-log.txt</filename>.  PSPP displays the command&#8217;s error
output, if any.  If <literal>rsync</literal> needs to prompt the user (<emphasis>e.g.</emphasis> to
obtain a password), the command fails.  Only if the <literal>rsync</literal>
succeeds, PSPP then runs the <literal>sha512sum</literal> command.
</para>
<screen>HOST COMMAND=['rsync remote:data.txt data.txt &gt; rsync-log.txt'
              'sha512sum -c data.txt.sha512sum].
</screen>
<para>By default, PSPP waits as long as necessary for the series of commands
to complete.  Use the optional <literal>TIMELIMIT</literal> subcommand to limit
the execution time to the specified number of seconds.
</para>
<para>PSPP built for mingw does not support all the features of
<literal>HOST</literal>.
</para>
<para>PSPP rejects this command if the SAFER (see <link linkend="SET">SET</link>) setting is
active.
</para>
</sect1>
<sect1 label="17.15" id="INCLUDE">
<title>INCLUDE</title>
<indexterm role="vr"><primary>INCLUDE</primary></indexterm>

<literallayout>        INCLUDE [FILE=]&#8217;<replaceable>file_name</replaceable>&#8217; [ENCODING=&#8217;<replaceable>encoding</replaceable>&#8217;].
</literallayout>
<para><literal>INCLUDE</literal> causes the PSPP command processor to read an
additional command file as if it were included bodily in the current
command file.
If errors are encountered in the included file, then command
processing stops and no more commands are processed.
Include files may be nested to any depth, up to the limit of available
memory.
</para>
<para>The <literal>INSERT</literal> command (see <link linkend="INSERT">INSERT</link>) is a more flexible
alternative to <literal>INCLUDE</literal>.  An <literal>INCLUDE</literal> command acts the same as
<literal>INSERT</literal> with <literal>ERROR=STOP CD=NO SYNTAX=BATCH</literal> specified.
</para>
<para>The optional <literal>ENCODING</literal> subcommand has the same meaning as with <literal>INSERT</literal>.
</para>
</sect1>
<sect1 label="17.16" id="INSERT">
<title>INSERT</title>
<indexterm role="vr"><primary>INSERT</primary></indexterm>

<literallayout>     INSERT [FILE=]&#8217;<replaceable>file_name</replaceable>&#8217;
        [CD={NO,YES}]
        [ERROR={CONTINUE,STOP}]
        [SYNTAX={BATCH,INTERACTIVE}]
        [ENCODING={LOCALE, &#8217;<replaceable>charset_name</replaceable>&#8217;}].
</literallayout>
<para><literal>INSERT</literal> is similar to <literal>INCLUDE</literal> (see <link linkend="INCLUDE">INCLUDE</link>)
but somewhat more flexible.
It causes the command processor to read a file as if it were embedded in the
current command file.
</para>
<para>If <literal>CD=YES</literal> is specified, then before including the file, the
current directory becomes the directory of the included
file.
The default setting is &#8216;<literal>CD=NO</literal>&#8217;.
Note that this directory remains current until it is
changed explicitly (with the <literal>CD</literal> command, or a subsequent
<literal>INSERT</literal> command with the &#8216;<literal>CD=YES</literal>&#8217; option).
It does not revert to its original setting even after the included
file is finished processing.
</para>
<para>If <literal>ERROR=STOP</literal> is specified, errors encountered in the
inserted file causes processing to immediately cease.
Otherwise processing continues at the next command.
The default setting is <literal>ERROR=CONTINUE</literal>.
</para>
<para>If <literal>SYNTAX=INTERACTIVE</literal> is specified then the syntax contained in
the included file must conform to interactive syntax
conventions. See <link linkend="Syntax-Variants">Syntax Variants</link>.
The default setting is <literal>SYNTAX=BATCH</literal>.
</para>
<para><literal>ENCODING</literal> optionally specifies the character set used by the included
file.  Its argument, which is not case-sensitive, must be in one of
the following forms:
</para>
<variablelist><varlistentry><term><literal>LOCALE</literal>
</term><listitem><para>The encoding used by the system locale, or as overridden by the
<literal>SET</literal> command (see <link linkend="SET">SET</link>).  On GNU/Linux and other Unix-like systems,
environment variables, <emphasis>e.g.</emphasis> <envar>LANG</envar> or <envar>LC_ALL</envar>, determine the
system locale.
</para>
</listitem></varlistentry><varlistentry><term><replaceable>charset_name</replaceable>
</term><listitem><para>One of the character set names listed by <acronym>IANA</acronym> at
<ulink url="http://www.iana.org/assignments/character-sets">http://www.iana.org/assignments/character-sets</ulink>.  Some examples
are <literal>ASCII</literal> (United States), <literal>ISO-8859-1</literal> (western Europe),
<literal>EUC-JP</literal> (Japan), and <literal>windows-1252</literal> (Windows).  Not all
systems support all character sets.
</para>
</listitem></varlistentry><varlistentry><term><literal>Auto,<replaceable>encoding</replaceable></literal>
</term><listitem><para>Automatically detects whether a syntax file is encoded in an Unicode
encoding such as UTF-8, UTF-16, or UTF-32.  If it is not, then PSPP
generally assumes that the file is encoded in <replaceable>encoding</replaceable> (an <acronym>IANA</acronym>
character set name).  However, if <replaceable>encoding</replaceable> is UTF-8, and the
syntax file is not valid UTF-8, PSPP instead assumes that the file
is encoded in <literal>windows-1252</literal>.
</para>
<para>For best results, <replaceable>encoding</replaceable> should be an <acronym>ASCII</acronym>-compatible
encoding (the most common locale encodings are all <acronym>ASCII</acronym>-compatible),
because encodings that are not <acronym>ASCII</acronym> compatible cannot be
automatically distinguished from UTF-8.
</para>
</listitem></varlistentry><varlistentry><term><literal>Auto</literal>
</term></varlistentry><varlistentry><term><literal>Auto,Locale</literal>
</term><listitem><para>Automatic detection, as above, with the default encoding taken from
the system locale or the setting on <literal>SET LOCALE</literal>.
</para></listitem></varlistentry></variablelist>
<para>When ENCODING is not specified, the default is taken from the
<option>--syntax-encoding</option> command option, if it was specified, and
otherwise it is <literal>Auto</literal>.
</para>
</sect1>
<sect1 label="17.17" id="OUTPUT">
<title>OUTPUT</title>
<indexterm role="vr"><primary>OUTPUT</primary></indexterm>
<indexterm role="cp"><primary>precision, of output</primary></indexterm>
<indexterm role="cp"><primary>decimal places</primary></indexterm>

<literallayout>OUTPUT MODIFY
       /SELECT TABLES
       /TABLECELLS SELECT = [ <replaceable>class</replaceable>... ]
                   FORMAT = <replaceable>fmt_spec</replaceable>.
</literallayout><blockquote><para><emphasis role="bold">Please note:</emphasis> In the above synopsis the characters &#8216;<literal>[</literal>&#8217; and &#8216;<literal>]</literal>&#8217; are literals.
They must appear in the syntax to be interpreted.
</para></blockquote>
<para><literal>OUTPUT</literal> changes the appearance of the tables in which results are
printed. In particular, it can be used to set the format and precision
to which results are displayed.
</para>
<para>After running this command, the default table appearance parameters
will have been modified and  each new output table generated uses
the new parameters.
</para>
<para>Following <literal>/TABLECELLS SELECT =</literal> a list of cell classes must
appear, enclosed in square brackets.  This list determines the classes
of values should be selected for modification. Each class can be:
</para>
<variablelist><varlistentry><term>RESIDUAL
</term><listitem><para>Residual values.  Default: <literal>F40.2</literal>.
</para>
</listitem></varlistentry><varlistentry><term>CORRELATION
</term><listitem><para>Correlations.  Default: <literal>F40.3</literal>.
</para>
</listitem></varlistentry><varlistentry><term>PERCENT
</term><listitem><para>Percentages.  Default: <literal>PCT40.1</literal>.
</para>
</listitem></varlistentry><varlistentry><term>SIGNIFICANCE
</term><listitem><para>Significance of tests (p-values).  Default: <literal>F40.3</literal>.
</para>
</listitem></varlistentry><varlistentry><term>COUNT
</term><listitem><para>Counts or sums of weights.  For a weighted data set, the default is
the weight variable&#8217;s print format.  For an unweighted data set, the
default is F40.0.
</para></listitem></varlistentry></variablelist>
<para>For most other numeric values that appear in tables, <literal>SET FORMAT</literal>
may be used to specify the format (see <link linkend="SET-FORMAT">SET FORMAT</link>).
</para>
<para>The value of <replaceable>fmt_spec</replaceable> must be a valid output format (see <link linkend="Input-and-Output-Formats">Input and Output Formats</link>).
Note that not all possible formats are meaningful for all classes.
</para>
</sect1>
<sect1 label="17.18" id="PERMISSIONS">
<title>PERMISSIONS</title>
<indexterm role="vr"><primary>PERMISSIONS</primary></indexterm>
<indexterm role="cp"><primary>mode</primary></indexterm>
<indexterm role="cp"><primary>file mode</primary></indexterm>
<indexterm role="cp"><primary>changing file permissions</primary></indexterm>

<literallayout>PERMISSIONS
        FILE=&#8217;<replaceable>file_name</replaceable>&#8217;
        /PERMISSIONS = {READONLY,WRITEABLE}.
</literallayout>
<para><literal>PERMISSIONS</literal> changes the permissions of a file.
There is one mandatory subcommand which specifies the permissions to
which the file should be changed.
If you set a file&#8217;s  permission  to <literal>READONLY</literal>, then the file
will become unwritable either by you or anyone else on the system.
If you set the permission to <literal>WRITEABLE</literal>, then the file becomes
writeable by you; the permissions afforded to others are unchanged.
This command cannot be used if the <literal>SAFER</literal> (see <link linkend="SET">SET</link>)
setting is active.
</para>

</sect1>
<sect1 label="17.19" id="PRESERVE-and-RESTORE">
<title>PRESERVE and RESTORE</title>
<indexterm role="vr"><primary>PRESERVE</primary></indexterm>
<indexterm role="vr"><primary>RESTORE</primary></indexterm>

<literallayout>PRESERVE.
&#8230;
RESTORE.
</literallayout>
<para><literal>PRESERVE</literal> saves all of the settings that <literal>SET</literal> (see <link linkend="SET">SET</link>)
can adjust.  A later <literal>RESTORE</literal> command restores those settings.
</para>
<para><literal>PRESERVE</literal> can be nested up to five levels deep.
</para>
</sect1>
<sect1 label="17.20" id="SET">
<title>SET</title>
<indexterm role="vr"><primary>SET</primary></indexterm>

<literallayout>SET

(data input)
        /BLANKS={SYSMIS,&#8217;.&#8217;,number}
        /DECIMAL={DOT,COMMA}
        /FORMAT=<replaceable>fmt_spec</replaceable>
        /EPOCH={AUTOMATIC,<replaceable>year</replaceable>}
        /RIB={NATIVE,MSBFIRST,LSBFIRST,VAX}
        /RRB={NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL}

(interaction)
        /MXERRS=<replaceable>max_errs</replaceable>
        /MXWARNS=<replaceable>max_warnings</replaceable>
        /WORKSPACE=<replaceable>workspace_size</replaceable>

(syntax execution)
        /LOCALE=&#8217;<replaceable>locale</replaceable>&#8217;
        /MXLOOPS=<replaceable>max_loops</replaceable>
        /SEED={RANDOM,<replaceable>seed_value</replaceable>}
        /UNDEFINED={WARN,NOWARN}
        /FUZZBITS=<replaceable>fuzzbits</replaceable>
        /SCALEMIN=<replaceable>count</replaceable>

(data output)
        /CC{A,B,C,D,E}={&#8217;<replaceable>npre</replaceable>,<replaceable>pre</replaceable>,<replaceable>suf</replaceable>,<replaceable>nsuf</replaceable>&#8217;,&#8217;<replaceable>npre</replaceable>.<replaceable>pre</replaceable>.<replaceable>suf</replaceable>.<replaceable>nsuf</replaceable>&#8217;}
        /DECIMAL={DOT,COMMA}
        /FORMAT=<replaceable>fmt_spec</replaceable>
        /LEADZERO={ON,OFF}
        /MDISPLAY={TEXT,TABLES}
        /SMALL=<replaceable>number</replaceable>
        /SUMMARY={NONE,<replaceable>comment</replaceable>}
        /WIB={NATIVE,MSBFIRST,LSBFIRST,VAX}
        /WRB={NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL}

(output routing)
        /ERRORS={ON,OFF,TERMINAL,LISTING,BOTH,NONE}
        /MESSAGES={ON,OFF,TERMINAL,LISTING,BOTH,NONE}
        /PRINTBACK={ON,OFF,TERMINAL,LISTING,BOTH,NONE}
        /RESULTS={ON,OFF,TERMINAL,LISTING,BOTH,NONE}

(output driver options)
        /HEADERS={NO,YES,BLANK}
        /LENGTH={NONE,<replaceable>n_lines</replaceable>}
        /WIDTH={NARROW,WIDTH,<replaceable>n_characters</replaceable>}
        /TNUMBERS={VALUES,LABELS,BOTH}
        /TVARS={NAMES,LABELS,BOTH}
        /TLOOK={NONE,<replaceable>file</replaceable>}

(logging)
        /JOURNAL={ON,OFF} [&#8217;<replaceable>file_name</replaceable>&#8217;]

(system files)
        /SCOMPRESSION={ON,OFF}

(miscellaneous)
        /SAFER=ON
        /LOCALE=&#8217;<replaceable>string</replaceable>&#8217;

(macros)
        /MEXPAND={ON,OFF}
        /MPRINT={ON,OFF}
        /MITERATE=<replaceable>number</replaceable>
        /MNEST=<replaceable>number</replaceable>

(settings not yet implemented, but accepted and ignored)
        /BASETEXTDIRECTION={AUTOMATIC,RIGHTTOLEFT,LEFTTORIGHT}
        /BLOCK=&#8217;<replaceable>c</replaceable>&#8217;
        /BOX={&#8217;<replaceable>xxx</replaceable>&#8217;,&#8217;<replaceable>xxxxxxxxxxx</replaceable>&#8217;}
        /CACHE={ON,OFF}
        /CELLSBREAK=<replaceable>number</replaceable>
        /COMPRESSION={ON,OFF}
        /CMPTRANS={ON,OFF}
        /HEADER={NO,YES,BLANK}
</literallayout>
<para><literal>SET</literal> allows the user to adjust several parameters relating to
PSPP&#8217;s execution.  Since there are many subcommands to this command, its
subcommands are examined in groups.
</para>
<para>For subcommands that take boolean values, <literal>ON</literal> and <literal>YES</literal> are synonymous,
as are <literal>OFF</literal> and <literal>NO</literal>, when used as subcommand values.
</para>
<para>The data input subcommands affect the way that data is read from data
files.  The data input subcommands are
</para>
<variablelist><varlistentry><term>BLANKS
</term><listitem><anchor id="SET-BLANKS"/><para>This is the value assigned to an item data item that is empty or
contains only white space.  An argument of SYSMIS or &#8217;.&#8217;  causes the
system-missing value to be assigned to null items.  This is the
default.  Any real value may be assigned.
</para>
</listitem></varlistentry><varlistentry><term>DECIMAL
</term><listitem><anchor id="SET-DECIMAL"/><para>This value may be set to <literal>DOT</literal> or <literal>COMMA</literal>.
Setting it to <literal>DOT</literal> causes the decimal point character to be
&#8216;<literal>.</literal>&#8217; and the grouping character to be &#8216;<literal>,</literal>&#8217;.
Setting it to <literal>COMMA</literal>
causes the decimal point character to be &#8216;<literal>,</literal>&#8217; and the grouping
character to be &#8216;<literal>.</literal>&#8217;.
If the setting is <literal>COMMA</literal>, then &#8216;<literal>,</literal>&#8217; is not treated
as a field separator in the <literal>DATA LIST</literal> command (see <link linkend="DATA-LIST">DATA LIST</link>).
The default value is determined from the system locale.
</para>
</listitem></varlistentry><varlistentry><term>FORMAT
</term><listitem><anchor id="SET-FORMAT"/><para>Allows the default numeric input/output format to be specified.  The
default is F8.2.  See <link linkend="Input-and-Output-Formats">Input and Output Formats</link>.
</para>
</listitem></varlistentry><varlistentry><term>EPOCH
</term><listitem><anchor id="SET-EPOCH"/><para>Specifies the range of years used when a 2-digit year is read from a
data file or used in a date construction expression (see <link linkend="Date-Construction">Date
Construction</link>).  If a 4-digit year is specified for the epoch, then
2-digit years are interpreted starting from that year, known as the
epoch.  If <literal>AUTOMATIC</literal> (the default) is specified, then the epoch begins
69 years before the current date.
</para>
</listitem></varlistentry><varlistentry><term>RIB
</term><listitem><anchor id="SET-RIB"/>
<para>PSPP extension to set the byte ordering (endianness) used for reading
data in IB or PIB format (see <link linkend="Binary-and-Hexadecimal-Numeric-Formats">Binary and Hexadecimal Numeric
Formats</link>).  In <literal>MSBFIRST</literal> ordering, the most-significant byte appears at
the left end of a IB or PIB field.  In <literal>LSBFIRST</literal> ordering, the
least-significant byte appears at the left end.  <literal>VAX</literal> ordering is like
<literal>MSBFIRST</literal>, except that each pair of bytes is in reverse order.  <literal>NATIVE</literal>,
the default, is equivalent to <literal>MSBFIRST</literal> or <literal>LSBFIRST</literal> depending on the
native format of the machine running PSPP.
</para>
</listitem></varlistentry><varlistentry><term>RRB
</term><listitem><anchor id="SET-RRB"/>
<para>PSPP extension to set the floating-point format used for reading data in
RB format (see <link linkend="Binary-and-Hexadecimal-Numeric-Formats">Binary and Hexadecimal Numeric Formats</link>).  The
possibilities are:
</para>
<variablelist><varlistentry><term>NATIVE
</term><listitem><para>The native format of the machine running PSPP.  Equivalent to either IDL
or IDB.
</para>
</listitem></varlistentry><varlistentry><term>ISL
</term><listitem><para>32-bit IEEE 754 single-precision floating point, in little-endian byte
order.
</para>
</listitem></varlistentry><varlistentry><term>ISB
</term><listitem><para>32-bit IEEE 754 single-precision floating point, in big-endian byte
order.
</para>
</listitem></varlistentry><varlistentry><term>IDL
</term><listitem><para>64-bit IEEE 754 double-precision floating point, in little-endian byte
order.
</para>
</listitem></varlistentry><varlistentry><term>IDB
</term><listitem><para>64-bit IEEE 754 double-precision floating point, in big-endian byte
order.
</para>
</listitem></varlistentry><varlistentry><term>VF
</term><listitem><para>32-bit VAX F format, in VAX-endian byte order.
</para>
</listitem></varlistentry><varlistentry><term>VD
</term><listitem><para>64-bit VAX D format, in VAX-endian byte order.
</para>
</listitem></varlistentry><varlistentry><term>VG
</term><listitem><para>64-bit VAX G format, in VAX-endian byte order.
</para>
</listitem></varlistentry><varlistentry><term>ZS
</term><listitem><para>32-bit IBM Z architecture short format hexadecimal floating point, in
big-endian byte order.
</para>
</listitem></varlistentry><varlistentry><term>ZL
</term><listitem><para>64-bit IBM Z architecture long format hexadecimal floating point, in
big-endian byte order.
</para>
<para>Z architecture also supports IEEE 754 floating point.  The ZS and ZL
formats are only for use with very old input files.
</para></listitem></varlistentry></variablelist><para>The default is NATIVE.
</para></listitem></varlistentry></variablelist>
<para>Interaction subcommands affect the way that PSPP interacts with an
online user.  The interaction subcommands are
</para>
<variablelist><varlistentry><term>MXERRS
</term><listitem><para>The maximum number of errors before PSPP halts processing of the current
command file.  The default is 50.
</para>
</listitem></varlistentry><varlistentry><term>MXWARNS
</term><listitem><para>The maximum number of warnings + errors before PSPP halts processing the
current command file.
The special value of zero means that all warning situations should be ignored.
No warnings are issued, except a single initial warning advising you
that warnings will not be given.
The default value is 100.
</para></listitem></varlistentry></variablelist>
<para>Syntax execution subcommands control the way that PSPP commands
execute.  The syntax execution subcommands are
</para>
<variablelist><varlistentry><term>LOCALE
</term><listitem><para>Overrides the system locale for the purpose of reading and writing
syntax and data files.  The argument should be a locale name in the
general form <literal><replaceable>language</replaceable>_<replaceable>country</replaceable>.<replaceable>encoding</replaceable></literal>, where <replaceable>language</replaceable>
and <replaceable>country</replaceable> are 2-character language and country abbreviations,
respectively, and <replaceable>encoding</replaceable> is an <acronym>IANA</acronym> character set name.
Example locales are <literal>en_US.UTF-8</literal> (UTF-8 encoded English as
spoken in the United States) and <literal>ja_JP.EUC-JP</literal> (EUC-JP encoded
Japanese as spoken in Japan).
</para>
</listitem></varlistentry><varlistentry><term>MXLOOPS
</term><listitem><anchor id="SET-MXLOOPS"/>
<para>The maximum number of iterations for an uncontrolled loop
(see <link linkend="LOOP">LOOP</link>), and for any loop in the matrix language (see <link linkend="Matrix-LOOP-and-BREAK-Commands">Matrix
LOOP and BREAK Commands</link>).  The default <replaceable>max_loops</replaceable> is 40.
</para>
</listitem></varlistentry><varlistentry><term>SEED
</term><listitem><anchor id="SET-SEED"/><para>The initial pseudo-random number seed.  Set it to a real number or to
RANDOM, to obtain an initial seed from the current time of day.
</para>
</listitem></varlistentry><varlistentry><term>UNDEFINED
</term><listitem><para>Currently not used.
</para>
</listitem></varlistentry><varlistentry><term>FUZZBITS
</term><listitem><anchor id="SET-FUZZBITS"/><para>The maximum number of bits of errors in the least-significant places
to accept for rounding up a value that is almost halfway between two
possibilities for rounding with the RND operator (see <link linkend="Miscellaneous-Mathematics">Miscellaneous
Mathematics</link>).  The default <replaceable>fuzzbits</replaceable> is 6.
</para>
</listitem></varlistentry><varlistentry><term>SCALEMIN
</term><listitem><anchor id="SET-SCALEMIN"/><para>The minimum number of distinct valid values for PSPP to assume that
a variable has a scale measurement level.  See <link linkend="Measurement-Level">Measurement Level</link>.
</para>
</listitem></varlistentry><varlistentry><term>WORKSPACE
</term><listitem><para>The maximum amount of memory (in kilobytes) that PSPP uses to
store data being processed.  If memory in excess of the workspace size
is required, then PSPP starts to use temporary files to store
the data.   Setting a higher value means that procedures
run faster, but may cause other applications to run slower.
On platforms without virtual memory management, setting a very large
workspace may cause PSPP to abort.
<indexterm role="cp"><primary>workspace</primary></indexterm>
<indexterm role="cp"><primary>memory, amount used to store cases</primary></indexterm>
</para></listitem></varlistentry></variablelist>
<para>Data output subcommands affect the format of output data.  These
subcommands are
</para>
<variablelist><varlistentry><term>CCA
</term><term>CCB
</term><term>CCC
</term><term>CCD
</term><term>CCE
</term><listitem><anchor id="CCx-Settings"/>
<para>Set up custom currency formats.  See <link linkend="Custom-Currency-Formats">Custom Currency Formats</link>, for
details.
</para>
</listitem></varlistentry><varlistentry><term>DECIMAL
</term><listitem><para>The default <literal>DOT</literal> setting causes the decimal point character to be
&#8216;<literal>.</literal>&#8217;.  A setting of <literal>COMMA</literal> causes the decimal point character to be
&#8216;<literal>,</literal>&#8217;.
</para>
</listitem></varlistentry><varlistentry><term>FORMAT
</term><listitem><para>Allows the default numeric input/output format to be specified.  The
default is F8.2.  See <link linkend="Input-and-Output-Formats">Input and Output Formats</link>.
</para>
</listitem></varlistentry><varlistentry><term>LEADZERO
</term><listitem><anchor id="SET-LEADZERO"/>
<para>Controls whether numbers with magnitude less than one are displayed
with a zero before the decimal point.  For example, with <literal>SET
LEADZERO=OFF</literal>, which is the default, one-half is shown as 0.5, and
with <literal>SET LEADZERO=ON</literal>, it is shown as .5.  This setting affects
only the <literal>F</literal>, <literal>COMMA</literal>, and <literal>DOT</literal> formats.
</para>
</listitem></varlistentry><varlistentry><term>MDISPLAY
</term><listitem><anchor id="SET-MDISPLAY"/>
<para>Controls how the <literal>PRINT</literal> command within
<literal>MATRIX</literal>&#8230;<literal>END MATRIX</literal> outputs matrices.  With the
default <literal>TEXT</literal>, <literal>PRINT</literal> outputs matrices as text.  Change
this setting to <literal>TABLES</literal> to instead output matrices as pivot
tables.  See <link linkend="Matrix-PRINT-Command">Matrix PRINT Command</link>, for more information.
</para>
</listitem></varlistentry><varlistentry><term>SMALL
</term><listitem><para>This controls how PSPP formats small numbers in pivot tables, in
cases where PSPP does not otherwise have a well-defined format for
the numbers.  When such a number has a magnitude less than the value
set here, PSPP formats the number in scientific notation;
otherwise, it formats it in standard notation.  The default is 0.0001.
Set a value of 0 to disable scientific notation.
</para>
</listitem></varlistentry><varlistentry><term>SUMMARY
</term><listitem><para>The <literal>SUMMARY</literal> option sets the comment string which will appear in all
generated tables until the next <literal>SUMMARY</literal> is issued.  If the special
value <literal>NONE</literal> is specified, then no comment will appear.
These comment strings can be seen in the graphical user interface by placing
the pointer over the table.
If <replaceable>comment</replaceable> contains any of the following substrings, they will be
subsituted as follows:
</para><variablelist><varlistentry><term><literal>\n</literal>
</term><listitem><para>A line break.
</para></listitem></varlistentry><varlistentry><term><literal>)DATE</literal>
</term><listitem><para>The current date in the form &#8216;<literal>dd-mmm-yyyy</literal>&#8217;
</para></listitem></varlistentry><varlistentry><term><literal>)ADATE</literal>
</term><listitem><para>The current date in the form &#8216;<literal>mm/dd/yyyy</literal>&#8217;
</para></listitem></varlistentry><varlistentry><term><literal>)SDATE</literal>
</term><listitem><para>The current date in the form &#8216;<literal>yyyy/mm/dd</literal>&#8217;
</para></listitem></varlistentry><varlistentry><term><literal>)EDATE</literal>
</term><listitem><para>The current date in the form &#8216;<literal>dd.mm.yyyy</literal>&#8217;
</para></listitem></varlistentry><varlistentry><term><literal>)TIME</literal>
</term><listitem><para>The current 12 hour clock time in the form &#8216;<literal>hh:mm:ss</literal>&#8217;
</para></listitem></varlistentry><varlistentry><term><literal>)ETIME</literal>
</term><listitem><para>The current 24 hour clock time in the form &#8216;<literal>hh:mm:ss</literal>&#8217;
</para></listitem></varlistentry></variablelist>
</listitem></varlistentry><varlistentry><term>WIB
</term><listitem><anchor id="SET-WIB"/>
<para>PSPP extension to set the byte ordering (endianness) used for writing
data in IB or PIB format (see <link linkend="Binary-and-Hexadecimal-Numeric-Formats">Binary and Hexadecimal Numeric
Formats</link>).  In <literal>MSBFIRST</literal> ordering, the most-significant byte appears at
the left end of a IB or PIB field.  In <literal>LSBFIRST</literal> ordering, the
least-significant byte appears at the left end.  <literal>VAX</literal> ordering is like
<literal>MSBFIRST</literal>, except that each pair of bytes is in reverse order.  <literal>NATIVE</literal>,
the default, is equivalent to <literal>MSBFIRST</literal> or <literal>LSBFIRST</literal> depending on the
native format of the machine running PSPP.
</para>
</listitem></varlistentry><varlistentry><term>WRB
</term><listitem><anchor id="SET-WRB"/>
<para>PSPP extension to set the floating-point format used for writing data in
RB format (see <link linkend="Binary-and-Hexadecimal-Numeric-Formats">Binary and Hexadecimal Numeric Formats</link>).  The choices
are the same as <literal>SET RIB</literal>.  The default is <literal>NATIVE</literal>.
</para></listitem></varlistentry></variablelist>
<para>In the PSPP text-based interface, the output routing subcommands
affect where output is sent.  The following values are allowed for
each of these subcommands:
</para>
<variablelist><varlistentry><term>OFF
</term></varlistentry><varlistentry><term>NONE
</term><listitem><para>Discard this kind of output.
</para>
</listitem></varlistentry><varlistentry><term>TERMINAL
</term><listitem><para>Write this output to the terminal, but not to listing files and other
output devices.
</para>
</listitem></varlistentry><varlistentry><term>LISTING
</term><listitem><para>Write this output to listing files and other output devices, but not
to the terminal.
</para>
</listitem></varlistentry><varlistentry><term>ON
</term><term>BOTH
</term><listitem><para>Write this type of output to all output devices.
</para></listitem></varlistentry></variablelist>
<para>These output routing subcommands are:
</para>
<variablelist><varlistentry><term>ERRORS
</term><listitem><para>Applies to error and warning messages.  The default is <literal>BOTH</literal>.
</para>
</listitem></varlistentry><varlistentry><term>MESSAGES
</term><listitem><para>Applies to notes.  The default is <literal>BOTH</literal>.
</para>
</listitem></varlistentry><varlistentry><term>PRINTBACK
</term><listitem><para>Determines whether the syntax used for input is printed back as part
of the output.  The default is <literal>NONE</literal>.
</para>
</listitem></varlistentry><varlistentry><term>RESULTS
</term><listitem><para>Applies to everything not in one of the above categories, such as the
results of statistical procedures.  The default is <literal>BOTH</literal>.
</para></listitem></varlistentry></variablelist>
<para>These subcommands have no effect on output in the PSPP GUI
environment.
</para>
<para>Output driver option subcommands affect output drivers&#8217; settings.  These
subcommands are
</para>
<variablelist><varlistentry><term>HEADERS
</term><term>LENGTH
</term><term>WIDTH
</term><term>TNUMBERS
</term><listitem><para>The <literal>TNUMBERS</literal> option sets the way in which values are displayed in output tables.
The valid settings are <literal>VALUES</literal>, <literal>LABELS</literal> and <literal>BOTH</literal>.
If <literal>TNUMBERS</literal> is set to <literal>VALUES</literal>, then all values are displayed with their literal value
(which for a numeric value is a number and for a string value an alphanumeric string).
If <literal>TNUMBERS</literal> is set to <literal>LABELS</literal>, then values are displayed using their assigned labels if any.
(See <link linkend="VALUE-LABELS">VALUE LABELS</link>.)
If the value has no label, then the literal value is used for display.
If <literal>TNUMBERS</literal> is set to <literal>BOTH</literal>, then values are displayed with both their label
(if any) and their literal value in parentheses.
</para></listitem></varlistentry><varlistentry><term>TVARS
</term><listitem><anchor id="SET-TVARS"/><para>The <literal>TVARS</literal> option sets the way in which variables are displayed in output tables.
The valid settings are <literal>NAMES</literal>, <literal>LABELS</literal> and <literal>BOTH</literal>.
If <literal>TVARS</literal> is set to <literal>NAMES</literal>, then all variables are displayed using their names.
If <literal>TVARS</literal> is set to <literal>LABELS</literal>, then variables are displayed using their label if one
has been set.  If no label has been set, then the name is used.
(See <link linkend="VARIABLE-LABELS">VARIABLE LABELS</link>.)
If <literal>TVARS</literal> is set to <literal>BOTH</literal>, then variables are displayed with both their label
(if any) and their name in parentheses.
</para></listitem></varlistentry><varlistentry><term>TLOOK
</term><listitem><para>The <literal>TLOOK</literal> option sets the style used for subsequent table
output.  Specifying <literal>NONE</literal> makes PSPP use the default
built-in style.  Otherwise, specifying <replaceable>file</replaceable> makes PSPP search
for an <filename>.stt</filename> or <filename>.tlo</filename> file in the same way as specifying
<option>--table-look=<replaceable>file</replaceable></option> the PSPP command line (see <link linkend="Main-Options">Main
Options</link>).
</para></listitem></varlistentry></variablelist>
<indexterm role="cp"><primary>headers</primary></indexterm>
<indexterm role="cp"><primary>length</primary></indexterm>
<indexterm role="cp"><primary>pager</primary></indexterm>
<indexterm role="cp"><primary>width</primary></indexterm>
<indexterm role="cp"><primary>tnumbers</primary></indexterm>

<para>These subcommands affect journaling, also called logging.  When
journaling is enabled, PSPP writes the commands that it executes,
plus any errors or other diagostics that it outputs, to a text file,
called the <firstterm>journal</firstterm> file.
</para>
<para>PSPP enables journaling by default when it runs interactively in a
terminal or in the PSPPIRE GUI.  In the GUI, use Edit
&#8594; Options&#8230; to view or override the default location or
to disable journaling.  From syntax, use <literal>SHOW JOURNAL</literal> to see
the journal&#8217;s location and whether it is enabled.
</para>
<variablelist><varlistentry><term>JOURNAL
</term><term>LOG
</term><listitem><para>Specify <literal>ON</literal> to enable the journal and <literal>OFF</literal> to disable
it.  Specify a file name to set the name of the journal file.
</para></listitem></varlistentry></variablelist>
<para>System file subcommands affect the default format of system files
produced by PSPP.  These subcommands are
</para>
<variablelist><varlistentry><term>SCOMPRESSION
</term><listitem><para>Whether system files created by <literal>SAVE</literal> or <literal>XSAVE</literal> are
compressed by default.  The default is <literal>ON</literal>.
</para></listitem></varlistentry></variablelist>
<para>Security subcommands affect the operations that commands are allowed to
perform.  The security subcommands are
</para>
<variablelist><varlistentry><term>SAFER
</term><listitem><para>Setting this option disables the following operations:
</para>
<itemizedlist><listitem><para>The <literal>ERASE</literal> command.
</para></listitem><listitem><para>The <literal>HOST</literal> command.
</para></listitem><listitem><para>The <literal>PERMISSIONS</literal> command.
</para></listitem><listitem><para>Pipes (file names beginning or ending with &#8216;<literal>|</literal>&#8217;).
</para></listitem></itemizedlist>
<para>Be aware that this setting does not guarantee safety (commands can still
overwrite files, for instance) but it is an improvement.
When set, this setting cannot be reset during the same session, for
obvious security reasons.
</para>
</listitem></varlistentry><varlistentry><term>LOCALE
</term><listitem><indexterm role="cp"><primary>locale</primary></indexterm>
<indexterm role="cp"><primary>encoding, characters</primary></indexterm>
<para>This item is used to set the default character encoding.
The encoding may be specified either as an encoding name or alias
(see <ulink url="http://www.iana.org/assignments/character-sets">http://www.iana.org/assignments/character-sets</ulink>), or
as a locale name.
If given as a locale name, only the character encoding of the
locale is relevant.
</para>
<para>System files written by PSPP use this encoding.
System files read by PSPP, for which the encoding is unknown, are
interpreted using this encoding.
</para>
<para>The full list of valid encodings and locale names/alias are operating system
dependent.
The following are all examples of acceptable syntax on common GNU/Linux
systems.
</para><screen>SET LOCALE='iso-8859-1'.

SET LOCALE='ru_RU.cp1251'.

SET LOCALE='japanese'.
</screen>
<para>Contrary to intuition, this command does not affect any aspect
of the system&#8217;s locale.
</para></listitem></varlistentry></variablelist>
<para>The following subcommands affect the interpretation of macros.
</para>
<variablelist><varlistentry><term>MEXPAND
</term><listitem><anchor id="SET-MEXPAND"/><para>Controls whether macros are expanded.  The default is ON.
</para>
</listitem></varlistentry><varlistentry><term>MPRINT
</term><listitem><anchor id="SET-MPRINT"/><para>Controls whether the expansion of macros is included in output.  This
is separate from whether command syntax in general is included in
output.  The default is OFF.
</para>
</listitem></varlistentry><varlistentry><term>MITERATE
</term><listitem><anchor id="SET-MITERATE"/><para>Limits the number of iterations executed in <literal>!DO</literal> loops within
macros.  This does not affect other language constructs such as
<literal>LOOP</literal>.  This must be set to a positive integer.  The default is
1000.
</para>
</listitem></varlistentry><varlistentry><term>MNEST
</term><listitem><anchor id="SET-MNEST"/><para>Limits the number of levels of nested macro expansions.  This must be
set to a positive integer.  The default is 50.
</para></listitem></varlistentry></variablelist>
<para>The following subcommands are not yet implemented, but PSPP accepts
them and ignores the settings.
</para>
<variablelist><varlistentry><term>BASETEXTDIRECTION
</term><term>BLOCK
</term><term>BOX
</term><term>CACHE
</term><term>CELLSBREAK
</term><term>COMPRESSION
</term><term>CMPTRANS
</term><term>HEADER
</term></varlistentry></variablelist>
</sect1>
<sect1 label="17.21" id="SHOW">
<title>SHOW</title>
<indexterm role="vr"><primary>SHOW</primary></indexterm>

<literallayout>SHOW
        [ALL]
        [BLANKS]
        [CC]
        [CCA]
        [CCB]
        [CCC]
        [CCD]
        [CCE]
        [COPYING]
        [DECIMAL]
        [DIRECTORY]
        [ENVIRONMENT]
        [FORMAT]
        [FUZZBITS]
        [LENGTH]
        [MEXPAND]
        [MPRINT]
        [MITERATE]
        [MNEST]
        [MXERRS]
        [MXLOOPS]
        [MXWARNS]
        [N]
        [SCOMPRESSION]
        [SYSTEM]
        [TEMPDIR]
        [UNDEFINED]
        [VERSION]
        [WARRANTY]
        [WEIGHT]
        [WIDTH]
</literallayout>
<para><literal>SHOW</literal> can be used to display the current state of PSPP&#8217;s execution
parameters.  Parameters that can be changed using <literal>SET</literal>
(see <link linkend="SET">SET</link>), can be examined using <literal>SHOW</literal> using the subcommand
with the same name.  <literal>SHOW</literal> supports the following additional
subcommands:
</para>
<variablelist><varlistentry><term><literal>ALL</literal>
</term><listitem><para>Show all settings.
</para></listitem></varlistentry><varlistentry><term><literal>CC</literal>
</term><listitem><para>Show all custom currency settings (<literal>CCA</literal> through <literal>CCE</literal>).
</para></listitem></varlistentry><varlistentry><term><literal>DIRECTORY</literal>
</term><listitem><para>Shows the current working directory.
</para></listitem></varlistentry><varlistentry><term><literal>ENVIRONMENT</literal>
</term><listitem><para>Shows the operating system details.
</para></listitem></varlistentry><varlistentry><term><literal>N</literal>
</term><listitem><para>Reports the number of cases in the active dataset.  The reported number is not
weighted.  If no dataset is defined, then &#8216;<literal>Unknown</literal>&#8217; is reported.
</para></listitem></varlistentry><varlistentry><term><literal>SYSTEM</literal>
</term><listitem><para>Shows information about how PSPP was built.  This information is
useful in bug reports.  See <link linkend="Bugs">Bugs</link>, for details.
</para></listitem></varlistentry><varlistentry><term><literal>TEMPDIR</literal>
</term><listitem><para>Shows the path of the directory where temporary files are stored.
</para></listitem></varlistentry><varlistentry><term><literal>VERSION</literal>
</term><listitem><para>Shows the version of this installation of PSPP.
</para></listitem></varlistentry><varlistentry><term><literal>WARRANTY</literal>
</term><listitem><para>Show details of the lack of warranty for PSPP.
</para></listitem></varlistentry><varlistentry><term><literal>COPYING</literal> / <literal>LICENSE</literal>
</term><listitem><para>Display the terms of PSPP&#8217;s copyright licence (see <link linkend="License">License</link>).
</para></listitem></varlistentry></variablelist>
<para>Specifying <literal>SHOW</literal> without any subcommands is equivalent to <literal>SHOW ALL</literal>.
</para>
</sect1>
<sect1 label="17.22" id="SUBTITLE">
<title>SUBTITLE</title>
<indexterm role="vr"><primary>SUBTITLE</primary></indexterm>

<literallayout>SUBTITLE &#8217;<replaceable>subtitle_string</replaceable>&#8217;.
  or
SUBTITLE <replaceable>subtitle_string</replaceable>.
</literallayout>
<para><literal>SUBTITLE</literal> provides a subtitle to a particular PSPP
run.  This subtitle appears at the top of each output page below the
title, if headers are enabled on the output device.
</para>
<para>Specify a subtitle as a string in quotes.  The alternate syntax that did
not require quotes is now obsolete.  If it is used then the subtitle is
converted to all uppercase.
</para>
</sect1>
<sect1 label="17.23" id="TITLE">
<title>TITLE</title>
<indexterm role="vr"><primary>TITLE</primary></indexterm>

<literallayout>TITLE &#8217;<replaceable>title_string</replaceable>&#8217;.
  or
TITLE <replaceable>title_string</replaceable>.
</literallayout>
<para><literal>TITLE</literal> provides a title to a particular PSPP run.
This title appears at the top of each output page, if headers are enabled
on the output device.
</para>
<para>Specify a title as a string in quotes.  The alternate syntax that did
not require quotes is now obsolete.  If it is used then the title is
converted to all uppercase.
</para>
<!-- PSPP - a program for statistical analysis. -->
<!-- Copyright (C) 2017, 2020 Free Software Foundation, Inc. -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.3 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<!-- A copy of the license is included in the section entitled "GNU -->
<!-- Free Documentation License". -->
<!-- -->
</sect1>
</chapter>
<chapter label="18" id="Invoking-pspp_002dconvert">
<title>Invoking <command>pspp-convert</command></title>
<indexterm role="cp"><primary>Invocation</primary></indexterm>
<indexterm role="cp"><primary><command>pspp-convert</command></primary></indexterm>

<para><command>pspp-convert</command> is a command-line utility accompanying
PSPP. It reads an SPSS or SPSS/PC+ system file or SPSS portable
file or encrypted SPSS syntax file <replaceable>input</replaceable> and
writes a copy of it to another <replaceable>output</replaceable> in a different format.
Synopsis:
</para>
<literallayout><literal>pspp-convert</literal> [<replaceable>options</replaceable>] <replaceable>input</replaceable> <replaceable>output</replaceable>

<literal>pspp-convert --<!-- /@w -->help</literal>

<literal>pspp-convert --<!-- /@w -->version</literal>
</literallayout>
<para>The format of <replaceable>input</replaceable> is automatically detected, when possible.
The character encoding of old SPSS system files cannot always be
guessed correctly, and SPSS/PC+ system files do not include any
indication of their encoding.  Use <literal>-e <replaceable>encoding</replaceable></literal> to specify
the encoding in this case.
</para>
<para>By default, the intended format for <replaceable>output</replaceable> is inferred based on its
extension:
</para>
<variablelist><varlistentry><term><literal>csv</literal>
</term><term><literal>txt</literal>
</term><listitem><para>Comma-separated value.  Each value is formatted according to its
variable&#8217;s print format.  The first line in the file contains variable
names.
</para>
</listitem></varlistentry><varlistentry><term><literal>sav</literal>
</term></varlistentry><varlistentry><term><literal>sys</literal>
</term><listitem><para>SPSS system file.
</para>
</listitem></varlistentry><varlistentry><term><literal>por</literal>
</term><listitem><para>SPSS portable file.
</para>
</listitem></varlistentry><varlistentry><term><literal>sps</literal>
</term><listitem><para>SPSS syntax file.  (Only encrypted syntax files may be converted to
this format.)
</para></listitem></varlistentry></variablelist>
<para><command>pspp-convert</command> can convert most input formats to most output
formats.  Encrypted SPSS file formats are exceptions: if the input
file is in an encrypted format, then the output file will be the same
format (decrypted).  To decrypt such a file, specify the encrypted
file as <replaceable>input</replaceable>.  The output will be the equivalent plaintext
file.  Options for the output format are ignored in this case.
</para>
<para>The password for encrypted files can be specified a few different
ways.  If the password is known, use the <option>-p</option> option
(documented below) or allow <command>pspp-convert</command> to prompt for it.
If the password is unknown, use the <option>-a</option> and <option>-l</option>
options to specify how to search for it, or <option>--password-list</option>
to specify a file of passwords to try.
</para>
<para>Use <literal>-O <replaceable>format</replaceable></literal> to override the inferred format or to
specify the format for unrecognized extensions.
</para>
<para><command>pspp-convert</command> accepts the following general options:
</para>
<variablelist><varlistentry><term><option><option>-O <replaceable>format</replaceable></option></option>
</term><term><option><option>--output-format=<replaceable>format</replaceable></option></option>
</term><listitem><para>Sets the output format, where <replaceable>format</replaceable> is one of the extensions
listed above, <emphasis>e.g.</emphasis>: <option>-O csv</option>.  Use <option>--help</option> to list
the supported output formats.
</para>
</listitem></varlistentry><varlistentry><term><option>-c <replaceable>maxcases</replaceable></option>
</term><term><option>--cases=<replaceable>maxcases</replaceable></option>
</term><listitem><para>By default, all cases are copied from <replaceable>input</replaceable> to <replaceable>output</replaceable>.
Specifying this option to limit the number of cases written to
<replaceable>output</replaceable> to <replaceable>maxcases</replaceable>.
</para>
</listitem></varlistentry><varlistentry><term><option>-e <replaceable>charset</replaceable></option>
</term><term><option>--encoding=<replaceable>charset</replaceable></option>
</term><listitem><para>Overrides the encoding in which character strings in <replaceable>input</replaceable> are
interpreted.  This option is necessary because old SPSS system files,
and SPSS/PC+ system files, do not self-identify their encoding.
</para>
</listitem></varlistentry><varlistentry><term><option>-k <replaceable>variable</replaceable>&#8230;</option>
</term><term><option>--keep=<replaceable>variable</replaceable>&#8230;</option>
</term><listitem><para>By default, <command>pspp-convert</command> includes all the variables from the
input file.  Use this option to list specific variables to include;
any variables not listed will be dropped.  The variables in the output
file will also be reordered into the given order.  The variable list
may use <literal>TO</literal> in the same way as in PSPP syntax, <emphasis>e.g.</emphasis> if the
dictionary contains consecutive variables <literal>a</literal>, <literal>b</literal>,
<literal>c</literal>, and <literal>d</literal>, then <option>--keep='a to d'</option> will include all
of them (and no others).
</para>
</listitem></varlistentry><varlistentry><term><option>-d <replaceable>variable</replaceable>&#8230;</option>
</term><term><option>--drop=<replaceable>variable</replaceable>&#8230;</option>
</term><listitem><para>Drops the specified variables from the output.
</para>
<para>When <option>--keep</option> and <option>--drop</option> are used together,
<option>--keep</option> is processed first.
</para>
</listitem></varlistentry><varlistentry><term><option>-h</option>
</term><term><option>--help</option>
</term><listitem><para>Prints a usage message on stdout and exits.
</para>
</listitem></varlistentry><varlistentry><term><option>-v</option>
</term><term><option>--version</option>
</term><listitem><para>Prints version information on stdout and exits.
</para></listitem></varlistentry></variablelist>
<para>The following options affect CSV output:
</para>
<variablelist><varlistentry><term><option>--recode</option>
</term><listitem><para>By default, <command>pspp-convert</command> writes user-missing values to CSV
output files as their regular values.  With this option,
<command>pspp-convert</command> recodes them to system-missing values (which
are written as a single space).
</para>
</listitem></varlistentry><varlistentry><term><option>--no-var-names</option>
</term><listitem><para>By default, <command>pspp-convert</command> writes the variable names as the
first line of output.  With this option, <command>pspp-convert</command> omits
this line.
</para>
</listitem></varlistentry><varlistentry><term><option>--labels</option>
</term><listitem><para>By default, <command>pspp-convert</command> writes variables&#8217; values to CSV
output files.  With this option, <command>pspp-convert</command> writes value
labels.
</para>
</listitem></varlistentry><varlistentry><term><option>--print-formats</option>
</term><listitem><para>By default, <command>pspp-convert</command> writes numeric variables as plain
numbers.  This option makes <command>pspp-convert</command> honor variables&#8217;
print formats.
</para>
</listitem></varlistentry><varlistentry><term><option>--decimal=<replaceable>decimal</replaceable></option>
</term><listitem><para>This option sets the character used as a decimal point in output.  The
default is &#8216;<literal>.</literal>&#8217;.
</para>
</listitem></varlistentry><varlistentry><term><option>--delimiter=<replaceable>delimiter</replaceable></option>
</term><listitem><para>This option sets the character used to separate fields in output.  The
default is &#8216;<literal>,</literal>&#8217;, unless the decimal point is &#8216;<literal>,</literal>&#8217;, in which
case &#8216;<literal>;</literal>&#8217; is used.
</para>
</listitem></varlistentry><varlistentry><term><option>--qualifier=<replaceable>qualifier</replaceable></option>
</term><listitem><para>The option sets the character used to quote fields that contain the
delimiter.  The default is &#8216;<literal>&quot;</literal>&#8217;.
</para></listitem></varlistentry></variablelist>
<para>The following options specify how to obtain the password for encrypted
files:
</para>
<variablelist><varlistentry><term><option>-p <replaceable>password</replaceable></option>
</term></varlistentry><varlistentry><term><option>--password=<replaceable>password</replaceable></option>
</term><listitem><para>Specifies the password to use to decrypt an encrypted SPSS system file
or syntax file.  If this option is not specified,
<command>pspp-convert</command> will prompt interactively for the password as
necessary.
</para>
<para>Be aware that command-line options, including passwords, may be
visible to other users on multiuser systems.
</para>
<para>When used with <option>-a</option> (or <option>--password-alphabet</option>) and
<option>-l</option> (or <option>--password-length</option>), this option specifies the
starting point for the search.  This can be used to restart a search
that was interrupted.
</para>
</listitem></varlistentry><varlistentry><term><option>-a <replaceable>alphabet</replaceable></option>
</term></varlistentry><varlistentry><term><option>--password-alphabet=<replaceable>alphabet</replaceable></option>
</term><listitem><para>Specifies the alphabet of symbols over which to search for an
encrypted file&#8217;s password.  <replaceable>alphabet</replaceable> may include individual
characters and ranges delimited by &#8216;<literal>-</literal>&#8217;.  For example, <option>-a
a-z</option> searches lowercase letters, <option>-a A-Z0-9</option> searches uppercase
letters and digits, and <option>-a ' -~'</option> searches all printable ASCII
characters.
</para>
</listitem></varlistentry><varlistentry><term><option>-l <replaceable>max-length</replaceable></option>
</term></varlistentry><varlistentry><term><option>--password-length=<replaceable>max-length</replaceable></option>
</term><listitem><para>Specifies the maximum length of the passwords to try.
</para>
</listitem></varlistentry><varlistentry><term><option>--password-list=<replaceable>file</replaceable></option>
</term><listitem><para>Specifies a file to read containing a list of passwords to try, one
per line.  If <replaceable>file</replaceable> is <filename>-</filename>, reads from stdin.
</para></listitem></varlistentry></variablelist><!-- PSPP - a program for statistical analysis. -->
<!-- Copyright (C) 2019, 2020 Free Software Foundation, Inc. -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.3 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<!-- A copy of the license is included in the section entitled "GNU -->
<!-- Free Documentation License". -->
<!-- -->
</chapter>
<chapter label="19" id="Invoking-pspp_002doutput">
<title>Invoking <command>pspp-output</command></title>
<indexterm role="cp"><primary>Invocation</primary></indexterm>
<indexterm role="cp"><primary><command>pspp-output</command></primary></indexterm>

<para><command>pspp-output</command> is a command-line utility accompanying PSPP.
It supports multiple operations on SPSS viewer or <filename>.spv</filename> files,
here called SPV files.  SPSS 16 and later writes SPV files to
represent the contents of its output editor.
</para>
<para>SPSS 15 and earlier versions instead use <filename>.spo</filename> files.
<command>pspp-output</command> does not support this format.
</para>
<para><command>pspp-options</command> may be invoked in the following ways:
</para>
<literallayout><literal>pspp-output</literal> <literal>detect</literal> <replaceable>file</replaceable>

<literal>pspp-output</literal> [<replaceable>options</replaceable>] <literal>dir</literal> <replaceable>file</replaceable>

<literal>pspp-output</literal> [<replaceable>options</replaceable>] <literal>convert</literal> <replaceable>source</replaceable> <replaceable>destination</replaceable>

<literal>pspp-output</literal> [<replaceable>options</replaceable>] <literal>get-table-look</literal> <replaceable>source</replaceable> <replaceable>destination</replaceable>

<literal>pspp-output</literal> [<replaceable>options</replaceable>] <literal>convert-table-look</literal> <replaceable>source</replaceable> <replaceable>destination</replaceable>

<literal>pspp-output --<!-- /@w -->help</literal>

<literal>pspp-output --<!-- /@w -->version</literal>
</literallayout>
<para>Each of these forms is documented separately below.
<command>pspp-output</command> also has several undocumented command forms that
developers may find useful for debugging.
</para>

<sect1 label="19.1" id="The-pspp_002doutput-detect-Command">
<title>The <literal>detect</literal> Command</title>

<literallayout><literal>pspp-output</literal> <literal>detect</literal> <replaceable>file</replaceable>
</literallayout>
<para>When <replaceable>file</replaceable> is an SPV file, <command>pspp-output</command> exits
successfully without outputting anything.  When <replaceable>file</replaceable> is not an
SPV file or some other error occurs, <command>pspp-output</command> prints an
error message and exits with a failure indication.
</para>
</sect1>
<sect1 label="19.2" id="The-pspp_002doutput-dir-Command">
<title>The <literal>dir</literal> Command</title>

<literallayout><literal>pspp-output</literal> [<replaceable>options</replaceable>] <literal>dir</literal> <replaceable>file</replaceable>
</literallayout>
<para>Prints on stdout a table of contents for SPV file <replaceable>file</replaceable>.  By
default, this table lists every object in the file, except for hidden
objects.  See <link linkend="Input-Selection-Options">Input Selection Options</link>, for information on the
options available to select a subset of objects.
</para>
<para>The following additional option for <command>dir</command> is intended mainly
for use by PSPP developers:
</para>
<variablelist><varlistentry><term><option>--member-names</option>
</term><listitem><para>Also show the names of the Zip members associated with each object.
</para></listitem></varlistentry></variablelist>
</sect1>
<sect1 label="19.3" id="The-pspp_002doutput-convert-Command">
<title>The <literal>convert</literal> Command</title>

<literallayout><literal>pspp-output</literal> [<replaceable>options</replaceable>] <literal>convert</literal> <replaceable>source</replaceable> <replaceable>destination</replaceable>
</literallayout>
<para>Reads SPV file <replaceable>source</replaceable> and converts it to another format, writing
the output to <replaceable>destination</replaceable>.
</para>
<para>By default, the intended format for <replaceable>destination</replaceable> is inferred
based on its extension, in the same way that the <command>pspp</command>
program does for its output files.  See <link linkend="Invoking-PSPP">Invoking PSPP</link>, for details.
</para>
<para>See <link linkend="Input-Selection-Options">Input Selection Options</link>, for information on the options
available to select a subset of objects to include in the output.  The
following additional options are accepted:
</para>
<variablelist><varlistentry><term><option>-O format=<replaceable>format</replaceable></option>
</term><listitem><para>Overrides the format inferred from the output file&#8217;s extension.  Use
<option>--help</option> to list the available formats.  See <link linkend="Invoking-PSPP">Invoking PSPP</link>,
for details of the available output formats.
</para>
</listitem></varlistentry><varlistentry><term><option>-O <replaceable>option</replaceable>=<replaceable>value</replaceable></option>
</term><listitem><para>Sets an option for the output file format.  See <link linkend="Invoking-PSPP">Invoking PSPP</link>, for
details of the available output options.
</para>
</listitem></varlistentry><varlistentry><term><option>-F</option>
</term><term><option>--force</option>
</term><listitem><para>By default, if the source is corrupt or otherwise cannot be processed,
the destination is not written.  With <option>-F</option> or <option>--force</option>,
the destination is written as best it can, even with errors.
</para>
</listitem></varlistentry><varlistentry><term><option>--table-look=<replaceable>file</replaceable></option>
</term><listitem><para>Reads a table style from <replaceable>file</replaceable> and applies it to all of the
output tables.  The file should be a TableLook <filename>.stt</filename> or
<filename>.tlo</filename> file.
</para>
</listitem></varlistentry><varlistentry><term><option>--use-page-setup</option>
</term><listitem><para>By default, the <literal>convert</literal> command uses the default page setup
(for example, page size and margins) for <replaceable>destination</replaceable>, or the one
specified with <option>-O</option> options, if any.  Specify this option to
ignore these sources of page setup in favor of the one embedded in the
SPV, if any.
</para></listitem></varlistentry></variablelist>
</sect1>
<sect1 label="19.4" id="The-pspp_002doutput-get_002dtable_002dlook-Command">
<title>The <literal>get-table-look</literal> Command</title>

<literallayout><literal>pspp-output</literal> [<replaceable>options</replaceable>] <literal>get-table-look</literal> <replaceable>source</replaceable> <replaceable>destination</replaceable>
</literallayout>
<para>Reads SPV file <replaceable>source</replaceable>, applies any selection options
(see <link linkend="Input-Selection-Options">Input Selection Options</link>), picks the first table from the
selected object, extracts the TableLook from that table, and writes it
to <replaceable>destination</replaceable> (typically with an <filename>.stt</filename> extension) in the
TableLook XML format.
</para>
<para>Use &#8216;<literal>-</literal>&#8217; for <replaceable>source</replaceable> to instead write the default look to
<replaceable>destination</replaceable>.
</para>
<para>The user may use the TableLook file to change the style of tables in
other files, by passing it to the <option>--table-look</option> option on the
<literal>convert</literal> command.
</para>
</sect1>
<sect1 label="19.5" id="The-pspp_002doutput-convert_002dtable_002dlook-Command">
<title>The <literal>convert-table-look</literal> Command</title>

<literallayout><literal>pspp-output</literal> [<replaceable>options</replaceable>] <literal>convert-table-look</literal> <replaceable>source</replaceable> <replaceable>destination</replaceable>
</literallayout>
<para>Reads <filename>.stt</filename> or <filename>.tlo</filename> file <replaceable>source</replaceable>, and writes it back
to <replaceable>destination</replaceable> (typically with an <filename>.stt</filename> extension) in the
TableLook XML format.  This is useful for converting a TableLook
<filename>.tlo</filename> file from SPSS 15 or earlier into the newer <filename>.stt</filename>
format.
</para>
</sect1>
<sect1 label="19.6" id="Input-Selection-Options">
<title>Input Selection Options</title>

<para>The <command>dir</command> and <command>convert</command> commands, by default, operate
on all of the objects in the source SPV file, except for objects that
are not visible in the output viewer window.  The user may specify
these options to select a subset of the input objects.  When multiple
options are used, only objects that satisfy all of them are selected:
</para>
<variablelist><varlistentry><term><option>--select=[^]<replaceable>class</replaceable>&#8230;</option>
</term><listitem><para>Include only objects of the given <replaceable>class</replaceable>; with leading &#8216;<literal>^</literal>&#8217;,
include only objects not in the class.  Use commas to separate
multiple classes.  The supported classes are:
</para>
<blockquote><para><literal>charts headings logs models tables texts trees warnings
outlineheaders pagetitle notes unknown other</literal>
</para></blockquote>
<para>Use <option>--select=help</option> to print this list of classes.
</para>
</listitem></varlistentry><varlistentry><term><option>--commands=[^]<replaceable>command</replaceable>&#8230;</option>
</term><term><option>--subtypes=[^]<replaceable>subtype</replaceable>&#8230;</option>
</term><term><option>--labels=[^]<replaceable>label</replaceable>&#8230;</option>
</term><listitem><para>Include only objects with the specified <replaceable>command</replaceable>, <replaceable>subtype</replaceable>,
or <replaceable>label</replaceable>.  With a leading &#8216;<literal>^</literal>&#8217;, include only the objects
that do not match.  Multiple values may be specified separated by
commas.  An asterisk at the end of a value acts as a wildcard.
</para>
<para>The <option>--command</option> option matches command identifiers, case
insensitively.  All of the objects produced by a single command use
the same, unique command identifier.  Command identifiers are always
in English regardless of the language used for output.  They often
differ from the command name in PSPP syntax.  Use the
<command>pspp-output</command> program&#8217;s <command>dir</command> command to print command
identifiers in particular output.
</para>
<para>The <option>--subtypes</option> option matches particular tables within a
command, case insensitively.  Subtypes are not necessarily unique: two
commands that produce similar output tables may use the same subtype.
Subtypes are always in English and <command>dir</command> will print them.
</para>
<para>The <option>--labels</option> option matches the labels in table output (that
is, the table titles).  Labels are affected by the output language,
variable names and labels, split file settings, and other factors.
</para>
</listitem></varlistentry><varlistentry><term><option>--nth-commands=<replaceable>n</replaceable>&#8230;</option>
</term><listitem><para>Include only objects from the <replaceable>n</replaceable>th command that matches
<option>--command</option> (or the <replaceable>n</replaceable>th command overall if
<option>--command</option> is not specified), where <replaceable>n</replaceable> is 1 for the first
command, 2 for the second, and so on.
</para>
</listitem></varlistentry><varlistentry><term><option>--instances=<replaceable>instance</replaceable>&#8230;</option>
</term><listitem><para>Include the specified <replaceable>instance</replaceable> of an object that matches the
other criteria within a single command.  The <replaceable>instance</replaceable> may be a
number (1 for the first instance, 2 for the second, and so on) or
<literal>last</literal> for the last instance.
</para>
</listitem></varlistentry><varlistentry><term><option>--show-hidden</option>
</term><listitem><para>Include hidden output objects in the output.  By default, they are
excluded.
</para>
</listitem></varlistentry><varlistentry><term><option>--or</option>
</term><listitem><para>Separates two sets of selection options.  Objects selected by either
set of options are included in the output.
</para></listitem></varlistentry></variablelist>
<para>The following additional input selection options are intended mainly
for use by PSPP developers:
</para>
<variablelist><varlistentry><term><option>--errors</option>
</term><listitem><para>Include only objects that cause an error when read.  With the
<command>convert</command> command, this is most useful in conjunction with the
<option>--force</option> option.
</para>
</listitem></varlistentry><varlistentry><term><option>--members=<replaceable>member</replaceable>&#8230;</option>
</term><listitem><para>Include only the objects that include a listed Zip file <replaceable>member</replaceable>.
More than one name may be included, comma-separated.  The members in
an SPV file may be listed with the <command>dir</command> command by adding the
<option>--show-members</option> option or with the <command>zipinfo</command> program
included with many operating systems.  Error messages that
<command>pspp-output</command> prints when it reads SPV files also often
include member names.
</para>
</listitem></varlistentry><varlistentry><term><option>--member-names</option>
</term><listitem><para>Displays the name of the Zip member or members associated with each
object just above the object itself.
</para></listitem></varlistentry></variablelist><!-- PSPP - a program for statistical analysis. -->
<!-- Copyright (C) 2017, 2020 Free Software Foundation, Inc. -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.3 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<!-- A copy of the license is included in the section entitled "GNU -->
<!-- Free Documentation License". -->
<!-- -->
</sect1>
</chapter>
<chapter label="20" id="Invoking-pspp_002ddump_002dsav">
<title>Invoking <command>pspp-dump-sav</command></title>
<indexterm role="cp"><primary>Invocation</primary></indexterm>
<indexterm role="cp"><primary><command>pspp-dump-sav</command></primary></indexterm>

<para><command>pspp-dump-sav</command> is a command-line utility accompanying
PSPP.  It is not installed by default, so it may be missing
from your PSPP installation.
It reads one or more SPSS system files and prints their
contents.  The output format is useful for debugging system file
readers and writers and for discovering how to interpret unknown or
poorly understood records.  End users may find the output useful for
providing the PSPP developers information about system files that PSPP
does not accurately read.
</para>
<para>Synopsis:
</para>
<literallayout><literal>pspp-dump-sav</literal> [<literal>-d</literal>[<replaceable>maxcases</replaceable>] | <literal>--<!-- /@w -->data</literal>[<literal>=</literal><replaceable>maxcases</replaceable>]] <replaceable>file</replaceable>&#8230;

<literal>pspp-dump-sav --<!-- /@w -->help</literal> | <literal>-h</literal>

<literal>pspp-dump-sav --<!-- /@w -->version</literal> | <literal>-v</literal>
</literallayout>
<para>The following options are accepted:
</para>
<variablelist><varlistentry><term><literal>-d</literal>[<replaceable>maxcases</replaceable>]
</term></varlistentry><varlistentry><term><literal>--<!-- /@w -->data</literal>[<literal>=</literal><replaceable>maxcases</replaceable>]
</term><listitem><para>By default, <command>pspp-dump-sav</command> does not print any of the data in a
system file, only the file headers.  Specify this option to print the
data as well.  If <replaceable>maxcases</replaceable> is specified, then it limits the
number of cases printed.
</para>
</listitem></varlistentry><varlistentry><term><literal>-h</literal>
</term><term><literal>--<!-- /@w -->help</literal>
</term><listitem><para>Prints a usage message on stdout and exits.
</para>
</listitem></varlistentry><varlistentry><term><literal>-v</literal>
</term><term><literal>--<!-- /@w -->version</literal>
</term><listitem><para>Prints version information on stdout and exits.
</para></listitem></varlistentry></variablelist>
<para>Some errors that prevent files from being interpreted successfully
cause <command>pspp-dump-sav</command> to exit without reading any additional
files given on the command line.
<!-- PSPP - a program for statistical analysis. -->
<!-- Copyright (C) 2017, 2020 Free Software Foundation, Inc. -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.3 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<!-- A copy of the license is included in the section entitled "GNU -->
<!-- Free Documentation License". -->
<!-- -->
</para></chapter>
<chapter label="21" id="Not-Implemented">
<title>Not Implemented</title>

<para>This chapter lists parts of the PSPP language that are not yet
implemented.
</para>
<indexterm role="cp"><primary>unimplemented commands</primary></indexterm>
<indexterm role="cp"><primary>commands, unimplemented</primary></indexterm>

<!-- Generated from ../src/language/command.def by get-commands.py -->
<!-- Do not modify! -->

<variablelist><varlistentry><term><literal>2SLS</literal>
</term><listitem><para>Two stage least squares regression
</para>
</listitem></varlistentry><varlistentry><term><literal>ACF</literal>
</term><listitem><para>Autocorrelation function
</para>
</listitem></varlistentry><varlistentry><term><literal>ALSCAL</literal>
</term><listitem><para>Multidimensional scaling
</para>
</listitem></varlistentry><varlistentry><term><literal>ANACOR</literal>
</term><listitem><para>Correspondence analysis
</para>
</listitem></varlistentry><varlistentry><term><literal>ANOVA</literal>
</term><listitem><para>Factorial analysis of variance
</para>
</listitem></varlistentry><varlistentry><term><literal>CASEPLOT</literal>
</term><listitem><para>Plot time series
</para>
</listitem></varlistentry><varlistentry><term><literal>CASESTOVARS</literal>
</term><listitem><para>Restructure complex data
</para>
</listitem></varlistentry><varlistentry><term><literal>CATPCA</literal>
</term><listitem><para>Categorical principle components analysis
</para>
</listitem></varlistentry><varlistentry><term><literal>CATREG</literal>
</term><listitem><para>Categorical regression
</para>
</listitem></varlistentry><varlistentry><term><literal>CCF</literal>
</term><listitem><para>Time series cross correlation
</para>
</listitem></varlistentry><varlistentry><term><literal>CLEAR TRANSFORMATIONS</literal>
</term><listitem><para>Clears transformations from active dataset
</para>
</listitem></varlistentry><varlistentry><term><literal>CLUSTER</literal>
</term><listitem><para>Hierarchical clustering
</para>
</listitem></varlistentry><varlistentry><term><literal>CONJOINT</literal>
</term><listitem><para>Analyse full concept data
</para>
</listitem></varlistentry><varlistentry><term><literal>CORRESPONDENCE</literal>
</term><listitem><para>Show correspondence
</para>
</listitem></varlistentry><varlistentry><term><literal>COXREG</literal>
</term><listitem><para>Cox proportional hazards regression
</para>
</listitem></varlistentry><varlistentry><term><literal>CREATE</literal>
</term><listitem><para>Create time series data
</para>
</listitem></varlistentry><varlistentry><term><literal>CSDESCRIPTIVES</literal>
</term><listitem><para>Complex samples descriptives
</para>
</listitem></varlistentry><varlistentry><term><literal>CSGLM</literal>
</term><listitem><para>Complex samples GLM
</para>
</listitem></varlistentry><varlistentry><term><literal>CSLOGISTIC</literal>
</term><listitem><para>Complex samples logistic regression
</para>
</listitem></varlistentry><varlistentry><term><literal>CSPLAN</literal>
</term><listitem><para>Complex samples design
</para>
</listitem></varlistentry><varlistentry><term><literal>CSSELECT</literal>
</term><listitem><para>Select complex samples
</para>
</listitem></varlistentry><varlistentry><term><literal>CSTABULATE</literal>
</term><listitem><para>Tabulate complex samples
</para>
</listitem></varlistentry><varlistentry><term><literal>CURVEFIT</literal>
</term><listitem><para>Fit curve to line plot
</para>
</listitem></varlistentry><varlistentry><term><literal>DATE</literal>
</term><listitem><para>Create time series data
</para>
</listitem></varlistentry><varlistentry><term><literal>DETECTANOMALY</literal>
</term><listitem><para>Find unusual cases
</para>
</listitem></varlistentry><varlistentry><term><literal>DISCRIMINANT</literal>
</term><listitem><para>Linear discriminant analysis
</para>
</listitem></varlistentry><varlistentry><term><literal>EDIT</literal>
</term><listitem><para>obsolete
</para>
</listitem></varlistentry><varlistentry><term><literal>END FILE TYPE</literal>
</term><listitem><para>Ends complex data input
</para>
</listitem></varlistentry><varlistentry><term><literal>FILE TYPE</literal>
</term><listitem><para>Complex data input
</para>
</listitem></varlistentry><varlistentry><term><literal>FIT</literal>
</term><listitem><para>Goodness of Fit
</para>
</listitem></varlistentry><varlistentry><term><literal>GENLOG</literal>
</term><listitem><para>Categorical model fitting
</para>
</listitem></varlistentry><varlistentry><term><literal>GET TRANSLATE</literal>
</term><listitem><para>Read other file formats
</para>
</listitem></varlistentry><varlistentry><term><literal>GGRAPH</literal>
</term><listitem><para>Custom defined graphs
</para>
</listitem></varlistentry><varlistentry><term><literal>HILOGLINEAR</literal>
</term><listitem><para>Hierarchical loglinear models
</para>
</listitem></varlistentry><varlistentry><term><literal>HOMALS</literal>
</term><listitem><para>Homogeneity analysis
</para>
</listitem></varlistentry><varlistentry><term><literal>IGRAPH</literal>
</term><listitem><para>Interactive graphs
</para>
</listitem></varlistentry><varlistentry><term><literal>INFO</literal>
</term><listitem><para>Local Documentation
</para>
</listitem></varlistentry><varlistentry><term><literal>KEYED DATA LIST</literal>
</term><listitem><para>Read nonsequential data
</para>
</listitem></varlistentry><varlistentry><term><literal>KM</literal>
</term><listitem><para>Kaplan-Meier
</para>
</listitem></varlistentry><varlistentry><term><literal>LOGLINEAR</literal>
</term><listitem><para>General model fitting
</para>
</listitem></varlistentry><varlistentry><term><literal>MANOVA</literal>
</term><listitem><para>Multivariate analysis of variance
</para>
</listitem></varlistentry><varlistentry><term><literal>MAPS</literal>
</term><listitem><para>Geographical display
</para>
</listitem></varlistentry><varlistentry><term><literal>MIXED</literal>
</term><listitem><para>Mixed linear models
</para>
</listitem></varlistentry><varlistentry><term><literal>MODEL CLOSE</literal>
</term><listitem><para>Close server connection
</para>
</listitem></varlistentry><varlistentry><term><literal>MODEL HANDLE</literal>
</term><listitem><para>Define server connection
</para>
</listitem></varlistentry><varlistentry><term><literal>MODEL LIST</literal>
</term><listitem><para>Show existing models
</para>
</listitem></varlistentry><varlistentry><term><literal>MODEL NAME</literal>
</term><listitem><para>Specify model label
</para>
</listitem></varlistentry><varlistentry><term><literal>MULTIPLE CORRESPONDENCE</literal>
</term><listitem><para>Multiple correspondence analysis
</para>
</listitem></varlistentry><varlistentry><term><literal>MULT RESPONSE</literal>
</term><listitem><para>Multiple response analysis
</para>
</listitem></varlistentry><varlistentry><term><literal>MVA</literal>
</term><listitem><para>Missing value analysis
</para>
</listitem></varlistentry><varlistentry><term><literal>NAIVEBAYES</literal>
</term><listitem><para>Small sample bayesian prediction
</para>
</listitem></varlistentry><varlistentry><term><literal>NLR</literal>
</term><listitem><para>Non Linear Regression
</para>
</listitem></varlistentry><varlistentry><term><literal>NOMREG</literal>
</term><listitem><para>Multinomial logistic regression
</para>
</listitem></varlistentry><varlistentry><term><literal>NONPAR CORR</literal>
</term><listitem><para>Nonparametric correlation
</para>
</listitem></varlistentry><varlistentry><term><literal>NUMBERED</literal>
</term><listitem>

</listitem></varlistentry><varlistentry><term><literal>OLAP CUBES</literal>
</term><listitem><para>On-line analytical processing
</para>
</listitem></varlistentry><varlistentry><term><literal>OMS</literal>
</term><listitem><para>Output management
</para>
</listitem></varlistentry><varlistentry><term><literal>ORTHOPLAN</literal>
</term><listitem><para>Orthogonal effects design
</para>
</listitem></varlistentry><varlistentry><term><literal>OVERALS</literal>
</term><listitem><para>Nonlinear canonical correlation
</para>
</listitem></varlistentry><varlistentry><term><literal>PACF</literal>
</term><listitem><para>Partial autocorrelation
</para>
</listitem></varlistentry><varlistentry><term><literal>PARTIAL CORR</literal>
</term><listitem><para>Partial correlation
</para>
</listitem></varlistentry><varlistentry><term><literal>PLANCARDS</literal>
</term><listitem><para>Conjoint analysis planning
</para>
</listitem></varlistentry><varlistentry><term><literal>PLUM</literal>
</term><listitem><para>Estimate ordinal regression models
</para>
</listitem></varlistentry><varlistentry><term><literal>POINT</literal>
</term><listitem><para>Marker in keyed file
</para>
</listitem></varlistentry><varlistentry><term><literal>PPLOT</literal>
</term><listitem><para>Plot time series variables
</para>
</listitem></varlistentry><varlistentry><term><literal>PREDICT</literal>
</term><listitem><para>Specify forecast period
</para>
</listitem></varlistentry><varlistentry><term><literal>PREFSCAL</literal>
</term><listitem><para>Multidimensional unfolding
</para>
</listitem></varlistentry><varlistentry><term><literal>PRINCALS</literal>
</term><listitem><para>PCA by alternating least squares
</para>
</listitem></varlistentry><varlistentry><term><literal>PROBIT</literal>
</term><listitem><para>Probit analysis
</para>
</listitem></varlistentry><varlistentry><term><literal>PROCEDURE OUTPUT</literal>
</term><listitem><para>Specify output file
</para>
</listitem></varlistentry><varlistentry><term><literal>PROXIMITIES</literal>
</term><listitem><para>Pairwise similarity
</para>
</listitem></varlistentry><varlistentry><term><literal>PROXSCAL</literal>
</term><listitem><para>Multidimensional scaling of proximity data
</para>
</listitem></varlistentry><varlistentry><term><literal>RATIO STATISTICS</literal>
</term><listitem><para>Descriptives of ratios
</para>
</listitem></varlistentry><varlistentry><term><literal>READ MODEL</literal>
</term><listitem><para>Read new model
</para>
</listitem></varlistentry><varlistentry><term><literal>RECORD TYPE</literal>
</term><listitem><para>Defines a type of record within FILE TYPE
</para>
</listitem></varlistentry><varlistentry><term><literal>REFORMAT</literal>
</term><listitem><para>Read obsolete files
</para>
</listitem></varlistentry><varlistentry><term><literal>REPEATING DATA</literal>
</term><listitem><para>Specify multiple cases per input record
</para>
</listitem></varlistentry><varlistentry><term><literal>REPORT</literal>
</term><listitem><para>Pretty print working file
</para>
</listitem></varlistentry><varlistentry><term><literal>RMV</literal>
</term><listitem><para>Replace missing values
</para>
</listitem></varlistentry><varlistentry><term><literal>SCRIPT</literal>
</term><listitem><para>Run script file
</para>
</listitem></varlistentry><varlistentry><term><literal>SEASON</literal>
</term><listitem><para>Estimate seasonal factors
</para>
</listitem></varlistentry><varlistentry><term><literal>SELECTPRED</literal>
</term><listitem><para>Select predictor variables
</para>
</listitem></varlistentry><varlistentry><term><literal>SPCHART</literal>
</term><listitem><para>Plot control charts
</para>
</listitem></varlistentry><varlistentry><term><literal>SPECTRA</literal>
</term><listitem><para>Plot spectral density
</para>
</listitem></varlistentry><varlistentry><term><literal>STEMLEAF</literal>
</term><listitem><para>Plot stem-and-leaf display
</para>
</listitem></varlistentry><varlistentry><term><literal>SUMMARIZE</literal>
</term><listitem><para>Univariate statistics
</para>
</listitem></varlistentry><varlistentry><term><literal>SURVIVAL</literal>
</term><listitem><para>Survival analysis
</para>
</listitem></varlistentry><varlistentry><term><literal>TDISPLAY</literal>
</term><listitem><para>Display active models
</para>
</listitem></varlistentry><varlistentry><term><literal>TREE</literal>
</term><listitem><para>Create classification tree
</para>
</listitem></varlistentry><varlistentry><term><literal>TSAPPLY</literal>
</term><listitem><para>Apply time series model
</para>
</listitem></varlistentry><varlistentry><term><literal>TSET</literal>
</term><listitem><para>Set time sequence variables
</para>
</listitem></varlistentry><varlistentry><term><literal>TSHOW</literal>
</term><listitem><para>Show time sequence variables
</para>
</listitem></varlistentry><varlistentry><term><literal>TSMODEL</literal>
</term><listitem><para>Estimate time series model
</para>
</listitem></varlistentry><varlistentry><term><literal>TSPLOT</literal>
</term><listitem><para>Plot time sequence variables
</para>
</listitem></varlistentry><varlistentry><term><literal>TWOSTEP CLUSTER</literal>
</term><listitem><para>Cluster observations
</para>
</listitem></varlistentry><varlistentry><term><literal>UNIANOVA</literal>
</term><listitem><para>Univariate analysis
</para>
</listitem></varlistentry><varlistentry><term><literal>UNNUMBERED</literal>
</term><listitem><para>obsolete
</para>
</listitem></varlistentry><varlistentry><term><literal>VALIDATEDATA</literal>
</term><listitem><para>Identify suspicious cases
</para>
</listitem></varlistentry><varlistentry><term><literal>VARCOMP</literal>
</term><listitem><para>Estimate variance
</para>
</listitem></varlistentry><varlistentry><term><literal>VARSTOCASES</literal>
</term><listitem><para>Restructure complex data
</para>
</listitem></varlistentry><varlistentry><term><literal>VERIFY</literal>
</term><listitem><para>Report time series
</para>
</listitem></varlistentry><varlistentry><term><literal>WLS</literal>
</term><listitem><para>Weighted least squares regression
</para>
</listitem></varlistentry><varlistentry><term><literal>XGRAPH</literal>
</term><listitem><para>High resolution charts
</para>
</listitem></varlistentry></variablelist><!-- Local Variables: -->
<!-- buffer-read-only: t -->
<!-- End: -->

<!-- PSPP - a program for statistical analysis. -->
<!-- Copyright (C) 2017, 2020 Free Software Foundation, Inc. -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.3 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<!-- A copy of the license is included in the section entitled "GNU -->
<!-- Free Documentation License". -->
<!-- -->
</chapter>
<chapter label="22" id="Bugs">
<title>Bugs</title>

<indexterm role="cp"><primary>bugs</primary></indexterm>
<indexterm role="cp"><primary>troubleshooting</primary></indexterm>

<para>Occasionally you may encounter a bug in PSPP.
</para>
<para>If you believe you have found a bug, please
make sure that it really is a bug.  Sometimes, what may appear
to be a bug, turns out to be a misunderstanding of how to use the program.
If you are unsure, ask for advice on the pspp-users mailing list.
Information about the mailing list is at <ulink url="http://lists.gnu.org/mailman/listinfo/pspp-users">http://lists.gnu.org/mailman/listinfo/pspp-users</ulink>.
</para>
<para>It is also valuable to try the newest version of PSPP, since the
problem may have already been fixed.  You can always find the newest
version of PSPP by visiting <ulink url="https://www.gnu.org/s/pspp">the PSPP
website</ulink>.  You might have obtained PSPP from a downstream packager,
such as a GNU/Linux distribution; if your downstream package is not
up-to-date, please ask the distributor to update to the newest
version.
</para>
<para>If the problem persists in the up-to-date version, check to see if it
has already been reported.  Reported issues are listed at
<ulink url="http://savannah.gnu.org/bugs/?group=pspp">http://savannah.gnu.org/bugs/?group=pspp</ulink>.  If it has already
been reported, you might consider adding a comment with additional
information or even just to mention that you are also experiencing the
problem, since the PSPP developers are often inclined to work on
issues that are important to a large number of users.
</para>
<para>For known issues in individual language features, see the relevant section in see <link linkend="Language">Language</link>.
</para>
<para>If the problem exists in a recent version and it has not already
been reported, then please report it.
</para>

<sect1 label="22.1">
<title>How to report bugs</title>

<para>The best way to send a bug report is using the web page at
<ulink url="http://savannah.gnu.org/bugs/?group=pspp">http://savannah.gnu.org/bugs/?group=pspp</ulink>.
Alternatively, bug reports may be sent by email
to <email>bug-gnu-pspp@gnu.org</email>.
</para>
<para>A high-quality bug report allows the developers to understand,
reproduce, and ultimately fix the problem.  We recommend
including the following:
</para>
<itemizedlist><listitem><para>The version of PSPP in which you encountered the problem.  It also
often helps to know some information about how PSPP was built.
</para>
<para>With PSPP command syntax, <literal>SHOW SYSTEM.</literal> will output
everything we ordinarily need.  In the PSPPIRE GUI,
Help &#8594; System Info produces the same output.
</para>
</listitem><listitem><para>The operating system and type of computer on which it is running.
</para>
</listitem><listitem><para>A sample of the syntax which causes the problem or, if it is a user
 interface problem, the sequence of steps required to reproduce it.
 Screenshots can be helpful for reporting bugs in the graphical user
 interface, especially since GUI bugs can arise on some systems but
 not others, but they do not usually help fixing other kinds of bugs.
</para>
</listitem><listitem><para>A description of what you think is wrong: What happened that you
  didn&#8217;t expect, and what did you expect to happen?  Include any error
  messages that PSPP output.
</para></listitem></itemizedlist>
<para>Here is one example of a bug report that includes all of the elements above:
</para>
<sidebar><screen>I'm running PSPP on a system where <literal>SHOW SYSTEM.</literal>  outputs the
following:

<!-- Use @image for Info and for plaintext output. -->
<!-- Use HTML for HTML output. -->
<!-- Use the Texi-fied version of the plaintext output for other output formats. -->
<!-- Some of these could do better, but we have not yet implemented it. -->
</screen><screen>                   System Information
+----------------+------------------------------------+
|Version         |GNU pspp 2.1.1                      |
|Host System     |x86_64-pc-linux-gnu                 |
|Build System    |x86_64-pc-linux-gnu                 |
|Locale Directory|/usr/local/share/locale             |
|Journal File    |/home/blp/.local/state/pspp/pspp.jnl|
|Compiler Version|15.2.1 20251111 (Red Hat 15.2.1-4)  |
+----------------+------------------------------------+
</screen><screen>
The bug I'm seeing is that executing the following syntax:

 DATA LIST FREE /x *.
 BEGIN DATA.
 1 2 3
 END DATA.
 LIST.

results in:

 4
 5
 6

but I think the output should be:

 1
 2
 3
</screen></sidebar>
<para>The following bug report, on the other hand, does not provide enough
information for PSPP developers to understand the problem.  This means
that the developers cannot identify or fix the problem without
additional rounds of questions, which is more work for both the
reporter and the developer:
</para>
<sidebar><screen>I downloaded the latest version of PSPP and entered a sequence of numbers,
but when I analyse them it gives the wrong output.
</screen></sidebar>
<para>PSPP developers value all users&#8217; feedback, but cannot promise
an immediate response.  The bug reporting is not a consultancy or
support service, although you can make private arrangements for such
services.  Since PSPP is free software, consultants have access to
the information they need to provide such support.
</para>
<para>For general enquiries or help, please use the
<ulink url="http://lists.gnu.org/mailman/listinfo/pspp-users">pspp-users
mailing list</ulink> instead of the bug mailing list or bug tracker.
</para>
<para>The PSPP bug tracker and bug reporting mailing list are public.  To
privately report a security vulnerability in GNU PSPP, please send
your report to the closed mailing list <email>pspp-security@gnu.org</email>.
The PSPP developers will help you assess your report and fix problems
prior to public disclosure.
</para>
<!-- PSPP - a program for statistical analysis. -->
<!-- Copyright (C) 2017, 2020 Free Software Foundation, Inc. -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.3 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<!-- A copy of the license is included in the section entitled "GNU -->
<!-- Free Documentation License". -->
<!-- -->
</sect1>
</chapter>
<chapter label="23" id="Function-Index">
<title>Function Index</title>
<index role="fn"></index>
<!-- PSPP - a program for statistical analysis. -->
<!-- Copyright (C) 2017, 2020 Free Software Foundation, Inc. -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.3 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<!-- A copy of the license is included in the section entitled "GNU -->
<!-- Free Documentation License". -->
<!-- -->
</chapter>
<chapter label="24" id="Command-Index">
<title>Command Index</title>
<index role="vr"></index>
<!-- PSPP - a program for statistical analysis. -->
<!-- Copyright (C) 2017, 2020 Free Software Foundation, Inc. -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.3 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<!-- A copy of the license is included in the section entitled "GNU -->
<!-- Free Documentation License". -->
<!-- -->
</chapter>
<chapter label="25" id="Concept-Index">
<title>Concept Index</title>
<index role="cp"></index>

<!-- PSPP - a program for statistical analysis. -->
<!-- Copyright (C) 2017 Free Software Foundation, Inc. -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.3 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<!-- A copy of the license is included in the section entitled "GNU -->
<!-- Free Documentation License". -->
<!-- -->
</chapter>
<appendix label="A" id="GNU-Free-Documentation-License">
<title>GNU Free Documentation License</title>

<!-- The GNU Free Documentation License. -->
<simpara role="center">Version 1.3, 3 November 2008</simpara>

<!-- This file is intended to be included within another document, -->
<!-- hence no sectioning command or @node. -->

<literallayout>Copyright &#169; 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
<ulink url="http://fsf.org/">http://fsf.org/</ulink>

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
</literallayout>
<orderedlist numeration="arabic"><listitem><para>PREAMBLE
</para>
<para>The purpose of this License is to make a manual, textbook, or other
functional and useful document <firstterm>free</firstterm> in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or noncommercially.
Secondarily, this License preserves for the author and publisher a way
to get credit for their work, while not being considered responsible
for modifications made by others.
</para>
<para>This License is a kind of &#8220;copyleft&#8221;, which means that derivative
works of the document must themselves be free in the same sense.  It
complements the GNU General Public License, which is a copyleft
license designed for free software.
</para>
<para>We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does.  But this License is not limited to software manuals;
it can be used for any textual work, regardless of subject matter or
whether it is published as a printed book.  We recommend this License
principally for works whose purpose is instruction or reference.
</para>
</listitem><listitem><para>APPLICABILITY AND DEFINITIONS
</para>
<para>This License applies to any manual or other work, in any medium, that
contains a notice placed by the copyright holder saying it can be
distributed under the terms of this License.  Such a notice grants a
world-wide, royalty-free license, unlimited in duration, to use that
work under the conditions stated herein.  The &#8220;Document&#8221;, below,
refers to any such manual or work.  Any member of the public is a
licensee, and is addressed as &#8220;you&#8221;.  You accept the license if you
copy, modify or distribute the work in a way requiring permission
under copyright law.
</para>
<para>A &#8220;Modified Version&#8221; of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
</para>
<para>A &#8220;Secondary Section&#8221; is a named appendix or a front-matter section
of the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document&#8217;s overall
subject (or to related matters) and contains nothing that could fall
directly within that overall subject.  (Thus, if the Document is in
part a textbook of mathematics, a Secondary Section may not explain
any mathematics.)  The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding
them.
</para>
<para>The &#8220;Invariant Sections&#8221; are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License.  If a
section does not fit the above definition of Secondary then it is not
allowed to be designated as Invariant.  The Document may contain zero
Invariant Sections.  If the Document does not identify any Invariant
Sections then there are none.
</para>
<para>The &#8220;Cover Texts&#8221; are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License.  A Front-Cover Text may
be at most 5 words, and a Back-Cover Text may be at most 25 words.
</para>
<para>A &#8220;Transparent&#8221; copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters.  A copy made in an otherwise Transparent file
format whose markup, or absence of markup, has been arranged to thwart
or discourage subsequent modification by readers is not Transparent.
An image format is not Transparent if used for any substantial amount
of text.  A copy that is not &#8220;Transparent&#8221; is called &#8220;Opaque&#8221;.
</para>
<para>Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, La&tex; input
format, <acronym>SGML</acronym> or <acronym>XML</acronym> using a publicly available
<acronym>DTD</acronym>, and standard-conforming simple <acronym>HTML</acronym>,
PostScript or <acronym>PDF</acronym> designed for human modification.  Examples
of transparent image formats include <acronym>PNG</acronym>, <acronym>XCF</acronym> and
<acronym>JPG</acronym>.  Opaque formats include proprietary formats that can be
read and edited only by proprietary word processors, <acronym>SGML</acronym> or
<acronym>XML</acronym> for which the <acronym>DTD</acronym> and/or processing tools are
not generally available, and the machine-generated <acronym>HTML</acronym>,
PostScript or <acronym>PDF</acronym> produced by some word processors for
output purposes only.
</para>
<para>The &#8220;Title Page&#8221; means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page.  For works in
formats which do not have any title page as such, &#8220;Title Page&#8221; means
the text near the most prominent appearance of the work&#8217;s title,
preceding the beginning of the body of the text.
</para>
<para>The &#8220;publisher&#8221; means any person or entity that distributes copies
of the Document to the public.
</para>
<para>A section &#8220;Entitled XYZ&#8221; means a named subunit of the Document whose
title either is precisely XYZ or contains XYZ in parentheses following
text that translates XYZ in another language.  (Here XYZ stands for a
specific section name mentioned below, such as &#8220;Acknowledgements&#8221;,
&#8220;Dedications&#8221;, &#8220;Endorsements&#8221;, or &#8220;History&#8221;.)  To &#8220;Preserve the Title&#8221;
of such a section when you modify the Document means that it remains a
section &#8220;Entitled XYZ&#8221; according to this definition.
</para>
<para>The Document may include Warranty Disclaimers next to the notice which
states that this License applies to the Document.  These Warranty
Disclaimers are considered to be included by reference in this
License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and has
no effect on the meaning of this License.
</para>
</listitem><listitem><para>VERBATIM COPYING
</para>
<para>You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no other
conditions whatsoever to those of this License.  You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute.  However, you may accept
compensation in exchange for copies.  If you distribute a large enough
number of copies you must also follow the conditions in section 3.
</para>
<para>You may also lend copies, under the same conditions stated above, and
you may publicly display copies.
</para>
</listitem><listitem><para>COPYING IN QUANTITY
</para>
<para>If you publish printed copies (or copies in media that commonly have
printed covers) of the Document, numbering more than 100, and the
Document&#8217;s license notice requires Cover Texts, you must enclose the
copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover.  Both covers must also clearly and legibly identify
you as the publisher of these copies.  The front cover must present
the full title with all words of the title equally prominent and
visible.  You may add other material on the covers in addition.
Copying with changes limited to the covers, as long as they preserve
the title of the Document and satisfy these conditions, can be treated
as verbatim copying in other respects.
</para>
<para>If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.
</para>
<para>If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a computer-network location from which the general network-using
public has access to download using public-standard network protocols
a complete Transparent copy of the Document, free of added material.
If you use the latter option, you must take reasonably prudent steps,
when you begin distribution of Opaque copies in quantity, to ensure
that this Transparent copy will remain thus accessible at the stated
location until at least one year after the last time you distribute an
Opaque copy (directly or through your agents or retailers) of that
edition to the public.
</para>
<para>It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to give
them a chance to provide you with an updated version of the Document.
</para>
</listitem><listitem><para>MODIFICATIONS
</para>
<para>You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release
the Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy
of it.  In addition, you must do these things in the Modified Version:
</para>
<orderedlist numeration="upperalpha"><listitem><para>Use in the Title Page (and on the covers, if any) a title distinct
from that of the Document, and from those of previous versions
(which should, if there were any, be listed in the History section
of the Document).  You may use the same title as a previous version
if the original publisher of that version gives permission.
</para>
</listitem><listitem><para>List on the Title Page, as authors, one or more persons or entities
responsible for authorship of the modifications in the Modified
Version, together with at least five of the principal authors of the
Document (all of its principal authors, if it has fewer than five),
unless they release you from this requirement.
</para>
</listitem><listitem><para>State on the Title page the name of the publisher of the
Modified Version, as the publisher.
</para>
</listitem><listitem><para>Preserve all the copyright notices of the Document.
</para>
</listitem><listitem><para>Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
</para>
</listitem><listitem><para>Include, immediately after the copyright notices, a license notice
giving the public permission to use the Modified Version under the
terms of this License, in the form shown in the Addendum below.
</para>
</listitem><listitem><para>Preserve in that license notice the full lists of Invariant Sections
and required Cover Texts given in the Document&#8217;s license notice.
</para>
</listitem><listitem><para>Include an unaltered copy of this License.
</para>
</listitem><listitem><para>Preserve the section Entitled &#8220;History&#8221;, Preserve its Title, and add
to it an item stating at least the title, year, new authors, and
publisher of the Modified Version as given on the Title Page.  If
there is no section Entitled &#8220;History&#8221; in the Document, create one
stating the title, year, authors, and publisher of the Document as
given on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence.
</para>
</listitem><listitem><para>Preserve the network location, if any, given in the Document for
public access to a Transparent copy of the Document, and likewise
the network locations given in the Document for previous versions
it was based on.  These may be placed in the &#8220;History&#8221; section.
You may omit a network location for a work that was published at
least four years before the Document itself, or if the original
publisher of the version it refers to gives permission.
</para>
</listitem><listitem><para>For any section Entitled &#8220;Acknowledgements&#8221; or &#8220;Dedications&#8221;, Preserve
the Title of the section, and preserve in the section all the
substance and tone of each of the contributor acknowledgements and/or
dedications given therein.
</para>
</listitem><listitem><para>Preserve all the Invariant Sections of the Document,
unaltered in their text and in their titles.  Section numbers
or the equivalent are not considered part of the section titles.
</para>
</listitem><listitem><para>Delete any section Entitled &#8220;Endorsements&#8221;.  Such a section
may not be included in the Modified Version.
</para>
</listitem><listitem><para>Do not retitle any existing section to be Entitled &#8220;Endorsements&#8221; or
to conflict in title with any Invariant Section.
</para>
</listitem><listitem><para>Preserve any Warranty Disclaimers.
</para></listitem></orderedlist>
<para>If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant.  To do this, add their titles to the
list of Invariant Sections in the Modified Version&#8217;s license notice.
These titles must be distinct from any other section titles.
</para>
<para>You may add a section Entitled &#8220;Endorsements&#8221;, provided it contains
nothing but endorsements of your Modified Version by various
parties&#8212;for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
standard.
</para>
<para>You may add a passage of up to five words as a Front-Cover Text, and a
passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version.  Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity.  If the Document already
includes a cover text for the same cover, previously added by you or
by arrangement made by the same entity you are acting on behalf of,
you may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.
</para>
<para>The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.
</para>
</listitem><listitem><para>COMBINING DOCUMENTS
</para>
<para>You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice, and that you preserve all their Warranty Disclaimers.
</para>
<para>The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy.  If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.
</para>
<para>In the combination, you must combine any sections Entitled &#8220;History&#8221;
in the various original documents, forming one section Entitled
&#8220;History&#8221;; likewise combine any sections Entitled &#8220;Acknowledgements&#8221;,
and any sections Entitled &#8220;Dedications&#8221;.  You must delete all
sections Entitled &#8220;Endorsements.&#8221;
</para>
</listitem><listitem><para>COLLECTIONS OF DOCUMENTS
</para>
<para>You may make a collection consisting of the Document and other documents
released under this License, and replace the individual copies of this
License in the various documents with a single copy that is included in
the collection, provided that you follow the rules of this License for
verbatim copying of each of the documents in all other respects.
</para>
<para>You may extract a single document from such a collection, and distribute
it individually under this License, provided you insert a copy of this
License into the extracted document, and follow this License in all
other respects regarding verbatim copying of that document.
</para>
</listitem><listitem><para>AGGREGATION WITH INDEPENDENT WORKS
</para>
<para>A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, is called an &#8220;aggregate&#8221; if the copyright
resulting from the compilation is not used to limit the legal rights
of the compilation&#8217;s users beyond what the individual works permit.
When the Document is included in an aggregate, this License does not
apply to the other works in the aggregate which are not themselves
derivative works of the Document.
</para>
<para>If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one half of
the entire aggregate, the Document&#8217;s Cover Texts may be placed on
covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic form.
Otherwise they must appear on printed covers that bracket the whole
aggregate.
</para>
</listitem><listitem><para>TRANSLATION
</para>
<para>Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections.  You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also include
the original English version of this License and the original versions
of those notices and disclaimers.  In case of a disagreement between
the translation and the original version of this License or a notice
or disclaimer, the original version will prevail.
</para>
<para>If a section in the Document is Entitled &#8220;Acknowledgements&#8221;,
&#8220;Dedications&#8221;, or &#8220;History&#8221;, the requirement (section 4) to Preserve
its Title (section 1) will typically require changing the actual
title.
</para>
</listitem><listitem><para>TERMINATION
</para>
<para>You may not copy, modify, sublicense, or distribute the Document
except as expressly provided under this License.  Any attempt
otherwise to copy, modify, sublicense, or distribute it is void, and
will automatically terminate your rights under this License.
</para>
<para>However, if you cease all violation of this License, then your license
from a particular copyright holder is reinstated (a) provisionally,
unless and until the copyright holder explicitly and finally
terminates your license, and (b) permanently, if the copyright holder
fails to notify you of the violation by some reasonable means prior to
60 days after the cessation.
</para>
<para>Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
</para>
<para>Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License.  If your rights have been terminated and not permanently
reinstated, receipt of a copy of some or all of the same material does
not give you any rights to use it.
</para>
</listitem><listitem><para>FUTURE REVISIONS OF THIS LICENSE
</para>
<para>The Free Software Foundation may publish new, revised versions
of the GNU Free Documentation License from time to time.  Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns.  See
<ulink url="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</ulink>.
</para>
<para>Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
License &#8220;or any later version&#8221; applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation.  If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation.  If the Document
specifies that a proxy can decide which future versions of this
License can be used, that proxy&#8217;s public statement of acceptance of a
version permanently authorizes you to choose that version for the
Document.
</para>
</listitem><listitem><para>RELICENSING
</para>
<para>&#8220;Massive Multiauthor Collaboration Site&#8221; (or &#8220;MMC Site&#8221;) means any
World Wide Web server that publishes copyrightable works and also
provides prominent facilities for anybody to edit those works.  A
public wiki that anybody can edit is an example of such a server.  A
&#8220;Massive Multiauthor Collaboration&#8221; (or &#8220;MMC&#8221;) contained in the
site means any set of copyrightable works thus published on the MMC
site.
</para>
<para>&#8220;CC-BY-SA&#8221; means the Creative Commons Attribution-Share Alike 3.0
license published by Creative Commons Corporation, a not-for-profit
corporation with a principal place of business in San Francisco,
California, as well as future copyleft versions of that license
published by that same organization.
</para>
<para>&#8220;Incorporate&#8221; means to publish or republish a Document, in whole or
in part, as part of another Document.
</para>
<para>An MMC is &#8220;eligible for relicensing&#8221; if it is licensed under this
License, and if all works that were first published under this License
somewhere other than this MMC, and subsequently incorporated in whole
or in part into the MMC, (1) had no cover texts or invariant sections,
and (2) were thus incorporated prior to November 1, 2008.
</para>
<para>The operator of an MMC Site may republish an MMC contained in the site
under CC-BY-SA on the same site at any time before August 1, 2009,
provided the MMC is eligible for relicensing.
</para>
</listitem></orderedlist>
<bridgehead renderas="sect1">ADDENDUM: How to use this License for your documents</bridgehead>

<para>To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and
license notices just after the title page:
</para>
<screen>  Copyright (C)  <replaceable>year</replaceable>  <replaceable>your name</replaceable>.
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.3
  or any later version published by the Free Software Foundation;
  with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
  Texts.  A copy of the license is included in the section entitled ``GNU
  Free Documentation License''.
</screen>
<para>If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
replace the &#8220;with&#8230;Texts.&#8221; line with this:
</para>
<screen>    with the Invariant Sections being <replaceable>list their titles</replaceable>, with
    the Front-Cover Texts being <replaceable>list</replaceable>, and with the Back-Cover Texts
    being <replaceable>list</replaceable>.
</screen>
<para>If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.
</para>
<para>If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License,
to permit their use in free software.
</para>
<!-- Local Variables: -->
<!-- ispell-local-pdict: "ispell-dict" -->
<!-- End: -->


</appendix>
</book>