Invoking pspp
*************

pspp has two separate user interfaces.  This chapter describes pspp, pspp's command-line driven text-based user interface. The following chapter briefly describes PSPPIRE, the graphical user interface to pspp.

The sections below describe the pspp program's command-line interface.

Main Options
============

Here is a summary of all the options, grouped by type, followed by explanations in the same order.

In the table, arguments to long options also apply to any corresponding short options.

Non-option arguments

          SYNTAX-FILE

Output options

          -o, --output=OUTPUT-FILE
          -O OPTION=VALUE
          -O format=FORMAT
          -O device={terminal|listing}
          --no-output
          -e, --error-file=ERROR-FILE

Language options

          -I, --include=DIR
          -I-, --no-include
          -b, --batch
          -i, --interactive
          -r, --no-statrc
          -a, --algorithm={compatible|enhanced}
          -x, --syntax={compatible|enhanced}
          --syntax-encoding=ENCODING

Informational options

          -h, --help
          -V, --version

Other options

          -s, --safer
          --testing-mode

SYNTAX-FILE
     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 - as an additional syntax file.

-o OUTPUT-FILE
     Write output to OUTPUT-FILE.  pspp has several different output drivers that support output in various formats (use --help to list the available formats).  Specify this option more than once to produce multiple output files, presumably in different formats.

     Use - as OUTPUT-FILE to write output to standard output.

     If no -o 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, e.g. pspp.pdf for PDF output.

-O OPTION=VALUE
     Sets an option for the output file configured by a preceding -o.  Most options are specific to particular output formats. A few options that apply generically are listed below.

-O format=FORMAT
     pspp uses the extension of the file name given on -o to select an output format.  Use this option to override this choice by specifying an alternate format, e.g. -o pspp.out -O html to write HTML to a file named pspp.out.  Use --help to list the available formats.

-O device={terminal|listing}
     Sets whether pspp considers the output device configured by the preceding -o to be a terminal or a listing device.  This affects what output will be sent to the device, as configured by the SET command's output routing subcommands (see SET).  By default, output written to standard output is considered a terminal device and other output is considered a listing device.

--no-output
     Disables output entirely, if neither -o nor -O is also used.  If one of those options is used, --no-output has no effect.

-e ERROR-FILE
--error-file=ERROR-FILE
     Configures a file to receive pspp error, warning, and note messages in plain text format.  Use - as ERROR-FILE 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 none as ERROR-FILE to explicitly suppress the default.

-I DIR
--include=DIR
     Appends DIR to the set of directories searched by the INCLUDE (see INCLUDE) and INSERT (see INSERT) commands.

-I-
--no-include
     Clears all directories from the include path, including directories inserted in the include path by default.  The default include path is . (the current directory), followed by .pspp in the user's home directory, followed by pspp's system configuration directory (usually /etc/pspp or /usr/local/etc/pspp).

-b

--batch

-i
--interactive
     These options forces syntax files to be interpreted in batch mode or interactive mode, respectively, rather than the default ``auto'' mode. See Syntax Variants, for a description of the differences.

-r
--no-statrc
     Disables running rc at pspp startup time.

-a {enhanced|compatible}
--algorithm={enhanced|compatible}
     With enhanced, the default, pspp uses the best implemented algorithms for statistical procedures.  With compatible, however, pspp will in some cases use inferior algorithms to produce the same results as the proprietary program SPSS.

     Some commands have subcommands that override this setting on a per command basis.

-x {enhanced|compatible}
--syntax={enhanced|compatible}
     With enhanced, the default, pspp accepts its own extensions beyond those compatible with the proprietary program SPSS.  With compatible, pspp rejects syntax that uses these extensions.

--syntax-encoding=ENCODING
     Specifies ENCODING as the encoding for syntax files named on the command line.  The ENCODING also becomes the default encoding for other syntax files read during the pspp session by the INCLUDE and INSERT commands.  See INSERT, for the accepted forms of ENCODING.

--help
     Prints a message describing pspp command-line syntax and the available device formats, then exits.

-V
--version
     Prints a brief message listing pspp's version, warranties you don't have, copying conditions and copyright, and e-mail address for bug reports, then exits.

