Package 'Foreign'

Package ‘foreign’

March 19, 2013

Priority recommended

Version 0.8-53

Date 2013-03-20

Title Read Data Stored by Minitab, S, SAS, SPSS, Stata, Systat, dBase,...

Depends R (>= 2.14.0), stats

Imports methods, utils

Description Functions for reading and writing data stored by statistical pack- ages such as Minitab, S, SAS, SPSS, Stata,Systat, ..., and for reading and writing dBase ﬁles.

ByteCompile yes

Biarch yes

License GPL (>= 2)

BugReports http://bugs.r-project.org

Author R Core Team [aut, cph, cre], Roger Bivand [ctb, cph], Vincent J. Carey [ctb, cph], Saikat DebRoy [ctb, cph], Stephen Eglen [ctb, cph], Rajarshi Guha [ctb, cph], Nicholas Lewin- Koh [ctb,cph], Mark Myatt [ctb, cph], Ben Pfaff [ctb], Frank Warmerdam [ctb, cph], Stephen Weigand [ctb, cph], Free Software Foundation, Inc. [cph]

Maintainer R Core Team

NeedsCompilation yes

Repository CRAN

Date/Publication 2013-03-19 12:52:56

1 2 lookup.xport

R topics documented:

lookup.xport ...... 2 read.arff ...... 3 read.dbf ...... 4 read.dta ...... 5 read.epiinfo ...... 6 read.mtp ...... 8 read.octave ...... 9 read.spss ...... 10 read.ssd ...... 12 read.systat ...... 13 read.xport ...... 15 S3 read functions ...... 16 write.arff ...... 17 write.dbf ...... 18 write.dta ...... 19 write.foreign ...... 21

Index 23

lookup.xport Lookup Information on a SAS XPORT Format Library

Description Scans a ﬁle as a SAS XPORT format library and returns a list containing information about the SAS library.

Usage lookup.xport(file)

Arguments file character variable with the name of the ﬁle to read. The ﬁle must be in SAS XPORT format.

Value A list with one component for each dataset in the XPORT format library.

Author(s) Saikat DebRoy read.arff 3

References SAS Technical Support document TS-140: “The Record Layout of a Data Set in SAS Transport (XPORT) Format” available as http://ftp.sas.com/techsup/download/technote/ts140.html.

See Also DateTimeClasses

Examples ## Not run: data<-read.epiinfo("oswego.rec",guess.broken.dates=TRUE,thisyear="1972")

## End(Not run) 8 read.mtp

read.mtp Read a Minitab Portable Worksheet

Description

Return a list with the data stored in a ﬁle as a Minitab Portable Worksheet.

Usage

read.mtp(file)

Arguments

file character variable with the name of the ﬁle to read. The ﬁle must be in Minitab Portable Worksheet format.

Value

A list with one component for each column, matrix, or constant stored in the Minitab worksheet.

Note

This function was written around 1990 for the format current then. Later versions of Minitab appear to have added to the format.

Author(s)

Douglas M. Bates

References

http://www.minitab.com/

Examples

## Not run: read.mtp("ex1-10.mtp")

## End(Not run) read.octave 9

read.octave Read Octave Text Data Files

Description

Read a ﬁle in Octave text data format into a list.

Usage

read.octave(file)

Arguments

file a character string with the name of the ﬁle to read.

Details

This function is used to read in files in Octave text data format, as created by save -text in Octave. It knows about most of the common types of variables, including the standard atomic (real and complex scalars, matrices, and N-d arrays, strings, ranges, and boolean scalars and matrices) and recursive (structs, cells, and lists) ones, but has no guarantee to read all types. If a type is not recognized, a warning indicating the unknown type is issued, it is attempted to skip the unknown entry, and NULL is used as its value. Note that this will give incorrect results, and maybe even errors, in the case of unknown recursive data types. As Octave can read MATLAB binary files, one can make the contents of such files available to R by using Octave’s load and save (as text) facilities as an intermediary step.

Value

A list with one named component for each variable in the ﬁle.

Author(s)

Stephen Eglen and Kurt Hornik

References

http://www.octave.org/ 10 read.spss

read.spss Read an SPSS Data File

Description read.spss reads a ﬁle stored by the SPSS save or export commands.

Usage read.spss(file, use.value.labels = TRUE, to.data.frame = FALSE, max.value.labels = Inf, trim.factor.names = FALSE, trim_values = TRUE, reencode = NA, use.missings = to.data.frame)

Arguments file Character string: the name of the file or URL to read. use.value.labels Convert variables with value labels into R factors with those levels? to.data.frame return a data frame? max.value.labels Only variables with value labels and at most this many unique values will be converted to factors if use.value.labels = TRUE. trim.factor.names Logical: trim trailing spaces from factor levels? trim_values logical: should values and value labels have trailing spaces ignored when matching for use.value.labels = TRUE? reencode logical: should character strings be re-encoded to the current locale. The default, NA, means to do so in a UTF-8 locale, only. Alternatively a character string specifying an encoding to assume for the file. use.missings logical: should information on user-defined missing values be used to set the corresponding values to NA?

