GNU PSPP

3.1 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
--table-look=file
-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 format=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.

--table-look=file

Reads a table style from file and applies it to all PSPP table output. The file should be a TableLook .stt or .tlo file. PSPP searches for file in the current directory, then in .pspp/looks in the user’s home directory, then in a looks subdirectory inside PSPP’s data directory (usually /usr/local/share/pspp). If PSPP cannot find file under the given name, it also tries adding a .stt extension.

When this option is not specified, PSPP looks for default.stt using the algorithm above, and otherwise it falls back to a default built-in style.

Using SET TLOOK in PSPP syntax overrides the style set on the command line (see SET).

-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

By default, at startup PSPP searches for a file named rc in the include path (described above) and, if it finds one, runs the commands in it. This option disables this behavior.

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

3.2 PDF, PostScript, SVG, and PNG Output Options

To produce output in PDF, PostScript, SVG, or PNG 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.

PDF, PostScript, and SVG use real units: each dimension among the options listed below may have a 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 above 50 are assumed to be in millimeters.

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.

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 -2 suffix, the third with a -3 suffix, and so on.

-O format={pdf|ps|svg|png}

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

-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

Sets color as the default color for lines and text. Use a CSS color format (e.g. #rrggbb) or name (e.g. black) as color.

-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 object-spacing=dimension

Sets the amount of vertical space between objects (such as headings or tables).

-O prop-font=font-name

Sets the default font used for ordinary text. Most systems support CSS-like font names such as “Sans Serif”, but a wide range of system-specific fonts are likely to be supported as well.

Default: proportional font Sans Serif.

-O font-size=font-size

Sets the size of the default fonts, in thousandths of a point. Default: 10000 (10 point).

-O trim=true

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.

-O outline=boolean

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 -O trim=true 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.)

-O font-resolution=dpi

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 10 / 72 * 96 = 13.3 pixels. Use a larger dpi to enlarge text output, or a smaller dpi to shrink it.

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

-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 width=columns

Width of a page, in columns. If unspecified or given as auto, the default is the width of the terminal, for interactive output, or the WIDTH setting (see SET), for output to a file.

-O box={ascii|unicode}

Sets the characters used for lines in tables. If set to ascii, output uses use the characters ‘-’, ‘|’, and ‘+’ for single-width lines and ‘=’ and ‘#’ for double-width lines. If set to unicode then, output uses Unicode box drawing characters. 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.

3.4 SPV Output Options

SPSS 16 and later write .spv files to represent the contents of its output editor. To produce output in .spv 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=spv

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

-O paper-size=paper-size

-O left-margin=dimension

-O right-margin=dimension

-O top-margin=dimension

-O bottom-margin=dimension

-O object-spacing=dimension

These have the same syntax and meaning as for PDF output. See PDF, PostScript, SVG, and PNG Output Options, for details.

3.5 TeX Output Options

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 -o file on the PSPP command line where file is a file name ending in .tex, or you can specify -O format=tex.

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.

3.6 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 bare=boolean

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 body element. The default value is false.

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

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

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

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

5.1 Preparation of Data Files

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:

• The variables — 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.
• The observations (also called ‘cases’) of the variables — each observation represents an instance when the variables were measured or observed.

For example, a data set which has the variables height, weight, and name, might have the observations:

1881 89.2 Ahmed
1192 107.01 Frank
1230 67 Julie

The following sections explain how to define a dataset.

• Defining Variables
• Listing the data
• Reading data from a text file
• Reading data from a pre-prepared PSPP file
• Saving data to a PSPP file.
• Reading data from other sources
• Exiting PSPP

PSPP> data list list /forename (A12) height.
PSPP> begin data.
data> Ahmed 188
data> Bertram 167
data> Catherine 134.231
data> David 109.1
data> end data
PSPP>

PSPP> list /format=numbered.

Ahmed          188.00
Bertram        167.00
Catherine      134.23
David          109.10
              .
              .
              .
Zachariah      113.02

PSPP> data list file='mydata.dat' list /forename (A12) height.

PSPP> get file='my-file.sav'.

PSPP> save outfile='my-new-file.sav'.

