gdata (version 2.18.0)

write.fwf: Write object in fixed width format

Description

write.fwf writes object in *f*ixed *w*idth *f*ormat.

Usage

write.fwf(x, file="", append=FALSE, quote=FALSE, sep=" ", na="",
  rownames=FALSE, colnames=TRUE, rowCol=NULL, justify="left",
  formatInfo=FALSE, quoteInfo=TRUE, width=NULL, eol="\n",
  qmethod=c("escape", "double"),  scientific=TRUE, …)

Arguments

x

data.frame or matrix, the object to be written

file

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="\r\n"' will produce Windows' line endings on a Unix-alike OS, and 'eol="\r"' 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

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

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=TRUE write.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.

See Also

format.info, format, NAToUnknown, write.table, read.fwf, read.table and trim

Examples

# NOT RUN {
  ## 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)
# }