-s
--safer
     Disables certain unsafe operations.  This includes the ERASE and HOST commands, as well as use of pipes as input and output files.

--testing-mode
     Invoke heuristics to assist with testing pspp.  For use by make check and similar scripts.

PDF, PostScript, and SVG Output Options
=======================================

To produce output in PDF, PostScript, and SVG formats, specify -o FILE on the pspp command line, optionally followed by any of the options shown in the table below to customize the output format.

PDF, PostScript, and SVG output is only available if your installation of pspp was compiled with the Cairo library.

-O format={pdf|ps|svg}
     Specify the output format.  This is only necessary if the file name given on -o does not end in .pdf, .ps, or .svg.

-O paper-size=PAPER-SIZE
     Paper size, as a name (e.g. a4, letter) or measurements (e.g. 210x297, 8.5x11in).

     The default paper size is taken from the PAPERSIZE environment variable or the file indicated by the PAPERCONF environment variable, if either variable is set.  If not, and your system supports the LC_PAPER locale category, then the default paper size is taken from the locale.  Otherwise, if /etc/papersize exists, the default paper size is read from it.  As a last resort, A4 paper is assumed.

-O foreground-color=COLOR
-O background-color=COLOR
     Sets COLOR as the color to be used for the background or foreground. Color should be given in the format #RRRRGGGGBBBB, where RRRR, GGGG and BBBB are 4 character hexadecimal representations of the red, green and blue components respectively.

-O orientation=ORIENTATION
     Either portrait or landscape.  Default: portrait.

-O left-margin=DIMENSION
-O right-margin=DIMENSION
-O top-margin=DIMENSION
-O bottom-margin=DIMENSION
     Sets the margins around the page.  See below for the allowed forms of DIMENSION Default: 0.5in.

-O prop-font=FONT-NAME
-O emph-font=FONT-NAME
-O fixed-font=FONT-NAME
     Sets the font used for proportional, emphasized, or fixed-pitch text. Most systems support CSS-like font names such as ``serif'' and ``monospace'', but a wide range of system-specific font are likely to be supported as well.

     Default: proportional font serif, emphasis font serif italic, fixed-pitch font monospace.

-O font-size=FONT-SIZE
     Sets the size of the default fonts, in thousandths of a point.  Default: 10000 (10 point).

-O line-gutter=DIMENSION
     Sets the width of white space on either side of lines that border text or graphics objects.  Default: 1pt.

-O line-spacing=DIMENSION
     Sets the spacing between the lines in a double line in a table. Default: 1pt.

-O line-width=DIMENSION
     Sets the width of the lines used in tables.  Default: 0.5pt.

Each DIMENSION value above may be specified in various units based on its suffix: mm for millimeters, in for inches, or pt for points.  Lacking a suffix, numbers below 50 are assumed to be in inches and those about 50 are assumed to be in millimeters.

Plain Text Output Options
=========================

pspp can produce plain text output, drawing boxes using ASCII or Unicode line drawing characters.  To produce plain text output, specify -o FILE on the pspp command line, optionally followed by options from the table below to customize the output format.

Plain text output is encoded in UTF-8.

-O format=txt
     Specify the output format.  This is only necessary if the file name given on -o does not end in .txt or .list.

-O charts={TEMPLATE.png|none}
     Name for chart files included in output.  The value should be a file name that includes a single # and ends in png.  When a chart is output, the # is replaced by the chart number.  The default is the file name specified on -o with the extension stripped off and replaced by -#.png.

     Specify none to disable chart output.  Charts are always disabled if your installation of pspp was compiled without the Cairo library.

-O foreground-color=COLOR
-O background-color=COLOR
     Sets COLOR as the color to be used for the background or foreground to be used for charts. Color should be given in the format #RRRRGGGGBBBB, where RRRR, GGGG and BBBB are 4 character hexadecimal representations of the red, green and blue components respectively. If charts are disabled, this option has no effect.

-O paginate=BOOLEAN
     If set, pspp writes an ASCII formfeed the end of every page.  Default: off.

