XLConnect (version 0.2-2)

readNamedRegion: Reading named regions from a workbook

Description

Reads named regions from a workbook.

Usage

## S3 method for class 'workbook':
readNamedRegion(object, name, header, rownames, colTypes, forceConversion, dateTimeFormat, check.names)

Arguments

object

The workbook to use

name

The name of the named region to read

header

The argument header specifies if the first row should be interpreted as column names. The default value is TRUE.

rownames

Index (numeric) or name (character) of column that should be used as row names. The corresponding column will be removed from the data set. Defaults to NULL which means that no row names are applied.

colTypes

Column types to use when reading in the data. Specified as a character vector of the corresponding type names (see XLC; XLC$DATA_TYPE.). You may also use R class names such as

forceConversion

logical specifying if conversions to less generic types should be forced. Defaults to FALSE meaning that if a column is specified to be of a certain type via the colTypes argument and a more generic type is det

dateTimeFormat

Date/time format used when doing date/time conversions. Defaults to getOption("XLConnect.dateTimeFormat"). This should be a POSIX format specifier according to strptime although not all spe

check.names

logical specifying if column names of the resulting data.frame should be checked to ensure that they are syntactically valid valid variable names and are not duplicated. See the check.names argument of

Details

The arguments name and header are vectorized. As such, multiple named regions can be read with one method call. If only one single named region is read, the return value is a data.frame.If multiple named regions are specified, the return value is a (named) list of data.frame's returned in the order they have been specified with the argument name.

References

What are named regions/ranges? http://www.officearticles.com/excel/named_ranges_in_microsoft_excel.htm How to create named regions/ranges? http://www.youtube.com/watch?v=iAE9a0uRtpM

See Also

workbook, readWorksheet, writeNamedRegion, writeWorksheet, readNamedRegionFromFile, onErrorCell

Examples

## Example 1:
# mtcars xlsx file from demoFiles subfolder of package XLConnect
demoExcelFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect")

# Load workbook
wb <- loadWorkbook(demoExcelFile)

# Read named region 'mtcars' (with default header = TRUE)
data <- readNamedRegion(wb, name = "mtcars")

## Example 2;
# conversion xlsx file from demoFiles subfolder of package XLConnect
excelFile <- system.file("demoFiles/conversion.xlsx", package = "XLConnect")

# Load workbook
wb <- loadWorkbook(excelFile)

# Read named region 'conversion' with pre-specified column types
# Note: in the worksheet all data was entered as strings!
# forceConversion = TRUE is used to force conversion from String
# into the less generic data types Numeric, DateTime & Boolean
df <- readNamedRegion(wb, name = "conversion", header = TRUE,
                      colTypes = c(XLC$DATA_TYPE.NUMERIC,
                                   XLC$DATA_TYPE.DATETIME,
                                   XLC$DATA_TYPE.BOOLEAN),
                      forceConversion = TRUE,
                      dateTimeFormat = "%Y-%m-%d %H:%M:%S")