Details This uses modified code from the PSPP project (http://www.gnu.org/software/pspp/ for reading the SPSS formats. If the filename appears to be a URL (of schemes ‘http:’, ‘ftp:’ or ‘https:’) the URL is first downloaded to a temporary file and then read. (‘https:’ is only supported on some platforms.) Occasionally in SPSS, value labels will be added to some values of a continuous variable (e.g. to distinguish different types of missing data), and you will not want these variables converted to factors. By setting max.value.labels you can specify that variables with a large number of distinct values are not converted to factors even if they have value labels. In addition, variables will not be converted to factors if there are non-missing values that have no value label. The value labels are then returned in the "value.labels" attribute of the variable. read.spss 11

If SPSS variable labels are present, they are returned as the "variable.labels" attribute of the answer. Fixed length strings (including value labels) are padded on the right with spaces by SPSS, and so are read that way by R. The default argument trim_values=TRUE causes trailing spaces to be ignored when matching to value labels, as examples have been seen where the strings and the value labels had different amounts of padding. See the examples for sub for ways to remove trailing spaces in character data. URL http://msdn.microsoft.com/en-us/library/ms776446(VS.85).aspx provides a list of translations from Windows codepage numbers to encoding names that iconv is likely to know about and so suitable values for reencode. Automatic re-encoding is attempted for apparent codepages of 200 or more in a UTF-8 locale: some other high-numbered codepages can be re-encoded on most systems, but the encoding names are platform-dependent (see iconvlist).

Value

A list (or data frame) with one component for each variable in the saved data set. If what looks like a Windows codepage was recorded in the SPSS file, it is attached (as a number) as attribute "codepage" to the result. There may be attributes "label.table" and "variable.labels". Attribute "label.table" is a named list of value labels with one element per variable, either NULL or a named character vector. Attribute "variable.labels" is a named character vector with names the short variable names and elements the long names. If there are user-defined missing values, there will be a attribute "Missings". This is a named list with one list element per variable. Each element has an element type, a length-one character vector giving the type of missingness, and may also have an element value with the values corresponding to missingness. This is a complex subject (where the R and C source code for read.spss is the main documentation), but the simplest cases are types "one", "two" and "three" with a corresponding number of (real or string) values whose labels can be found from the "label.table" attribute. Other possibilities are a finite or semi-infinite range, possibly plus a single value. See also http:// www.gnu.org/software/pspp/manual/html_node/Missing-Observations.html#Missing-Observations.

Note

If SPSS value labels are converted to factors the underlying numerical codes will not in general be the same as the SPSS numerical values, since the numerical codes in R are always 1, 2, 3,.... You may see warnings about the file encoding for SPSS save files: it is possible such files con- tain non-ASCII character data which need re-encoding. The most common occurrence is Win- dows codepage 1252, a superset of Latin-1. The encoding is recorded (as an integer) in attribute "codepage" of the result if it looks like a Windows codepage. Automatic re-encoding is done only in UTF-8 locales: see argument reencode.

Author(s)

Saikat DebRoy and the R-core team 12 read.ssd

See Also A different interface also based on the PSPP codebase is available in package memisc: see its help for spss.system.file.

Examples ## Not run: read.spss("datafile") ## don’t convert value labels to factor levels read.spss("datafile", use.value.labels = FALSE) ## convert value labels to factors for variables with at most ## ten distinct values. read.spss("datafile", max.value.labels = 10)

## End(Not run)

read.ssd Obtain a Data Frame from a SAS Permanent Dataset, via read.xport

Description Generates a SAS program to convert the ssd contents to SAS transport format and then uses read.xport to obtain a data frame.

Usage read.ssd(libname, sectionnames, tmpXport=tempfile(), tmpProgLoc=tempfile(), sascmd="sas")

Arguments libname character string defining the SAS library (usually a directory reference) sectionnames character vector giving member names. These are files in the libname directory. They will usually have a .ssd0x or .sas7bdat extension, which should be omitted. tmpXport character string: location where temporary xport format archive should reside – defaults to a randomly named file in the session temporary directory, which will be removed. tmpProgLoc character string: location where temporary conversion SAS program should reside – defaults to a randomly named file in session temporary directory, which will be removed on successful operation. sascmd character string giving full path to SAS executable.

Details Creates a SAS program and runs it. Error handling is primitive. read.systat 13

Value A data frame if all goes well, or NULL with warnings and some enduring side effects (log ﬁle for auditing)

Note This requires SAS to be available. If you have a SAS dataset without access to SAS you will need another product to convert it to a format such as .csv, for example ‘Stat/Transfer’ or ‘DBMS/Copy’ or the ‘SAS System Viewer’ (Windows only).

Author(s) For Unix: VJ Carey