PSPP> finish.

5.2 Data Screening and Transformation

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’s good practice to check for errors.

• Identifying incorrect data
• Dealing with suspicious data
• Inverting negatively coded variables
• Testing data consistency
• Testing for normality

PSPP> get file='/usr/local/share/pspp/examples/physiology.sav'.
PSPP> descriptives sex, weight, height.

PSPP> examine height, weight /statistics=extreme(3).

PSPP> recode height (179 = SYSMIS).
PSPP> recode weight (LOWEST THRU 0 = SYSMIS).

PSPP> get file='/usr/local/share/pspp/examples/hotel.sav'.
PSPP> display dictionary.

recode v3 (1 = 5) (2 = 4) (4 = 2) (5 = 1).

compute var = 6 - var.

PSPP> get file='/usr/local/share/pspp/examples/hotel.sav'.
PSPP> compute v3 = 6 - v3.
PSPP> compute v5 = 6 - v5.
PSPP> reliability v1, v3, v4.

PSPP> get file='/usr/local/share/pspp/examples/repairs.sav'.
PSPP> examine mtbf
                /statistics=descriptives.

PSPP> compute mtbf_ln = ln (mtbf).
PSPP> examine mtbf_ln
                /statistics=descriptives.

compute mtbf_ln = ln (mtbf).

5.3 Hypothesis Testing

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.

The researcher starts by making a null hypothesis. Often this is a hypothesis which he suspects to be false. For example, if he suspects that A is greater than B he will state the null hypothesis as A = B.²

The p-value 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 “the probability of making an error” nor is it the same as “the probability of rejecting a hypothesis when it is true”.

• Testing for differences of means
• Linear Regression

PSPP> get file='/usr/local/share/pspp/examples/physiology.sav'.
PSPP> recode height (179 = SYSMIS).
PSPP> t-test group=sex(0,1) /variables = height temperature.

PSPP> get file='/usr/local/share/pspp/examples/repairs.sav'.
PSPP> regression /variables = mtbf duty_cycle /dependent = mttr.

PSPP> regression /variables = mtbf /dependent = mttr.

6.1 Tokens

PSPP divides most syntax file lines into series of short chunks called tokens. Tokens are then grouped to form commands, each of which tells PSPP to take some action—read in data, write out data, perform a statistical procedure, etc. Each type of token is described below.

Identifiers

Identifiers are names that typically specify variables, commands, or subcommands. The first character in an identifier must be a letter, ‘#’, or ‘@’. The remaining characters in the identifier must be letters, digits, or one of the following special characters:

. _ $ # @

Identifiers may be any length, but only the first 64 bytes are significant. Identifiers are not case-sensitive: foobar, Foobar, FooBar, FOOBAR, and FoObaR are different representations of the same identifier.

Some identifiers are reserved. Reserved identifiers may not be used in any context besides those explicitly described in this manual. The reserved identifiers are:

ALL AND BY EQ GE GT LE LT NE NOT OR TO WITH

Keywords

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: ‘FRE’, ‘FREQ’, and ‘FREQUENCIES’ are equivalent when the last is a keyword.)

Reserved identifiers are always used as keywords. Other identifiers may be used both as keywords and as user-defined identifiers, such as variable names.

Numbers ¶

Numbers are expressed in decimal. A decimal point is optional. Numbers may be expressed in scientific notation by adding ‘e’ and a base-10 exponent, so that ‘1.234e3’ has the value 1234. Here are some more examples of valid numbers:

-5  3.14159265359  1e100  -.707  8945.

Negative numbers are expressed with a ‘-’ prefix. However, in situations where a literal ‘-’ token is expected, what appears to be a negative number is treated as ‘-’ followed by a positive number.

No white space is allowed within a number token, except for horizontal white space between ‘-’ and the rest of the number.

The last example above, ‘8945.’ is interpreted as two tokens, ‘8945’ and ‘.’, if it is the last token on a line. See Forming commands of tokens.

Strings ¶

