dplR (version 1.8.0)

write.sheet: Write Ring Widths to a Spreadsheet File

Description

Write a ring width object to a file in “spreadsheet” layout: years down the rows, series across the columns, and the years in the first column.

Usage

write.sheet(rwl.df, fname, sep = ",", dec = ".",
            layout = c("wide", "long"), prec = NULL, na.string = "",
            year.name = "Year")

Value

The function returns fname, the name of the file written.

Arguments

rwl.df

a data.frame of ring widths with the series in columns and the years as row names, as returned by read.rwl.

fname

a character vector giving the file name to write.

sep

the field separator, a single character.

dec

the decimal mark, "." or ",". May not be the same character as sep.

layout

the shape to write. "wide", the default, is years down the rows and series across the columns. "long" is a “long” or “tidy” file of series, year, value triples. Note that this is unrelated to the long argument of read.crn and read.tucson, which refers to a wider fixed-width year field.

prec

the precision to write, in mm, or NULL to take it from the object. Unlike write.tucson this is not restricted to 0.01 and 0.001.

na.string

character string written for a missing value. The default is an empty cell.

year.name

character string used as the header of the first column.

Author

Andy Bunn

Details

The file is written in the layout that read.sheet reads: a header row of the year column's name followed by the series IDs, then one row per year.

Precision

prec controls how many decimal places are written. Left at NULL it is taken from the "dplR.provenance" attribute that read.sheet and read.tucson attach to the objects they return, and failing that it is inferred from the data. This is what keeps a width read at 0.001 mm from being written back as 0.5670000000000001.

A precision that was derived rather than given is checked against the data before it is used, and if rounding there would discard real digits the file is written at full precision with a warning instead. A precision passed explicitly is an instruction and is obeyed, so prec = 0.1 rounds.

Trailing zeros are kept: at prec = 0.001 a width of 0.51 is written as 0.510.

Long format

With layout = "long" the file holds one row per observation --- the series ID, the year and the value --- with missing values left out. Rows are written one series at a time, years ascending within a series. year.name names the year column here too.

A year in which every series is NA has no rows. An interior such year still survives a round trip, because read.sheet rebuilds the span from the earliest and latest year in the file and the year reappears as a row of NA in its original place. A leading or trailing one has nothing outside it to pin the span and is lost; write.sheet warns when it writes a file in that state. Write with layout = "wide" to keep those years.

A ring width of zero is a locally absent ring and is written as a zero. A missing value is written as na.string. The two are different statements about a tree in a year and are never written the same way.

Series IDs are written verbatim. An ID containing the separator, a double quote or a line break is quoted using the usual comma-separated-value escape.

See Also

read.sheet, write.rwl, write.tucson

Examples

library(utils)
data(ca533)
tmpName <- tempfile(fileext = ".csv")

# write and read back
write.sheet(ca533, tmpName)
bar <- read.sheet(tmpName, verbose = FALSE)

# the data survives the round trip unchanged. Provenance describes the file an
# object was read from, so it is dropped from both sides before comparing.
no.prov <- function(x) { attr(x, "dplR.provenance") <- NULL; x }
identical(no.prov(ca533), no.prov(bar))

unlink(tmpName)