-O headers=BOOLEAN
     If enabled, pspp prints two lines of header information giving title and subtitle, page number, date and time, and pspp version are printed at the top of every page.  These two lines are in addition to any top margin requested.  Default: off.

-O length=LINE-COUNT
     Physical length of a page.  Headers and margins are subtracted from this value.  You may specify the number of lines as a number, or for screen output you may specify auto to track the height of the terminal as it changes.  Default: 66.

-O width=CHARACTER-COUNT
     Width of a page, in characters.  Margins are subtracted from this value.  For screen output you may specify auto in place of a number to track the width of the terminal as it changes.  Default: 79.

-O top-margin=TOP-MARGIN-LINES
     Length of the top margin, in lines.  pspp subtracts this value from the page length.  Default: 0.

-O bottom-margin=BOTTOM-MARGIN-LINES
     Length of the bottom margin, in lines.  pspp subtracts this value from the page length.  Default: 0.

-O box={ascii|unicode}
     Sets the characters used for lines in tables. If set to ascii the characters -, |, and + for single-width lines and = and # for double-width lines are used. If set to unicode then  Unicode box drawing characters will be used. The default is unicode if the locale's character encoding is "UTF-8" or ascii otherwise.

-O emphasis={none|bold|underline}
     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: none.

HTML Output Options
===================

To produce output in HTML format, specify -o FILE on the pspp command line, optionally followed by any of the options shown in the table below to customize the output format.

-O format=html
     Specify the output format.  This is only necessary if the file name given on -o does not end in .html.

-O charts={TEMPLATE.png|none}
     Sets the name used for chart files.  See Plain Text Output Options, for details.

-O borders=BOOLEAN
     Decorate the tables with borders.  If set to false, the tables produced will have no borders.  The default value is true.

-O css=BOOLEAN
     Use cascading style sheets.  Cascading style sheets give an improved appearance and can be used to produce pages which fit a certain web site's style. The default value is true.

OpenDocument Output Options
===========================

To produce output as an OpenDocument text (ODT) document, specify -o FILE on the pspp command line.  If FILE does not end in .odt, you must also specify -O format=odt.

ODT support is only available if your installation of pspp was compiled with the libxml2 library.

The OpenDocument output format does not have any configurable options.

Comma-Separated Value Output Options
====================================

To produce output in comma-separated value (CSV) format, specify -o FILE on the pspp command line, optionally followed by any of the options shown in the table below to customize the output format.

-O format=csv
     Specify the output format.  This is only necessary if the file name given on -o does not end in .csv.

-O separator=FIELD-SEPARATOR
     Sets the character used to separate fields.  Default: a comma (,).

-O quote=QUALIFIER
     Sets QUALIFIER 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 QUALIFIER is longer than one character, only the first character is used; if QUALIFIER is the empty string, then fields are never quoted.

-O titles=BOOLEAN
     Whether table titles (brief descriptions) should be printed.  Default: on.

-O captions=BOOLEAN
     Whether table captions (more extensive descriptions) should be printed.  Default: on.

The CSV format used is an extension to that specified in RFC 4180:

Tables
     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.

Titles
     When a table has a title and titles are enabled, the title is output just above the table as a single field prefixed by Table:.

Captions
     When a table has a caption and captions are enabled, the caption is output just below the table as a single field prefixed by Caption:.

Footnotes
     Within a table, footnote markers are output as bracketed letters following the cell's contents, e.g. [a], [b], ...  The footnotes themselves are output following the body of the table, as a separate two-column table introduced with a line that says Footnotes:.  Each row in the table represent one footnote: the first column is the marker, the second column is the text.

Text
     Text in output is printed as a field on a line by itself.  The TITLE and SUBTITLE produce similar output, prefixed by Title: or Subtitle:, respectively.

Messages
     Errors, warnings, and notes are printed the same way as text.

Charts
     Charts are not included in CSV output.

Successive output items are separated by a blank line.

Invoking psppire
****************

The graphic user interface
==========================

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.

The graphic user interface can be started by typing psppire at a command prompt. Alternatively many systems have a system of interactive menus or buttons from which psppire can be started by a series of mouse clicks.

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.