Strings are literal sequences of characters enclosed in pairs of single quotes (‘'’) or double quotes (‘"’). To include the character used for quoting in the string, double it, e.g. ‘'it''s an apostrophe'’. White space and case of letters are significant inside strings.

Strings can be concatenated using ‘+’, so that ‘"a" + 'b' + 'c'’ is equivalent to ‘'abc'’. So that a long string may be broken across lines, a line break may precede or follow, or both precede and follow, the ‘+’. (However, an entirely blank line preceding or following the ‘+’ is interpreted as ending the current command.)

Strings may also be expressed as hexadecimal character values by prefixing the initial quote character by ‘x’ or ‘X’. Regardless of the syntax file or active dataset’s encoding, the hexadecimal digits in the string are interpreted as Unicode characters in UTF-8 encoding.

Individual Unicode code points may also be expressed by specifying the hexadecimal code point number in single or double quotes preceded by ‘u’ or ‘U’. For example, Unicode code point U+1D11E, the musical G clef character, could be expressed as U'1D11E'. Invalid Unicode code points (above U+10FFFF or in between U+D800 and U+DFFF) are not allowed.

When strings are concatenated with ‘+’, each segment’s prefix is considered individually. For example, 'The G clef symbol is:' + u"1d11e" + "." inserts a G clef symbol in the middle of an otherwise plain text string.

Punctuators and Operators ¶

These tokens are the punctuators and operators:

, / = ( ) + - * / ** < <= <> > >= ~= & | .

Most of these appear within the syntax of commands, but the period (‘.’) 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, e.g., an identifier or a floating-point number.

6.2 Forming commands of tokens

Most PSPP commands share a common structure. A command begins with a command name, such as FREQUENCIES, DATA LIST, or N OF CASES. 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.

The command name may be followed by one or more subcommands. 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 (‘=’). 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 (‘/’).

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 (‘.’) as described in the previous section (see Tokens). A blank line, or one that consists only of white space or comments, also ends a command.

6.3 Syntax Variants

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.

In interactive mode, 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.

In batch mode, 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.

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.

The default mode for reading commands from a file is auto mode. 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.

The --interactive (or -i) or --batch (or -b) options set the syntax mode for files listed on the PSPP command line. See Main Options, for more details.

6.4 Types of Commands

Commands in PSPP are divided roughly into six categories:

Utility commands ¶

Set or display various global options that affect PSPP operations. May appear anywhere in a syntax file. See Utility commands.

File definition commands ¶

Give instructions for reading data from text files or from special binary “system files”. 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 Data Input and Output.

Input program commands ¶

Though rarely used, these provide tools for reading data files in arbitrary textual or binary formats. See INPUT PROGRAM.

Transformations ¶

Perform operations on data and write data to output files. Transformations are not carried out until a procedure is executed.

Restricted transformations ¶

Transformations that cannot appear in certain contexts. See Order of Commands, for details.

Procedures ¶

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 procedure is any command that causes the active dataset (the data) to be read.

6.5 Order of Commands

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.

PSPP possesses five internal states, called initial, input-program file-type, transformation, and procedure states. (Please note the distinction between the INPUT PROGRAM and FILE TYPE commands and the input-program and file-type states.)

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:

Utility commands

• Valid in any state.
• Do not cause state transitions. Exception: when N OF CASES is executed in the procedure state, it causes a transition to the transformation state.

DATA LIST

• Valid in any state.
• When executed in the initial or procedure state, causes a transition to the transformation state.
• Clears the active dataset if executed in the procedure or transformation state.

INPUT PROGRAM

• Invalid in input-program and file-type states.
• Causes a transition to the intput-program state.
• Clears the active dataset.

FILE TYPE

• Invalid in intput-program and file-type states.
• Causes a transition to the file-type state.
• Clears the active dataset.

Other file definition commands

• Invalid in input-program and file-type states.
• Cause a transition to the transformation state.
• Clear the active dataset, except for ADD FILES, MATCH FILES, and UPDATE.

Transformations

• Invalid in initial and file-type states.
• Cause a transition to the transformation state.

Restricted transformations

• Invalid in initial, input-program, and file-type states.
• Cause a transition to the transformation state.

Procedures

• Invalid in initial, input-program, and file-type states.
• Cause a transition to the procedure state.

6.6 Handling missing observations

PSPP includes special support for unknown numeric data values. Missing observations are assigned a special value, called the system-missing value. This “value” 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.

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.

Variables, whether numeric or string, can have designated user-missing values. 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.

For more information on missing values, see the following sections: Datasets, MISSING VALUES, Mathematical Expressions. See also the documentation on individual procedures for information on how they handle missing values.

6.7 Datasets

PSPP works with data organized into datasets. A dataset consists of a set of variables, which taken together are said to form a dictionary, and one or more cases, each of which has one value for each variable.

At any given time PSPP has exactly one distinguished dataset, called the active dataset. 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 DATASET commands can choose a new active dataset from among those that are open, as well as create and destroy datasets (see DATASET commands).

The sections below describe variables in more detail.

• Attributes of Variables
• Variables Automatically Defined by PSPP
• Lists of variable names
• Input and Output Formats
• Scratch Variables

SET CCx="string".

SET CCA="-,,,".  /* Same as COMMA.
SET CCB="-...".  /* Same as DOT.
SET CCC="-,$,,". /* Same as DOLLAR.
SET CCD="-,,%,". /* Like PCT, but groups with commas.

SET CCA=",EUR,,-".   /* Euro.
SET CCB="(,USD ,,)". /* US dollar.
SET CCC="-.R$..".    /* Brazilian real.
SET CCD="-,, NIS,".  /* Israel shekel.
SET CCE="-.Rp'. ..". /* Indonesia Rupiah.

0123456789
{ABCDEFGHI
}JKLMNOPQR

6.8 Files Used by PSPP

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:

command file

syntax file

These names (synonyms) refer to the file that contains instructions that tell PSPP what to do. The syntax file’s name is specified on the PSPP command line. Syntax files can also be read with INCLUDE (see INCLUDE).

data file

Data files contain raw data in text or binary format. Data can also be embedded in a syntax file with BEGIN DATA and END DATA.

listing file

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.

system file

System files are binary files that store a dictionary and a set of cases. GET and SAVE read and write system files.

portable file

Portable files are files in a text-based format that store a dictionary and a set of cases. IMPORT and EXPORT read and write portable files.

6.9 File Handles

A file handle 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 ‘'’ or ‘"’.

A file name string that begins or ends with ‘|’ 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 ‘curl’ (e.g. GET '|curl -s -S http://example.com/mydata.sav'), to read compressed data from a file using a program such as ‘zcat’ (e.g. GET '|zcat mydata.sav.gz'), and for many other purposes.

PSPP also supports declaring named file handles with the FILE HANDLE command. This command associates an identifier of your choice (the file handle’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 FILE HANDLE is also required to read data files in binary formats. See FILE HANDLE, for more information.

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, e.g. as an input file for GET or MATCH FILES, PSPP uses the file’s contents to decide. In the context of writing a file, e.g. as an output file for SAVE or AGGREGATE, PSPP decides based on the file’s name: if it ends in ‘.por’ (with any capitalization), then PSPP writes a portable file; otherwise, PSPP writes a system file.

INLINE is reserved as a file handle name. It refers to the “data file” embedded into the syntax file between BEGIN DATA and END DATA. See BEGIN DATA, for more information.

The file to which a file handle refers may be reassigned on a later FILE HANDLE command if it is first closed using CLOSE FILE HANDLE. See CLOSE FILE HANDLE, for more information.

6.10 Backus-Naur Form

The syntax of some parts of the PSPP language is presented in this manual using the formalism known as Backus-Naur Form, or BNF. The following table describes BNF:

• Words in all-uppercase are PSPP keyword tokens. In BNF, these are often called terminals. There are some special terminals, which are written in lowercase for clarity:

  number

  A real number.

  integer

  An integer number.

  string

  A string.

  var-name

  A single variable name.

  =, /, +, -, etc.

  Operators and punctuators.

  .

  The end of the command. This is not necessarily an actual dot in the syntax file (see Forming commands of tokens).

• Other words in all lowercase refer to BNF definitions, called productions. These productions are also known as nonterminals. Some nonterminals are very common, so they are defined here in English for clarity:

  var-list

  A list of one or more variable names or the keyword ALL.

  expression

  An expression. See Mathematical Expressions, for details.

• ‘::=’ means “is defined as”. The left side of ‘::=’ gives the name of the nonterminal being defined. The right side of ‘::=’ 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 production.
• So, the key difference between a terminal and a nonterminal is that a terminal cannot be broken into smaller parts—in fact, every terminal is a single token (see Tokens). 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.)
• The first nonterminal defined in a set of productions is called the start symbol. The start symbol defines the entire syntax for that command.

7.1 Boolean Values

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.

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.

Strings and Booleans are not compatible, and neither may be used in place of the other.

7.2 Missing Values in Expressions

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.

String user-missing values are not treated specially in expressions.

User-missing values for numeric variables are always transformed into the system-missing value, except inside the arguments to the VALUE and SYSMIS functions.

The missing-value functions can be used to precisely control how missing values are treated in expressions. See Missing-Value Functions, for more details.

7.3 Grouping Operators

Parentheses (‘()’) are the grouping operators. Surround an expression with parentheses to force early evaluation.

Parentheses also surround the arguments to functions, but in that situation they act as punctuators, not as operators.

7.4 Arithmetic Operators

The arithmetic operators take numeric operands and produce numeric results.

a + b

Yields the sum of a and b.

a - b

Subtracts b from a and yields the difference.

a * b

Yields the product of a and b. If either a or b is 0, then the result is 0, even if the other operand is missing.

a / b

Divides a by b and yields the quotient. If a is 0, then the result is 0, even if b is missing. If b is zero, the result is system-missing.

a ** b

Yields the result of raising a to the power b. If a is negative and b is not an integer, the result is system-missing. The result of 0**0 is system-missing as well.

- a

Reverses the sign of a.

7.5 Logical Operators

The logical operators take logical operands and produce logical results, meaning “true or false.” Logical operators are not true Boolean operators because they may also result in a system-missing value. See Boolean Values, for more information.

a AND b

a & b

True if both a and b 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.

a OR b

a | b

True if at least one of a and b 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.

NOT a

~ a

True if a is false. If the operand is missing, then the result is missing.

7.6 Relational Operators

The relational operators take numeric or string operands and produce Boolean results.

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.

The results of string comparisons, other than tests for equality or inequality, depend on the character set in use. String comparisons are case-sensitive.

a EQ b

a = b

True if a is equal to b.

a LE b

a <= b

True if a is less than or equal to b.

a LT b

a < b

True if a is less than b.

a GE b

a >= b

True if a is greater than or equal to b.

a GT b

a > b

True if a is greater than b.

a NE b

a ~= b

a <> b

True if a is not equal to b.

7.7 Functions

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.

Function names are not reserved. Their names are specially treated only when followed by a left parenthesis, so that ‘EXP(10)’ refers to the constant value e raised to the 10th power, but ‘EXP’ by itself refers to the value of a variable called EXP.

The sections below describe each function in detail.

• Mathematical Functions
• Miscellaneous Mathematical Functions
• Trigonometric Functions
• Missing-Value Functions
• Set-Membership Functions
• Statistical Functions
• String Functions
• Time & Date Functions
• Miscellaneous Functions
• Statistical Distribution Functions

          10 minutes                        600
          1 hour                          3,600
          1 day, 3 hours, 10 seconds     97,210
          40 days                     3,456,000

              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

7.8 Operator Precedence

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 ‘-’ represents unary negation, the second binary subtraction.

1. ()
2. **
3. -
4. * /
5. + -
6. = >= > <= < <>
7. NOT
8. AND
9. OR

8.1 BEGIN DATA

BEGIN DATA.
…
END DATA.

BEGIN DATA and END DATA can be used to embed raw ASCII data in a PSPP syntax file. DATA LIST or another input procedure must be used before BEGIN DATA (see DATA LIST). BEGIN DATA and END DATA must be used together. END DATA must appear by itself on a single line, with no leading white space and exactly one space between the words END and DATA, like this:

END DATA.

8.2 CLOSE FILE HANDLE

CLOSE FILE HANDLE handle_name.

CLOSE FILE HANDLE disassociates the name of a file handle with a given file. The only specification is the name of the handle to close. Afterward FILE HANDLE.

The file named INLINE, which represents data entered between BEGIN DATA and END DATA, cannot be closed. Attempts to close it with CLOSE FILE HANDLE have no effect.

CLOSE FILE HANDLE is a PSPP extension.

8.3 DATAFILE ATTRIBUTE

DATAFILE ATTRIBUTE
         ATTRIBUTE=name(’value’) [name(’value’)]…
         ATTRIBUTE=name[index](’value’) [name[index](’value’)]…
         DELETE=name [name]…
         DELETE=name[index] [name[index]]…

DATAFILE ATTRIBUTE 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.

Use the ATTRIBUTE subcommand to add or modify a custom data file attribute. Specify the name of the attribute as an identifier (see Tokens), followed by the desired value, in parentheses, as a quoted string. Attribute names that begin with $ are reserved for PSPP’s internal use, and attribute names that begin with @ or $@ are not displayed by most PSPP commands that display other attributes. Other attribute names are not treated specially.

Attributes may also be organized into arrays. To assign to an array element, add an integer array index enclosed in square brackets ([ and ]) 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.

Use the DELETE 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.

To associate custom attributes with particular variables, instead of with the entire active dataset, use VARIABLE ATTRIBUTE (see VARIABLE ATTRIBUTE) instead.

DATAFILE ATTRIBUTE takes effect immediately. It is not affected by conditional and looping structures such as DO IF or LOOP.

8.4 DATASET commands

DATASET NAME name [WINDOW={ASIS,FRONT}].
DATASET ACTIVATE name [WINDOW={ASIS,FRONT}].
DATASET COPY name [WINDOW={MINIMIZED,HIDDEN,FRONT}].
DATASET DECLARE name [WINDOW={MINIMIZED,HIDDEN,FRONT}].
DATASET CLOSE {name,*,ALL}.
DATASET DISPLAY.

The DATASET 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.

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.

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 EXECUTE had been specified. If the active dataset is unnamed before switching, then it is deleted and becomes unavailable after switching.

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

The DATASET DECLARE command creates a new dataset that is initially “empty,” 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, e.g. AGGREGATE (see AGGREGATE).

The DATASET CLOSE command deletes a dataset. If the active dataset is specified by name, or if ‘*’ 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.

The DATASET DISPLAY command lists all the currently defined datasets.

Many DATASET commands accept an optional WINDOW subcommand. In the PSPPIRE GUI, the value given for this subcommand influences how the dataset’s window is displayed. Outside the GUI, the WINDOW subcommand has no effect. The valid values are:

ASIS

Do not change how the window is displayed. This is the default for DATASET NAME and DATASET ACTIVATE.

FRONT

Raise the dataset’s window to the top. Make it the default dataset for running syntax.

MINIMIZED

Display the window “minimized” to an icon. Prefer other datasets for running syntax. This is the default for DATASET COPY and DATASET DECLARE.

HIDDEN

Hide the dataset’s window. Prefer other datasets for running syntax.

8.5 DATA LIST

Used to read text or binary data, DATA LIST is the most fundamental data-reading command. Even the more sophisticated input methods use DATA LIST commands as a building block. Understanding DATA LIST is important to understanding how to use PSPP to read your data files.

There are two major variants of DATA LIST, 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.

Each form of DATA LIST is described in detail below.

See GET DATA, for a command that offers a few enhancements over DATA LIST and that may be substituted for DATA LIST in many situations.

• DATA LIST FIXED
• DATA LIST FREE
• DATA LIST LIST

DATA LIST [FIXED]
        {TABLE,NOTABLE}
        [FILE=’file_name’ [ENCODING=’encoding’]]
        [RECORDS=record_count]
        [END=end_var]
        [SKIP=record_count]
        /[line_no] var_spec…

where each var_spec takes one of the forms
        var_list start-end [type_spec]
        var_list (fortran_spec)