character, name of file or connection, look in
write.table for more
append
logical, append to existing data in file
quote
logical, quote data in output
na
character, the string to use for missing values
i.e. NA in the output
sep
character, separator between columns in output
rownames
logical, print row names
colnames
logical, print column names
rowCol
character, rownames column name
justify
character, alignment of character columns; see
format
formatInfo
logical, return information on number of levels,
widths and format
quoteInfo
logical, should formatInfo account for quotes
width
numeric, width of the columns in the output
eol
the character(s) to print at the end of each line (row).
For example, 'eol="
\n"' will produce Windows' line endings on a
Unix-alike OS, and 'eol="
"' will produce files as expected by Mac
OS Excel 2004.
qmethod
a character string specifying how to deal with embedded
double quote characters when quoting strings. Must be one of
'"escape"' (default), in which case the quote character is
escaped in C style by a backslash, or '"double"', in which
case it is doubled. You can specify just the initial letter.
scientific
logical, if TRUE, allow numeric values to be
formatted using scientific notation.
...
further arguments to
format.info and format
Details
While *F*ixed *w*idth *f*ormat is no longer widely used, it remains
common in some disciplines.
Output is similar to print(x) or format(x). Formatting is
done completely by format on a column basis. Columns in
the output are by default separated with a space i.e. empty column with
a width of one character, but that can be changed with sep
argument as passed to write.table via ....
As mentioned formatting is done completely by
format. Arguments can be passed to format via
... to further modify the output. However, note that the
returned formatInfo might not properly account for this, since
format.info (which is used to collect information about
formatting) lacks the arguments of format.
quote can be used to quote fields in the output. Since all
columns of x are converted to character (via
format) during the output, all columns will be quoted! If
quotes are used, read.table can be easily used to read the
data back into R. Check examples. Do read the details about
quoteInfo argument.
Use only *true* character, i.e., avoid use of tabs, i.e., "\t", or similar
separators via argument sep. Width of the separator is taken as
the number of characters evaluated via nchar(sep).
Use argument na to convert missing/unknown values. Only single value
can be specified. Use NAToUnknown prior to export if you need
greater flexibility.
If rowCol is not NULL and rownames=TRUE, rownames
will also have column name with rowCol value. This is mainly for
flexibility with tools outside R. Note that (at least in R 2.4.0) it
is not "easy" to import data back to R with read.fwf if
you also export rownames. This is the reason, that default is
rownames=FALSE.
Information about format of output will be returned if
formatInfo=TRUE. Returned value is described in value
section. This information is gathered by format.info and
care was taken to handle numeric properly. If output contains rownames,
values account for this. Additionally, if rowCol is not
NULL returned values contain also information about format
of rownames.
If quote=TRUE, the output is of course wider due to
quotes. Return value (with formatInfo=TRUE) can account for this
in two ways; controlled with argument quoteInfo. However, note
that there is no way to properly read the data back to R if
quote=TRUE & quoteInfo=FALSE arguments were used for
export. quoteInfo applies only when quote=TRUE. Assume
that there is a file with quoted data as shown bellow (column numbers in
first three lines are only for demonstration of the values in the
output).
123456789 12345678 # for position
123 1234567 123456 # for width with quoteInfo=TRUE
1 12345 1234 # for width with quoteInfo=FALSE
"a" "hsgdh" " 9"
" " " bb" " 123"
With quoteInfo=TRUEwrite.fwf will return
colname position width
V1 1 3
V2 5 7
V3 13 6
or (with quoteInfo=FALSE)
colname position width
V1 2 1
V2 6 5
V3 14 4
Argument width can be used to increase the width of the columns
in the output. This argument is passed to the width argument of
format function. Values in width are recycled if
there is less values than the number of columns. If the specified width
is to short in comparison to the "width" of the data in particular
column, error is issued.
Value
Besides its effect to write/export data write.fwf can provide
information on format and width. A data.frame is returned with the
following columns:
colname
name of the column
nlevels
number of unique values (unused levels of factors are
dropped), 0 for numeric column
position
starting column number in the output
width
width of the column
digits
number of digits after the decimal point
exp
width of exponent in exponential representation; 0 means
there is no exponential representation, while 1 represents exponent
of length one i.e. 1e+6 and 2 1e+06 or 1e+16
Author(s)
Gregor Gorjanc
See Also
format.info, format,
NAToUnknown, write.table,
read.fwf, read.table and
trim
Examples
## Some data
num <- round(c(733070.345678, 1214213.78765456, 553823.798765678,
1085022.8876545678, 571063.88765456, 606718.3876545678,
1053686.6, 971024.187656, 631193.398765456, 879431.1),
digits=3)
testData <- data.frame(num1=c(1:10, NA),
num2=c(NA, seq(from=1, to=5.5, by=0.5)),
num3=c(NA, num),
int1=c(as.integer(1:4), NA, as.integer(4:9)),
fac1=factor(c(NA, letters[1:9], "hjh")),
fac2=factor(c(letters[6:15], NA)),
cha1=c(letters[17:26], NA),
cha2=c(NA, "longer", letters[25:17]),
stringsAsFactors=FALSE)
levels(testData$fac1) <- c(levels(testData$fac1), "unusedLevel")
testData$Date <- as.Date("1900-1-1")
testData$Date[2] <- NA
testData$POSIXt <- as.POSIXct(strptime("1900-1-1 01:01:01",
format="%Y-%m-%d %H:%M:%S"))
testData$POSIXt[5] <- NA
## Default
write.fwf(x=testData)
## NA should be -
write.fwf(x=testData, na="-")
## NA should be -NA-
write.fwf(x=testData, na="-NA-")
## Some other separator than space
write.fwf(x=testData[, 1:4], sep="-mySep-")
## Force wider columns
write.fwf(x=testData[, 1:5], width=20)
## Show effect of 'scienfic' option
testData$num3 <- testData$num3 * 1e8
write.fwf(testData, scientific=TRUE)
write.fwf(testData, scientific=FALSE)
testData$num3 <- testData$num3 / 1e8
## Write to file and report format and fixed width information
file <- tempfile()
formatInfo <- write.fwf(x=testData, file=file, formatInfo=TRUE)
formatInfo
## Read exported data back to R (note +1 due to separator)
## ... without header
read.fwf(file=file, widths=formatInfo$width + 1, header=FALSE, skip=1,
strip.white=TRUE)
## ... with header - via postimport modfication
tmp <- read.fwf(file=file, widths=formatInfo$width + 1, skip=1,
strip.white=TRUE)
colnames(tmp) <- read.table(file=file, nrow=1, as.is=TRUE)
tmp
## ... with header - persuading read.fwf to accept header properly
## (thanks to Marc Schwartz)
read.fwf(file=file, widths=formatInfo$width + 1, strip.white=TRUE,
skip=1, col.names=read.table(file=file, nrow=1, as.is=TRUE))
## ... with header - with the use of quotes
write.fwf(x=testData, file=file, quote=TRUE)
read.table(file=file, header=TRUE, strip.white=TRUE)
## Tidy up
unlink(file)