Package XLConnect

March 18, 2013

Type Package Title Excel Connector for R Version 0.2-5 Date 2013-03-18 Author Mirai Solutions GmbH Maintainer Martin Studer <[email protected]> URL http://www.mirai-solutions.com ,http://miraisolutions.wordpress.com SystemRequirements java (>= 1.6) Depends R (>= 2.10.0), rJava, utils, methods Suggests RUnit, lattice, ggplot2 (>= 0.9.3), fImport, forecast, zoo,scales Description Manipulate Excel les from R License GPL-3 LazyLoad yes NeedsCompilation no Repository CRAN Date/Publication 2013-03-18 21:35:23

R topics documented:
XLConnect-package . . . . . addImage-methods . . . . . . appendNamedRegion-methods appendWorksheet-methods . . aref . . . . . . . . . . . . . . aref2idx . . . . . . . . . . . . cellstyle-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 . 5 . 6 . 8 . 9 . 10 . 10

2 clearNamedRegion-methods . . . . . . clearRange-methods . . . . . . . . . . clearRangeFromReference-methods . . clearSheet-methods . . . . . . . . . . . cloneSheet-methods . . . . . . . . . . . col2idx . . . . . . . . . . . . . . . . . createCellStyle-methods . . . . . . . . createFreezePane-methods . . . . . . . createName-methods . . . . . . . . . . createSheet-methods . . . . . . . . . . createSplitPane-methods . . . . . . . . cref2idx . . . . . . . . . . . . . . . . . existsName-methods . . . . . . . . . . existsSheet-methods . . . . . . . . . . extraction-methods . . . . . . . . . . . extractSheetName . . . . . . . . . . . . getActiveSheetIndex-methods . . . . . getActiveSheetName-methods . . . . . getBoundingBox-methods . . . . . . . getCellFormula-methods . . . . . . . . getCellStyle-methods . . . . . . . . . . getDenedNames-methods . . . . . . . getForceFormulaRecalculation-methods getLastColumn-methods . . . . . . . . getLastRow-methods . . . . . . . . . . getReferenceCoordinates-methods . . . getReferenceFormula-methods . . . . . getSheetPos-methods . . . . . . . . . . getSheets-methods . . . . . . . . . . . hideSheet-methods . . . . . . . . . . . idx2aref . . . . . . . . . . . . . . . . . idx2col . . . . . . . . . . . . . . . . . idx2cref . . . . . . . . . . . . . . . . . isSheetHidden-methods . . . . . . . . . isSheetVeryHidden-methods . . . . . . isSheetVisible-methods . . . . . . . . . loadWorkbook . . . . . . . . . . . . . . mergeCells-methods . . . . . . . . . . mirai . . . . . . . . . . . . . . . . . . . onErrorCell-methods . . . . . . . . . . print-methods . . . . . . . . . . . . . . readNamedRegion . . . . . . . . . . . readNamedRegionFromFile . . . . . . readWorksheet-methods . . . . . . . . . readWorksheetFromFile . . . . . . . . . removeName-methods . . . . . . . . . removePane-methods . . . . . . . . . . removeSheet-methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

R topics documented: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 13 15 16 17 18 18 20 21 23 24 25 26 27 28 29 30 31 31 33 34 35 36 37 38 39 40 41 42 42 44 45 45 46 47 49 50 51 52 53 54 55 58 59 63 65 66 67

R topics documented: renameSheet-methods . . . . . . . . . . runUnitTests . . . . . . . . . . . . . . . saveWorkbook-methods . . . . . . . . . setActiveSheet-methods . . . . . . . . . setAutoFilter-methods . . . . . . . . . setBorder-methods . . . . . . . . . . . setCellFormula-methods . . . . . . . . setCellStyle-methods . . . . . . . . . . setColumnWidth-methods . . . . . . . setDataFormat-methods . . . . . . . . . setDataFormatForType-methods . . . . setFillBackgroundColor-methods . . . . setFillForegroundColor-methods . . . . setFillPattern-methods . . . . . . . . . setForceFormulaRecalculation-methods setMissingValue-methods . . . . . . . . setRowHeight-methods . . . . . . . . . setSheetColor-methods . . . . . . . . . setSheetPos-methods . . . . . . . . . . setStyleAction-methods . . . . . . . . . setStyleNamePrex-methods . . . . . . setWrapText-methods . . . . . . . . . . show-methods . . . . . . . . . . . . . . summary-methods . . . . . . . . . . . . unhideSheet-methods . . . . . . . . . . unmergeCells-methods . . . . . . . . . workbook-class . . . . . . . . . . . . . writeNamedRegion-methods . . . . . . writeNamedRegionToFile . . . . . . . . writeWorksheet-methods . . . . . . . . writeWorksheetToFile . . . . . . . . . . XLC . . . . . . . . . . . . . . . . . . . xlcDump . . . . . . . . . . . . . . . . xlcEdit . . . . . . . . . . . . . . . . . . xlcFreeMemory . . . . . . . . . . . . . xlcMemoryReport . . . . . . . . . . . . xlcRestore . . . . . . . . . . . . . . . . $-methods . . . . . . . . . . . . . . . . Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3 68 69 70 71 72 73 74 76 78 79 80 81 82 84 85 86 87 88 89 90 93 94 95 96 97 98 99 100 102 103 104 105 108 109 110 111 112 113 114

XLConnect-package

XLConnect-package

Excel Connector for R

Description Manipulate Excel les from R Details Package: Type: Version: Date: URL: SystemRequirements: Depends: Suggests: License: LazyLoad: XLConnect Package 0.2-5 2013-03-18 http://www.mirai-solutions.com http://miraisolutions.wordpress.com java (>= 6.0) R (>= 2.10.0), rJava, utils, methods RUnit, lattice, ggplot2 (>= 0.9.3), fImport, forecast, zoo, scales GPL-3 yes

For an overview over the package please refer to the available demos: demo(package = "XLConnect") Author(s) Mirai Solutions GmbH, <[email protected]> References Mirai Solutions GmbH: http://www.mirai-solutions.com Mirai Solutions Blog: http://miraisolutions.wordpress.com Apache POI: http://poi.apache.org Examples
# Load workbook; create if not existing wb <- loadWorkbook("XLConnect.xlsx", create = TRUE) # Create a worksheet createSheet(wb, name = "mtcars") # Create a name reference createName(wb, name = "mtcars", formula = "mtcars!$C$5") # Write built-in data.frame mtcars to the specified named region

addImage-methods
writeNamedRegion(wb, mtcars, name = "mtcars") # Save workbook saveWorkbook(wb)

addImage-methods

Adding images to a worksheet

Description Adds an image to a worksheet using a named region. Usage ## S4 method for signature workbook addImage(object, filename, name, originalSize) Arguments object filename name originalSize The workbook to use Name of the image le. Supported are images of the following formats: JPG/JPEG, PNG, WMF, EMF, BMP, PICT. Name of the named region that the image is set to If originalSize = TRUE, the image is inserted in the top left corner of the named region and not scaled. Otherwise, the image is scaled to t the named region. The default value for originalSize is FALSE.

Note There is an known issue in Apache POI with adding images to xls workbooks. The result of adding images to workbooks that already contain shapes or images may be that previous images are removed or that existing images are replaced with newly added ones. It is therefore advised that you use the addImage functionality only with workbooks that have no existing shapes or images. Note that this only holds for xls workbooks (Excel 97-2003) and not for xlsx (Excel 2007+). There should be no issues with xlsx workbooks. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, createName

6 Examples

appendNamedRegion-methods

## Write an R plot to a specified named region ## This example makes use of the Tonga Trench Earthquakes example # Load workbook (create if not existing) wb <- loadWorkbook("earthquake.xlsx", create = TRUE) # Create a sheet named earthquake createSheet(wb, name = "earthquake") # Create a named region called earthquake referring to the sheet # called earthquake createName(wb, name = "earthquake", formula = "earthquake!$B$2") # Create R plot to a png device require(lattice) png(filename = "earthquake.png", width = 8 devAskNewPage(ask = FALSE)

, height = 6

Depth <- equal.count(quakes$depth, number=8, overlap=.1) xyplot(lat ~ long | Depth, data = quakes) update(trellis.last.object(), strip = strip.custom(strip.names = TRUE, strip.levels = TRUE), par.strip.text = list(cex = .75), aspect = "iso") dev.off() # Write image to the named region created above using the images # original size; i.e. the images top left corner will match the # specified cells top left corner addImage(wb, filename = "earthquake.png", name = "earthquake", originalSize = TRUE) # Save workbook (this actually writes the file to disk) saveWorkbook(wb)

appendNamedRegion-methods Appending data to a named region

Description Appends data to an existing named region. Usage ## S4 method for signature workbook,ANY appendNamedRegion(object,data,name,header,rownames)

appendNamedRegion-methods Arguments object data name header rownames The workbook to use Data to write Name of the (existing) named region to which to append the data Species if the column names should be written. The default is FALSE.

Name (character) of column to use for the row names of the provided data object. If specied, the row names of the data object (data.frame) will be included as an additional column with the specied name. If rownames = NULL (default), no row names will be included.

Details Appends data to the existing named region specied by name. The data is appended at the bottom of the named region. See writeNamedRegion for further information on writing named regions. Note Named regions are automatically redened to the area occupied by the previous and the newly appended data. This guarantees that the complete set of data can be re-read using readNamedRegion. Note however, that no checks are performed to see whether the appended data has the same shape/structure as the previous data. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, writeNamedRegion, readNamedRegion, writeWorksheet, appendWorksheet, readWorksheet Examples
# mtcars xlsx file from demoFiles subfolder of package XLConnect demoExcelFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(demoExcelFile) # Append mtcars data set to named region named mtcars appendNamedRegion(wb, mtcars, name = "mtcars")

appendWorksheet-methods

appendWorksheet-methods Appending data to worksheets

Description Appends data to worksheets of a workbook. Usage ## S4 method for signature workbook,ANY,character appendWorksheet(object,data,sheet,header,rownames) ## S4 method for signature workbook,ANY,numeric appendWorksheet(object,data,sheet,header,rownames)

Arguments object data sheet header rownames The workbook to write to Data to append The name or index of the sheet to append the data to Species if the column names should be written. The default is TRUE. Name (character) of column to use for the row names of the provided data object. If specied, the row names of the data object (data.frame) will be included as an additional column with the specied name. If rownames = NULL (default), no row names will be included.

Details Appends data to the worksheet specied by sheet. Data will be appended at the bottom and left most column containing some data. If more complex "appending schemes" are required you may make direct use of writeWorksheet. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, writeWorksheet, readWorksheet, writeNamedRegion, appendNamedRegion, readNamedRegion

aref Examples
# mtcars xlsx file from demoFiles subfolder of package XLConnect demoExcelFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(demoExcelFile) # Append mtcars data set to worksheet named mtcars appendWorksheet(wb, mtcars, sheet = "mtcars")

aref

Constructing Excel area references

Description Constructs an Excel area reference Usage aref(topLeft, dimension) Arguments topLeft dimension Top left corner. Either a character specifying a cell reference in the form "A1" or a numeric vector of length two specifying the corresponding coordinates. Dimensions (numeric) of a 2-dimensional object (mostly a data.frame or a matrix)

Value Returns the area reference (character) for the specied top left cell and dimension. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also aref2idx, idx2aref, idx2cref, col2idx, idx2col Examples
aref("A1", dim(mtcars)) aref(c(1, 1), dim(mtcars))

10

cellstyle-class

aref2idx

Converting Excel cell references to row and column based cell references

Description Converts Excel cell references to row and column based cell references Usage aref2idx(x) Arguments x Value Returns a numeric matrix with four columns and as many rows as cell references that have been provided. The rst two columns represent the coordinates of the top left corner (row, column) and the third and fourth columns represent the bottom right corner of the referenced area. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also idx2aref, aref, cref2idx, idx2cref, col2idx, idx2col Examples
aref2idx(c("A1:B6", "B6:C17"))

Character vector of Excel cell references (e.g. "A1:B6", "B6:C17", ...)

cellstyle-class

Class "cellstyle"

Description This class represents a cell style in a Microsoft Excel workbook. S4 objects of this class and corresponding methods are used to manipulate cell styles. This includes setting data formats, borders, background- and foreground-colors, etc. Objects from the Class Cell styles are created by calling the createCellStyle method on a workbook object.

cellstyle-class Slots

11

jobj: Object of class jobjRef (see package rJava) which represents a Java object reference that is used in the back-end to manipulate the underlying Excel cell style instance. Note XLConnect generally makes use of custom (named) cell styles. This allows users to more easily manage cell styles via Excels cell style menu. For example, assuming you were using a specic custom cell style for your data table headers, you can change the header styling with a few clicks in Excels cell style menu across all tables. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com References Cell styles in Excel 2003: http://bit.ly/c1VUZ6 Cell styles in Excel 2007: http://bit.ly/gj1KRx See Also workbook, createCellStyle, setStyleAction, setCellStyle Examples
# Load workbook (create if not existing) wb <- loadWorkbook("cellstyles.xlsx", create = TRUE) # We dont set a specific style action in this demo, so the # default XLConnect will be used (XLC$"STYLE_ACTION.XLCONNECT") # Create a sheet named mtcars createSheet(wb, name = "mtcars") # Create a named region called mtcars referring to the sheet # called mtcars createName(wb, name = "mtcars", formula = "mtcars!$C$4") # Write built-in data set mtcars to the above defined named region. # This will use the default style action XLConnect. writeNamedRegion(wb, mtcars, name = "mtcars") # Now lets color all weight cells of cars with a weight > 3.5 in red # (mtcars$wt > 3.5) # First, create a corresponding (named) cell style heavyCar <- createCellStyle(wb, name = "HeavyCar")

12

clearNamedRegion-methods

# Specify the cell style to use a solid foreground color setFillPattern(heavyCar, fill = XLC$"FILL.SOLID_FOREGROUND") # Specify the foreground color to be used setFillForegroundColor(heavyCar, color = XLC$"COLOR.RED") # Which cars have a weight > 3.5 ? rowIndex <- which(mtcars$wt > 3.5) # NOTE: The mtcars data.frame has been written offset with top # left cell C4 - and we have also written a header row! # So, lets take that into account appropriately. Obviously, # the two steps could be combined directly into one ... rowIndex <- rowIndex + 4 # The same holds for the column index colIndex <- which(names(mtcars) == "wt") + 2 # Set the HeavyCar cell style for the corresponding cells. # Note: the row and col arguments are vectorized! setCellStyle(wb, sheet = "mtcars", row = rowIndex, col = colIndex, cellstyle = heavyCar) # Save workbook (this actually writes the file to disk) saveWorkbook(wb)

clearNamedRegion-methods Clearing named regions in a workbook

Description Clears named regions in a workbook. Usage ## S4 method for signature workbook,character clearNamedRegion(object, name)

Arguments object name The workbook to use The name of the named region to clear

clearRange-methods Details

13

Clearing a named region/range means to clear all the cells associated with that named region. Clearing named regions can be useful if (named) data sets in a worksheet need to be replaced, i.e. data is rst read, modied in R and nally written back to the the same named region. Without clearing the named region rst, (parts of) the original data may still be visible if they occupied a larger range in the worksheet. Author(s) Nicola Lambiase Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, clearSheet, clearRange, clearRangeFromReference, clearSheet Examples
# 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 data <- readNamedRegion(wb, name = "mtcars", header = TRUE) # Only consider cars with a weight >= 5 data <- data[data$wt >= 5, ] # Clear original named region clearNamedRegion(wb, name = "mtcars") # Write subsetted data back # Note: this is covering a smaller area now # writeNamedRegion automatically redefines the named region # to the size/area of the data writeNamedRegion(wb, data = data, name = "mtcars", header = TRUE)

clearRange-methods

Clearing cell ranges in a workbook

Description Clears cell ranges in a workbook.

14 Usage ## S4 method for clearRange(object, ## S4 method for clearRange(object, Arguments object sheet coords The workbook to use signature workbook,numeric sheet, coords) signature workbook,character sheet, coords)

clearRange-methods

The name or index of the worksheet in which to clear cell ranges Numeric vector of length 4 or numeric matrix with 4 columns where the elements of the vector or rows in the matrix refer to the coordinates of the top-left and bottom-right corners of the ranges to clear. I.e. a vector or each row species the coordinates {top row, left column, bottom row, right column}. You may use aref2idx to generate such a matrix.

Details Clearing a cell range means to clear all the cells associated with that range. Author(s) Nicola Lambiase Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, clearSheet, clearNamedRegion, clearRangeFromReference, clearSheet Examples
# mtcars xlsx file from demoFiles subfolder of # package XLConnect demoExcelFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(demoExcelFile) # Clear range from top left corner (4,2) ^= B4 to # bottom right corner (6,4) ^= D6 clearRange(wb, sheet = "mtcars", coords = c(4, 2, 6, 4)) # Clear two ranges in one go ... mat = matrix(c(5, 1, 6, 4, 5, 7, 7, 9), ncol = 4, byrow = TRUE) clearRange(wb, sheet = "mtcars", coords = mat) # The above is equivalent to ... clearRange(wb, sheet = "mtcars",

clearRangeFromReference-methods
coords = aref2idx(c("A5:D6", "G5:I7"))) # This in turn is the same as ... clearRangeFromReference(wb, reference = c("mtcars!A5:D6", "mtcars!G5:I7"))

15

clearRangeFromReference-methods Clearing cell ranges in a workbook

Description Clears cell ranges specied by area reference in a workbook. Usage ## S4 method for signature workbook,character clearRangeFromReference(object, reference) Arguments object reference Details Clearing a cell range means to clear all the cells associated with that range. This method is very similar to clearRange. Author(s) Nicola Lambiase Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, clearSheet, clearNamedRegion, clearRange, clearSheet Examples
# mtcars xlsx file from demoFiles subfolder of # package XLConnect demoExcelFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(demoExcelFile) # Clear ranges A5:D6 and G5:I7 on sheet mtcars

The workbook to use character specifying an area reference in the form SheetX!A7:B19

16
clearRangeFromReference(wb, reference = c("mtcars!A5:D6", "mtcars!G5:I7"))

clearSheet-methods

clearSheet-methods

Clearing worksheets in a workbook

Description Clears worksheets with specied names or indices in a workbook. Usage ## S4 method for clearSheet(object, ## S4 method for clearSheet(object, Arguments object sheet Details Clearing a worksheet means to clear all the cells in that worksheet. Consequently, the saved workbook should be smaller in size. Clearing a worksheet can be useful if data sets in a worksheet need to be replaced, i.e. data are rst read, modied in R and nally written back to the worksheet. Without clearing the worksheet rst, (parts of) the original data may still be visible if they occupied a larger range of the worksheet. Author(s) Nicola Lambiase Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, clearNamedRegion, clearRange, clearRangeFromReference Examples
# mtcars xlsx file from demoFiles subfolder of # package XLConnect demoExcelFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(demoExcelFile)

signature workbook,numeric sheet) signature workbook,character sheet)

The workbook to use The name or the index of the worksheet to clear

cloneSheet-methods

17

# Clear worksheets named mtcars and mtcars2 clearSheet(wb, sheet = c("mtcars", "mtcars2")) # Clear 3rd worksheet clearSheet(wb, sheet = 3)

cloneSheet-methods

Cloning/copying worksheets

Description Clones (copies) a worksheet in a workbook. Usage ## S4 method for signature workbook,numeric cloneSheet(object,sheet,name) ## S4 method for signature workbook,character cloneSheet(object,sheet,name) Arguments object sheet name The workbook to use The name or index of the worksheet to clone The name to assign to the cloned worksheet. Throws an exception if the name to assign is the name of an already existing worksheet.

Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, createSheet, removeSheet, renameSheet, getSheets, existsSheet Examples
# mtcars xlsx file from demoFiles subfolder of package XLConnect demoExcelFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(demoExcelFile) # Clone the mtcars worksheet and assign it the name mtcars cloned cloneSheet(wb, sheet = "mtcars", name = "mtcars cloned")

18

createCellStyle-methods

col2idx

Converting Excel column names to indices

Description Converts Excel column names to indices. Usage col2idx(x) Arguments x Value Returns a vector of integers representing the corresponding column indices. Note that passing invalid column name references may result in an arbitrary number. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also idx2col, cref2idx, idx2cref, idx2aref, aref2idx, aref Examples
col2idx(c("A", "BTG"))

Character vector of Excel column names (e.g. "A", "AF", ...)

createCellStyle-methods Creating custom named and anonymous cell styles

Description Creates a custom named or anonymous cellstyle. Usage ## S4 method for signature workbook,character createCellStyle(object,name)

createCellStyle-methods Arguments object name The workbook to use

19

The name of the new cellstyle to create. Omit to create an anonymous cellstyle.

Details Creates a named cellstyle with the specied name. Named cell styles may be used in conjunction with the name prex style action (see setStyleAction) or may also be used directly with the method setCellStyle. Named cell styles can easily be changed from within Excel using the cell styles menu. If name is missing, an anonymous cell style is created. Anonymous cell styles can be used in conjunction with the setCellStyle method. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, cellstyle, setStyleAction, setStyleNamePrefix, setCellStyle, setDataFormat, setBorder, setFillBackgroundColor, setFillForegroundColor, setFillPattern, setWrapText Examples
# Load workbook (create if not existing) wb <- loadWorkbook("createCellstyles.xlsx", create = TRUE) # We dont set a specific style action in this demo, so the # default XLConnect will be used (XLC$"STYLE_ACTION.XLCONNECT") # Create a sheet named mtcars createSheet(wb, name = "mtcars") # Create a named region called mtcars referring to the sheet # called mtcars createName(wb, name = "mtcars", formula = "mtcars!$C$4") # Write built-in data set mtcars to the above defined named region. # This will use the default style action XLConnect. writeNamedRegion(wb, mtcars, name = "mtcars") # Now lets color all weight cells of cars with a weight > 3.5 in red # (mtcars$wt > 3.5) # First, create a corresponding (named) cell style heavyCar <- createCellStyle(wb, name = "HeavyCar") # Specify the cell style to use a solid foreground color

20
setFillPattern(heavyCar, fill = XLC$"FILL.SOLID_FOREGROUND") # Specify the foreground color to be used setFillForegroundColor(heavyCar, color = XLC$"COLOR.RED") # Which cars have a weight > 3.5 ? rowIndex <- which(mtcars$wt > 3.5) # NOTE: The mtcars data.frame has been written offset with # top left cell C4 - and we have also written a header row! # So, lets take that into account appropriately. Obviously, # the two steps could be combined directly into one ... rowIndex <- rowIndex + 4 # The same holds for the column index colIndex <- which(names(mtcars) == "wt") + 2

createFreezePane-methods

# Set the HeavyCar cell style for the corresponding cells. # Note: the row and col arguments are vectorized! setCellStyle(wb, sheet = "mtcars", row = rowIndex, col = colIndex, cellstyle = heavyCar) # Save workbook (this actually writes the file to disk) saveWorkbook(wb)

createFreezePane-methods Creating a freeze pane on a worksheet

Description Creates a freeze pane on a specied worksheet. Usage ## S4 method for signature workbook,character createFreezePane(object, sheet, colSplit, rowSplit, leftColumn, topRow) ## S4 method for signature workbook,numeric createFreezePane(object, sheet, colSplit, rowSplit, leftColumn, topRow) Arguments object sheet colSplit rowSplit leftColumn topRow The workbook to use The name or index of the sheet on which to create a freeze pane Horizontal position of freeze (as column index or name) Vertical position of freeze (as number of rows) Left column (as column index or name) visible in right pane. If not specied, the default is leftColumn=colSplit Top row (as index) visible in bottom pane. If not specied, the default is topRow=rowSplit

createName-methods Note

21

To keep an area of a worksheet visible while you scroll to another area of the worksheet, you can lock specic rows or columns in one area by freezing or splitting panes. When you freeze panes, you keep specic rows or columns visible when you scroll in the worksheet. For example, you might want to keep row and column labels visible as you scroll. When you split panes, you create separate worksheet areas that you can scroll within, while rows or columns in the non-scrolled area remain visible. Author(s) Nicola Lambiase Mirai Solutions GmbH http://www.mirai-solutions.com References How to create a freeze pane/split pane in Ofce 2007 http://office.microsoft.com/en-us/ excel-help/freeze-or-lock-rows-and-columns-HP 1217 48.aspx See Also workbook createSplitPane removePane Examples
# Load workbook (create if not existing) wb <- loadWorkbook("freezePaneTest.xlsx", create = TRUE) # Create a worksheet named Sheet1 createSheet(wb, name = "Sheet1") # Create a freeze pane on Sheet1, using as reference position the 5th column and the 5th row, # showing the 1 th column as the leftmost visible one in the right pane # and the 1 th row as the top visible one in the bottom pane. createFreezePane(wb, "Sheet1", 5, 5, 1 , 1 ) # Save workbook (this actually writes the file to disk) saveWorkbook(wb)

createName-methods

Creating names in a workbook

Description Creates a name for a specied formula in a workbook. Usage ## S4 method for signature workbook createName(object, name, formula, overwrite)

22 Arguments object name formula overwrite The workbook to use The names name to create Excel formula specifying the name

createName-methods

If a name with the same name already exists and overwrite = TRUE, then this name is removed rst before the new one is created. If a name already exists and overwrite = FALSE, then an exception is thrown. The default value for overwrite is FALSE.

Details Creates a name named name for the specied formula. The formula should be specied as you would type it in Excel. Make sure that the worksheets, functions, ... exist that you are referring to in the formula. The name, formula and overwrite arguments are vectorized such that multiple names can be created in one method call. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com 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=iAE9a uRtpM See Also workbook, removeName, existsName, getDefinedNames, readNamedRegion, writeNamedRegion Examples
# Load workbook (create if not existing) wb <- loadWorkbook("createName.xlsx", create = TRUE) # Create a worksheet named mtcars createSheet(wb, name = "mtcars") # Create a named region called mtcars on the sheet called mtcars createName(wb, name = "mtcars", formula = "mtcars!$A$1") # Write built-in data set mtcars to the above defined named region writeNamedRegion(wb, mtcars, name = "mtcars") # Save workbook

createSheet-methods
saveWorkbook(wb)

23

createSheet-methods

Creating worksheets in a workbook

Description Creates worksheets with specied names in a workbook. Usage ## S4 method for signature workbook createSheet(object, name) Arguments object name Details Creates a worksheet with the specied name if it does not already exist. Note that the naming of worksheets needs to be in line with Excels convention, otherwise an exception will be thrown. For example, worksheet names cannot be longer than 31 characters. Also note that the name argument is vectorized, so multiple worksheets can be created in one method call. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, removeSheet, renameSheet, existsSheet, getSheets, cloneSheet Examples
# Load workbook (create if not existing) wb <- loadWorkbook("createSheet.xlsx", create = TRUE) # Create a worksheet called CO2 createSheet(wb, name = "CO2") # Save workbook (this actually writes the file to disk) saveWorkbook(wb)

The workbook to use The name of the sheet to create

24

createSplitPane-methods

createSplitPane-methods Creating a split pane on a worksheet

Description Creates a split pane on a specied worksheet. Usage ## S4 method for signature workbook,character createSplitPane(object,sheet,xSplitPos,ySplitPos,leftColumn,topRow) ## S4 method for signature workbook,numeric createSplitPane(object,sheet,xSplitPos,ySplitPos,leftColumn,topRow) Arguments object sheet xSplitPos ySplitPos leftColumn topRow Note To keep an area of a worksheet visible while you scroll to another area of the worksheet, you can lock specic rows or columns in one area by freezing or splitting panes. When you freeze panes, you keep specic rows or columns visible when you scroll in the worksheet. For example, you might want to keep row and column labels visible as you scroll. When you split panes, you create separate worksheet areas that you can scroll within, while rows or columns in the non-scrolled area remain visible. Author(s) Nicola Lambiase Mirai Solutions GmbH http://www.mirai-solutions.com References How to create a freeze pane/split pane in Ofce 2007 http://office.microsoft.com/en-us/ excel-help/freeze-or-lock-rows-and-columns-HP 1217 48.aspx See Also workbook createFreezePane removePane The workbook to use The name or index of the sheet on which to create a split pane Horizontal position of split (in 1/20th of a point) Vertical position of split (in 1/20th of a point) Left column (as index or column name) visible in right pane Top row visible in bottom pane

cref2idx Examples
# Load workbook (create if not existing) wb <- loadWorkbook("splitPaneTest.xlsx", create = TRUE) # Create a worksheet named Sheet1 createSheet(wb, name = "Sheet1") # Create a split pane on Sheet1, with coordinates (1 # 1 (-> J) as left column visible in right pane and 1 createSplitPane(wb, "Sheet1", 1 , 5 , 1 , 1 ) # Save workbook (this actually writes the file to disk) saveWorkbook(wb)

25

, 5 ) expressed as 1/2 th of a point, as top row visible in bottom pane

cref2idx

Converting Excel cell references to indices

Description Converts Excel cell references to row & column indices Usage cref2idx(x) Arguments x Value Returns a numeric matrix with two columns and as many rows as cell references that have been provided. The rst column represents the row indices and the second column represents the column indices. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also idx2cref, col2idx, idx2col, idx2aref, aref2idx, aref Examples
cref2idx(c("$A$2 ", "B18"))

Character vector of Excel cell references (e.g. "$A$20", "B18", ...)

26

existsName-methods

existsName-methods

Checking existence of names in a workbook

Description Checks the existence of a name in a workbook. Usage ## S4 method for signature workbook existsName(object, name) Arguments object name Details Returns TRUE if the specied name exists and FALSE otherwise. Note that the name argument is vectorized and therefore multiple names can be checked for existence in one method call. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, createName, removeName, getDefinedNames, readNamedRegion, writeNamedRegion Examples
# mtcars xlsx file from demoFiles subfolder of package XLConnect mtcarsFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(mtcarsFile) # Check if the name mtcars exists # (should return TRUE since the name is defined as mtcars!$A$1:$K$33) existsName(wb, name = "mtcars")

The workbook to use The name to check for

existsSheet-methods

27

existsSheet-methods

Checking for existence of worksheets in a workbook

Description Checks the existence of a worksheet in a workbook. Usage ## S4 method for signature workbook existsSheet(object,name) Arguments object name Details Checks if the specied worksheet exists. Returns TRUE if it exists, otherwise FALSE. The name argument is vectorized which allows to check for existence of multiple worksheets with one call. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, createSheet, removeSheet, renameSheet, getSheets, cloneSheet Examples
# mtcars xlsx file from demoFiles subfolder of package XLConnect demoExcelFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(demoExcelFile) # Check for existence of a worksheet called mtcars existsSheet(wb, "mtcars")

The workbook to use The sheet name to check for

28

extraction-methods

extraction-methods

Workbook data extraction & replacement operators

Description Operators that allow to extract/replace data from/on a workbook. Arguments x i j drop value ... The workbook object to use Name of worksheet ([, [<-) or name of Excel name ([[, [[<-) to extract or replace Only used with [[<-: Optional formula to dene the Excel name if it does not yet exist on the workbook. Not used Data object used for replacement Arguments passed to the corresponding underlying function to read/write the data

Details The workbook extraction operators are basically syntactic sugar for the common methods readWorksheet ([), writeWorksheet ([<-), readNamedRegion ([[), writeNamedRegion ([[<-). Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, readWorksheet, writeWorksheet, readNamedRegion, writeNamedRegion Examples
# Load workbook (create if not existing) wb <- loadWorkbook("extraction.xlsx", create = TRUE) # Write mtcars data set on a worksheet named mtcars1. # Note: The mtcars1 sheet will be created automatically if it does # not exist yet. Also, default values for other writeWorksheet arguments # hold, i.e. the data set is written starting at the top left corner. wb["mtcars1"] = mtcars # Write mtcars data set on a worksheet named mtcars2. # Again, the mtcars2 worksheet is created automatically. # Additionally specify arguments passed to the underlying method

extractSheetName
# writeWorksheet. wb["mtcars2", startRow = 6, startCol = 11, header = FALSE] = mtcars # Read worksheets mtcars1 and mtcars2. # Note: The default arguments hold for the underlying method # readWorksheet. wb["mtcars1"] wb["mtcars2"] # Write mtcars data set to a named region named mtcars3. Since # it doesnt exist yet we also need to specify the formula to # define it. Also note that the sheet mtcars3 referenced in the # formula does not yet exist - it will be created automatically! # Moreover, default values for other writeNamedRegion arguments hold. wb[["mtcars3", "mtcars3!$B$7"]] = mtcars # Redefine named region mtcars3. Note that no formula specification # is required since named region is already defined (see above example). wb[["mtcars3"]] = mtcars # Write mtcars data set to a named region mtcars4. Since the named # region does not yet exist a formula specification is required. Also, # additional arguments are specified that are passed to the underlying # method writeNamedRegion. wb[["mtcars4", "mtcars4!$D$8", rownames = "Car"]] = mtcars # Read the named regions mtcars3 and mtcars4. # Note: Default values hold for the underlying method readNamedRegion. wb[["mtcars3"]] wb[["mtcars4"]]

29

extractSheetName

Extracting the sheet name from a formula

Description Extracts the sheet name from a formula of the form <SHEET_NAME>!<CELL_ADDRESS> Usage extractSheetName(formula) Arguments formula Formula string of the form <SHEET_NAME>!<CELL_ADDRESS>. Note that the validity of the formula wont be checked.

30 Value

getActiveSheetIndex-methods

Returns the name of the sheet referenced in the formula. For quoted sheet names (required if names contain e.g. whitespaces or exclamation marks (!)) in formulas the function returns the unquoted name. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com Examples
extractSheetName(c("MySheet!$A$1", "My Sheet!$A$1", "My!Sheet!$A$1"))

getActiveSheetIndex-methods Querying the active worksheet index

Description Queries the index of the active worksheet in a workbook. Usage ## S4 method for signature workbook getActiveSheetIndex(object) Arguments object Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, getActiveSheetName Examples
# mtcars xlsx file from demoFiles subfolder of package XLConnect demoExcelFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(demoExcelFile) # Query the active sheet index activeSheet <- getActiveSheetIndex(wb)

The workbook to use

getActiveSheetName-methods

31

getActiveSheetName-methods Querying the active worksheet name

Description Queries the name of the active worksheet in a workbook. Usage ## S4 method for signature workbook getActiveSheetName(object) Arguments object Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, getActiveSheetIndex Examples
# mtcars xlsx file from demoFiles subfolder of package XLConnect demoExcelFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(demoExcelFile) # Query the active sheet name activeSheet <- getActiveSheetName(wb)

The workbook to use

getBoundingBox-methods Querying the coordinates of a worksheet bounding box

Description This function queries the coordinates of a bounding box in an Excel worksheet. A bounding box is the rectangular region of minimum size containing all the non-empty cells in a sheet.

32 Usage

getBoundingBox-methods

## S4 method for signature workbook,character getBoundingBox(object,sheet,startRow,startCol,endRow,endCol,autofitRow,autofitCol) ## S4 method for signature workbook,numeric getBoundingBox(object,sheet,startRow,startCol,endRow,endCol,autofitRow,autofitCol) Arguments object sheet startRow startCol endRow endCol autofitRow autofitCol The workbook to use The name or index of the sheet from which to get the bounding box Start reference row for the bounding box. Defaults to meaning that the start row is determined automatically. Start reference column for the bounding box. Defaults to meaning that the start column is determined automatically. End reference row for the bounding box. Defaults to meaning that the end row is determined automatically. End reference column for the bounding box. Defaults to meaning that the end column is determined automatically. logical specifying if leading and trailing empty rows should be skipped. Defaults to TRUE. logical specifying if leading and trailing empty columns should be skipped. Defaults to TRUE.

Details The result is a matrix containing the following coordinates: [1,] top left row [2,] top left column [3,] bottom right row [4,] bottom right column In case more than one sheet is selected, the result matrix will contain a column for each sheet.

The bounding box resolution algorithm works as follows: If startRow <= then the rst available row in the sheet is assumed. If endRow <= then the last available row in the sheet is assumed. If startCol <= then the minimum column between startRow and endRow is assumed. If endCol <= then the maximum column between startRow and endRow is assumed. The arguments autofitRow and autofitCol (both defaulting to TRUE) can be used to skip leading and trailing empty rows even in case startRow, endRow, startCol and endCol are specied to values > . This can be useful if data is expected within certain given boundaries but the exact location is not available. Author(s) Nicola Lambiase Mirai Solutions GmbH http://www.mirai-solutions.com

getCellFormula-methods See Also workbook, getReferenceCoordinates Examples

# multiregion xlsx file from demoFiles subfolder of package XLConnect demoExcelFile <- system.file("demoFiles/multiregion.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(demoExcelFile) # Query bounding box for the second sheet print(getBoundingBox(wb, sheet="SecondSheet")) # Query bounding box for the first sheet, selecting the columns from 5 to 8 print(getBoundingBox(wb, sheet="FirstSheet", startCol=5, endCol=8))

33

getCellFormula-methods Retrieving formula denitions from cells

Description Retrieves a cell formula from a workbook. Usage ## S4 method for signature workbook,character getCellFormula(object,sheet,row,col) ## S4 method for signature workbook,numeric getCellFormula(object,sheet,row,col) Arguments object sheet row col Details Retrieves the formula of the specied cell as a character, without the initial = character displayed in Excel. Raises an error if the specied cell is not a formula cell. Author(s) Thomas Themel Mirai Solutions GmbH http://www.mirai-solutions.com The workbook to use The name or index of the worksheet containing the cell The one-based row index of the cell to query The one-based column index of the cell to query

34 See Also workbook, setCellFormula Examples

# Load workbook (create if not existing) wb <- loadWorkbook("cellFormula.xlsx", create = TRUE) createSheet(wb, "Formula") # Assign a formula to A1 setCellFormula(wb, "Formula", 1, 1, "SUM($B$1:$B$29)") # Returns the formula for Sheet1!A1 getCellFormula(wb, "Formula", 1, 1) # The same with a numeric sheet index getCellFormula(wb, 1, 1, 1)

getCellStyle-methods

getCellStyle-methods

Retrieving named cell styles

Description Retrieves a named cell style from a workbook. Usage ## S4 method for signature workbook getCellStyle(object,name) Arguments object name Details Retrieves the cellstyle with the specied name. Author(s) Thomas Themel Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, cellstyle, setStyleAction, setStyleNamePrefix, setCellStyle, setDataFormat, setBorder, setFillBackgroundColor, setFillForegroundColor, setFillPattern, setWrapText The workbook to use The name of the cellstyle to retrieve

getDenedNames-methods Examples
# Load workbook (create if not existing) wb <- loadWorkbook("getCellstyles.xlsx", create = TRUE) # You wouldnt usually ignore the return value here... createCellStyle(wb, Header) # ... but if you did it doesnt hurt. cs <- getCellStyle(wb, Header) # Specify the cell style to use a solid foreground color setFillPattern(cs, fill = XLC$"FILL.SOLID_FOREGROUND") # Specify the foreground color to be used setFillForegroundColor(cs, color = XLC$"COLOR.RED")

35

getDefinedNames-methods Retrieving dened names in a workbook

Description Retrieves the dened names in a workbook. Usage ## S4 method for signature workbook getDefinedNames(object, validOnly) Arguments object validOnly The workbook to use If validOnly = TRUE only names with valid references are returned. Valid references are ones not starting with #REF! or #NULL! - which could result e.g. due to a missing sheet reference. The default value for validOnly is TRUE.

Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, createName, removeName, existsName, readNamedRegion, writeNamedRegion

36 Examples

getForceFormulaRecalculation-methods

# mtcars xlsx file from demoFiles subfolder of package XLConnect mtcarsFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(mtcarsFile) # Retrieve defined names with valid references getDefinedNames(wb)

getForceFormulaRecalculation-methods Querying the coordinates of the range reference by an Excel name

Description Queries the "force formula recalculation" ag on an Excel worksheet.

Usage ## S4 method for signature workbook,character getForceFormulaRecalculation(object,sheet) ## S4 method for signature workbook,numeric getForceFormulaRecalculation(object,sheet)

Arguments object sheet The workbook to use The name or index of the sheet to query. This argument is vectorized such that multiple sheets can be queried with one method call. If sheet = "*", the ag is queried for all sheets in the workbook (in the order as returned by getSheets).

Author(s) Thomas Themel Mirai Solutions GmbH http://www.mirai-solutions.com

See Also workbook, getSheets, setForceFormulaRecalculation

getLastColumn-methods Examples
# mtcars xlsx file from demoFiles subfolder of package XLConnect demoExcelFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(demoExcelFile) # Ask whether Excel will automatically recalculate formulas on sheet mtcars print(getForceFormulaRecalculation(wb, sheet = "mtcars"))

37

getLastColumn-methods Querying the last (non-empty) column on a worksheet

Description Queries the last (non-empty) column on a worksheet. Usage ## S4 method for signature workbook,character getLastColumn(object,sheet) ## S4 method for signature workbook,numeric getLastColumn(object,sheet) Arguments object sheet Details Returns the (1-based) numeric index of the last non-empty column in the specied worksheet. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook The workbook to use The name or index of the sheet of which to query the last column

38 Examples

getLastRow-methods

# mtcars xlsx file from demoFiles subfolder of package XLConnect demoExcelFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(demoExcelFile) # Query the last row of the mtcars worksheet getLastColumn(wb, "mtcars") # Query the last row of the mtcars2 worksheet getLastColumn(wb, "mtcars2") # Query the last row of the mtcars3 worksheet getLastColumn(wb, "mtcars3")

getLastRow-methods

Querying the last (non-empty) row on a worksheet

Description Queries the last (non-empty) row on a worksheet. Usage ## S4 method for signature workbook,character getLastRow(object,sheet) ## S4 method for signature workbook,numeric getLastRow(object,sheet) Arguments object sheet Details Returns the numeric index of the last non-empty row in the specied worksheet. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook The workbook to use The name or index of the sheet of which to query the last row

getReferenceCoordinates-methods Examples
# mtcars xlsx file from demoFiles subfolder of package XLConnect demoExcelFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(demoExcelFile) # Query the last row of the mtcars worksheet getLastRow(wb, "mtcars") # Query the last row of the mtcars2 worksheet getLastRow(wb, "mtcars2") # Query the last row of the mtcars3 worksheet getLastRow(wb, "mtcars3")

39

getReferenceCoordinates-methods Querying the coordinates of the range reference by an Excel name

Description Queries the coordinates of an Excel name in a workbook. Usage ## S4 method for signature workbook getReferenceCoordinates(object,name) Arguments object name The workbook to use The name to query. This argument is vectorized such that multiple names can be queried with one method call.

Author(s) Thomas Themel Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, createName, existsName, removeName, getReferenceFormula

40 Examples

getReferenceFormula-methods

# mtcars xlsx file from demoFiles subfolder of package XLConnect demoExcelFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(demoExcelFile) # Query reference coordinate for name mtcars print(getReferenceCoordinates(wb, name = "mtcars"))

getReferenceFormula-methods Querying reference formulas of Excel names

Description Queries the reference formula of an Excel name in a workbook. Usage ## S4 method for signature workbook getReferenceFormula(object,name) Arguments object name The workbook to use The name to query. This argument is vectorized such that multiple names can be queried with one method call.

Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, createName, existsName, removeName Examples
# mtcars xlsx file from demoFiles subfolder of package XLConnect demoExcelFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(demoExcelFile) # Query reference formula for name mtcars print(getReferenceFormula(wb, name = "mtcars"))

getSheetPos-methods

41

getSheetPos-methods

Querying worksheet position

Description Queries the position of a worksheet in a workbook. Usage ## S4 method for signature workbook,character getSheetPos(object,sheet) Arguments object sheet The workbook to use The name of the worksheet (character) to query. This argument is vectorized such that multiple worksheets can be queried with one method call.

Value Returns the position index of the corresponding worksheet. Note that querying a non-existing worksheet results in a 0 index and does not throw an exception! Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, setSheetPos, getSheets Examples
# mtcars xlsx file from demoFiles subfolder of package XLConnect demoExcelFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(demoExcelFile) # Query worksheet positions for the worksheets mtcars2, mtcars3, # mtcars and NotThere (which actually does not exist) print(getSheetPos(wb, sheet = c("mtcars2", "mtcars3", "mtcars", "NotThere")))

42

hideSheet-methods

getSheets-methods

Querying available worksheets in a workbook

Description Returns all worksheet names in a workbook. Usage ## S4 method for signature workbook getSheets(object) Arguments object Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, createSheet, removeSheet, renameSheet, getSheetPos, setSheetPos Examples
# mtcars xlsx file from demoFiles subfolder of package XLConnect demoExcelFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(demoExcelFile) # Query available worksheets sheets <- getSheets(wb)

The workbook to use

hideSheet-methods

Hiding worksheets in a workbook

Description (Very) hides the specied worksheets in a workbook.

hideSheet-methods Usage ## S4 method for signature workbook,character hideSheet(object, sheet, veryHidden) ## S4 method for signature workbook,numeric hideSheet(object, sheet, veryHidden) Arguments object sheet veryHidden The workbook to use The name or index of the sheet to hide

43

If veryHidden = TRUE, the specied sheet is "very" hidden (see note), otherwise it is just hidden. Default is FALSE.

Details The arguments sheet and veryHidden are vectorized such that multiple worksheets can be (very) hidden with one method call. An exception is thrown if the specied sheet does not exist. Note Note that hidden worksheets can be unhidden by users directly within Excel via standard functionality. Therefore Excel knows the concept of "very hidden" worksheets. These worksheets cannot be unhidden with standard Excel functionality but need programatic intervention to be made visible.

Also note that in case the specied worksheet to hide is the currently active worksheet, then hideSheet tries to set the active worksheet to the rst non-hidden (not hidden and not very hidden) worksheet in the workbook. If there is no such worksheet, hideSheet will throw an exception. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, unhideSheet, isSheetHidden, isSheetVeryHidden, isSheetVisible Examples
# Load workbook (create if not existing) wb <- loadWorkbook("hiddenWorksheet.xlsx", create = TRUE) # Write a couple of built-in data.frames into sheets # with corresponding name for(obj in c("CO2", "airquality", "swiss")) { createSheet(wb, name = obj) writeWorksheet(wb, get(obj), sheet = obj) }

44

idx2aref

# Hide sheet airquality; # the sheet may be unhidden by a user from within Excel # since veryHidden defaults to FALSE hideSheet(wb, sheet = "airquality") # Save workbook saveWorkbook(wb)

idx2aref

Converting row and column based area references to Excel area references

Description Converts row & column based area references to Excel area references Usage idx2aref(x) Arguments x Numeric (integer) matrix or vector of indices. If a matrix is provided it should have four columns with the rst two columns representing the top left corner (row and column indices) and the third & fourth column representing the bottom right corner. If a vector is provided it will be converted to a matrix by lling the vector into a 4-column matrix by row.

Value Returns a character vector of corresponding Excel area references. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also aref2idx, aref, idx2cref, cref2idx, idx2col, col2idx Examples
idx2aref(c(1, 1, 5, 4))

idx2col

45

idx2col

Converting column indices to Excel column names

Description Converts column indices to Excel column names. Usage idx2col(x) Arguments x Value Returns a character vector of corresponding Excel column names. Numbers <= empty string (""). Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also col2idx, idx2cref, cref2idx, idx2aref, aref2idx, aref Examples
idx2col(c(1, 347))

Numeric (integer) vector of column indices

result in the

idx2cref

Converting indices to Excel cell references

Description Converts row & column indices to Excel cell references Usage idx2cref(x, absRow = TRUE, absCol = TRUE)

46 Arguments x

isSheetHidden-methods

Numeric (integer) matrix or vector of indices. If a matrix is provided it should have two columns with the rst column representing the row indices and the second column representing the column indices (i.e. each row represents a indexbased cell reference). If a vector is provided it will be converted to a matrix by lling the vector into a 2-column matrix by row. Boolean determining if the row index should be considered absolute. If TRUE (default), this will result in a $-prexed row identier. Boolean determining if the column index should be considered absolute. If TRUE (default), this will result in a $-prexed column identier.

absRow absCol

Value Returns a character vector of corresponding Excel cell references. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also cref2idx, idx2col, col2idx, idx2aref, aref2idx, aref Examples
idx2cref(c(5, 8, 14, 38))

isSheetHidden-methods Checking if worksheets are hidden in a workbook

Description Checks if the specied worksheets are hidden (but not very hidden) in a workbook. Usage ## S4 method for signature workbook,character isSheetHidden(object,sheet) ## S4 method for signature workbook,numeric isSheetHidden(object,sheet) Arguments object sheet The workbook to use The name or index of the sheet to check

isSheetVeryHidden-methods Details

47

Returns TRUE if the specied sheet is hidden (not visible but also not very hidden), otherwise FALSE. sheet is vectorized such that multiple worksheets can be queried with one method call. An exception is thrown if the specied sheet does not exist. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, hideSheet, unhideSheet, isSheetVeryHidden, isSheetVisible Examples
# Load workbook (create if not existing) wb <- loadWorkbook("isSheetHidden.xlsx", create = TRUE) # Write a couple of built-in data.frames into sheets # with corresponding name for(obj in c("CO2", "airquality", "swiss")) { createSheet(wb, name = obj) writeWorksheet(wb, get(obj), sheet = obj) } # Hide sheet airquality hideSheet(wb, sheet = "airquality") # Check if sheet airquality is hidden; # this should obviously return TRUE isSheetHidden(wb, "airquality") # Check if sheet swiss is hidden; # this should obviously return FALSE isSheetHidden(wb, "swiss")

isSheetVeryHidden-methods Checking if worksheets are very hidden in a workbook

Description Checks if the specied worksheets are very hidden (but not just hidden) in a workbook.

48 Usage ## S4 method for signature workbook,character isSheetVeryHidden(object,sheet) ## S4 method for signature workbook,numeric isSheetVeryHidden(object,sheet) Arguments object sheet Details The workbook to use The name or index of the sheet to check

isSheetVeryHidden-methods

Returns TRUE if the specied named sheet is very hidden (not visible but also not just hidden), otherwise FALSE. sheet is vectorized such that multiple worksheets can be queried with one method call. An exception is thrown if the specied sheet does not exist. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, hideSheet, unhideSheet, isSheetHidden, isSheetVisible Examples
# Load workbook (create if not existing) wb <- loadWorkbook("isSheetVeryHidden.xlsx", create = TRUE) # Write a couple of built-in data.frames into sheets # with corresponding name for(obj in c("CO2", "airquality", "swiss")) { createSheet(wb, name = obj) writeWorksheet(wb, get(obj), sheet = obj) } # Very hide sheet airquality hideSheet(wb, sheet = "airquality", veryHidden = TRUE) # Hide sheet CO2 hideSheet(wb, sheet = "CO2", veryHidden = FALSE) # Check if sheet airquality is very hidden; # this should obviously return TRUE isSheetVeryHidden(wb, "airquality") # Check if sheet swiss is very hidden; # this should obviously return FALSE isSheetVeryHidden(wb, "swiss")

isSheetVisible-methods

49

# Check if sheet CO2 is very hidden; # this should also return FALSE - the sheet # is just hidden but not very hidden isSheetVeryHidden(wb, "CO2")

isSheetVisible-methods Checking if worksheets are visible in a workbook

Description Checks if the specied worksheets are visible in a workbook. Usage ## S4 method for signature workbook,character isSheetVisible(object,sheet) ## S4 method for signature workbook,numeric isSheetVisible(object,sheet) Arguments object sheet Details Returns TRUE if the specied named sheet is visible (not hidden and not very hidden), otherwise FALSE. sheet is vectorized such that multiple worksheets can be queried with one method call. An exception is thrown if the specied sheet does not exist. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, hideSheet, unhideSheet, isSheetHidden, isSheetVeryHidden The workbook to use The name or index of the sheet to check

50 Examples
# Load workbook (create if not existing) wb <- loadWorkbook("isSheetVisible.xlsx", create = TRUE) # Write a couple of built-in data.frames into sheets # with corresponding name for(obj in c("CO2", "airquality", "swiss")) { createSheet(wb, name = obj) writeWorksheet(wb, get(obj), sheet = obj) } # Hide sheet CO2 hideSheet(wb, sheet = "CO2", veryHidden = FALSE) # Very hide sheet airquality hideSheet(wb, sheet = "airquality", veryHidden = TRUE) # Check if sheet swiss is visible; # this should obviously return TRUE isSheetVisible(wb, "swiss") # Check if sheet CO2 is visible; # this should obviously return FALSE isSheetVisible(wb, "CO2") # Check if sheet airquality is visible; # this should obviously return FALSE isSheetVisible(wb, "airquality")

loadWorkbook

loadWorkbook

Loading Microsoft Excel workbooks

Description Loads or creates a Microsoft Excel workbook for further manipulation. Usage loadWorkbook(filename, create = FALSE) Arguments filename Filename (absolute or relative) of Excel workbook to be loaded. Supported are Excel 97 (*.xls) and OOXML (Excel 2007+, *.xlsx) le formats. Paths are expanded using path.expand. Species if the le should be created if it does not already exist (default is FALSE). Note that create = TRUE has no effect if the specied le exists, i.e. an existing le is loaded and not being recreated if create = TRUE.

create

mergeCells-methods Value Returns a workbook object for further manipulation. Note

51

loadWorkbook is basically just a shortcut form of new("workbook", filename, create) with some additional error checking. As such it is the preferred way of creating workbook instances. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com References Wikipedia: Ofce Open XML http://en.wikipedia.org/wiki/Office_Open_XML See Also workbook, saveWorkbook Examples
# Load existing demo Excel file mtcars.xlsx from the XLConnect package wb.mtcars <- loadWorkbook(system.file("demoFiles/mtcars.xlsx", package = "XLConnect")) # Create new workbook wb.new <- loadWorkbook("myNewExcelFile.xlsx", create = TRUE) # NOTE: The above statement does not write the file to disk! # saveWorkbook(wb.new) would need to be called in order to write/save # the file to disk!

mergeCells-methods

Merging cells

Description Merges cells in a worksheet. Usage ## S4 method for signature workbook,character mergeCells(object,sheet,reference) ## S4 method for signature workbook,numeric mergeCells(object,sheet,reference)

52 Arguments object sheet reference Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, unmergeCells, idx2cref Examples
# Load workbook (create if not existing) wb <- loadWorkbook("mergeCells.xlsx", create = TRUE) # Create a worksheet called merge createSheet(wb, name = "merge") # Merge the cells A1:B8 on the worksheet created above mergeCells(wb, sheet = "merge", reference = "A1:B8") # Save workbook saveWorkbook(wb)

mirai

The workbook to use The name or index of the sheet on which to merge cells A cell range specication (character) in the form A1:B8

mirai

Mirai Solutions GmbH

Description Utility object to easily get to the Mirai Solutions GmbH web page. Just enter mirai in the R console. Usage mirai References Mirai Solutions GmbH http://www.mirai-solutions.com

onErrorCell-methods

53

onErrorCell-methods

Behavior when error cells are detected

Description This function denes the behavior when reading data from a worksheet and error cells are detected. Usage ## S4 method for signature workbook onErrorCell(object,behavior) Arguments object behavior The workbook to use The behavior to follow when an error cell is detected. This is normally specied by a corresponding XLC error constant, i.e. either XLC$"ERROR.WARN" or XLC$"ERROR.STOP". XLC$"ERROR.WARN" means the error cell will be read as missing value (NA) and a corresponding warning will be generated (this is the default behavior). XLC$"ERROR.STOP" means that an exception will be thrown and further execution will be stopped immediately.

Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, readNamedRegion, readNamedRegionFromFile, readWorksheet, readWorksheetFromFile Examples
# errorCell xlsx file from demoFiles subfolder of package XLConnect demoExcelFile <- system.file("demoFiles/errorCell.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(demoExcelFile) # Set error behavior to XLC$ERROR.WARN when detecting error cells # Note: this is the default behavior onErrorCell(wb, XLC$ERROR.WARN) # Alternatively: wb$onErrorCell(XLC$ERROR.WARN) # Read named region MyData (with default header = TRUE) data <- readNamedRegion(wb, name = "MyData")

54
# Now set error behavior to XLC$ERROR.STOP to immediately # issue an exception and stop in case an error cell is # detected onErrorCell(wb, XLC$ERROR.STOP) # Alternatively: wb$onErrorCell(XLC$ERROR.STOP) # Read (again) named region MyData (with default header = TRUE) res <- try(readNamedRegion(wb, name = "MyData")) # Did we get an error? print(is(res, "try-error"))

print-methods

print-methods

Print a workbooks lename

Description Prints the workbooks underlying lename. Usage ## S4 method for signature workbook print(x,...) Arguments x ... Details Prints the specied workbooks lename (see also the S4 filename slot of the workbook class). Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook Examples
# Load existing demo Excel file mtcars.xlsx from the XLConnect package wb.mtcars <- loadWorkbook(system.file("demoFiles/mtcars.xlsx", package = "XLConnect")) # Print the workbooks underlying filename print(wb.mtcars)

The workbook to print Arguments passed on to standard print

readNamedRegion

55

readNamedRegion

Reading named regions from a workbook

Description Reads named regions from a workbook. Usage

## S4 method for signature workbook readNamedRegion(object, name, header, rownames, colTypes, forceConversion, dateTimeFormat, check.nam Arguments object name header rownames The workbook to use The name of the named region to read The argument header species if the rst row should be interpreted as column names. The default value is TRUE. 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. Column types to use when reading in the data. Specied as a character vector of the corresponding type names (see XLC; XLC$DATA_TYPE.<?>). You may also use R class names such as numeric, character, logical and POSIXt. The types are applied in the given order to the columns - elements are recycled if necessary. Defaults to character( ) meaning that column types are determined automatically (see the Note section for more information). By default, type conversions are only applied if the specied column type is a more generic type (e.g. from Numeric to String) - otherwise NA is returned. The forceConversion ag can be set to force conversion into less generic types where possible. logical specifying if conversions to less generic types should be forced. Defaults to FALSE meaning that if a column is specied to be of a certain type via the colTypes argument and a more generic type is detected in the column, then NA will be returned (example: column is specied to be DateTime but a more generic String is found). Specifying forceConversion = TRUE will try to enforce a conversion - if it succeeds the corresponding (converted) value will be returned, otherwise NA. See the Note section for some additional information. dateTimeFormat Date/time format used when doing date/time conversions. Defaults to getOption("XLConnect.dateTimeFormat"). This should be a POSIX format specier according to strptime although not all specications have been implemented yet - the most important ones however are available.

colTypes

forceConversion

56 check.names

readNamedRegion 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 data.frame. Defaults to TRUE. logical specifying whether to read cached formula results from the workbook instead of re-evaluating them. This is particularly helpful in cases for reading data produced by Excel features not supported in XLConnect like references to external workbooks. Defaults to FALSE, which means that formulas will be evaluated by XLConnect. keep List of column names or indices to be kept in the output data frame. It is possible to specify either keep or drop, but not both at the same time. Defaults to NULL. If a vector is passed as argument, it will be wrapped into a list. This list gets replicated to match the length of the other arguments. Example: if name = c("NamedRegion1", "NamedRegion2", "NamedRegion3") and keep = c(1,2), keep will be internally converted into list(c(1,2)) and then replicated to match the number of named regions, i.e. keep = list(c(1,2), c(1,2), c(1,2)). The result is that the rst two columns of each named region are kept. If keep = list(1,2) is specied, it will be replicated as list(1,2,1), i.e. respectively the rst, second and rst column of the named regions "NamedRegion1", "NamedRegion2", "NamedRegion3" will be kept. List of column names or indices to be dropped in the output data frame. It is possible to specify either keep or drop, but not both at the same time. Defaults to NULL. If a vector is passed as argument, it will be wrapped into a list. This list gets replicated to match the length of the other arguments. Example: if name = c("NamedRegion1", "NamedRegion2", "NamedRegion3") and drop = c(1,2), drop will be internally converted into list(c(1,2)) and then replicated to match the number of named regions, i.e. drop = list(c(1,2), c(1,2), c(1,2)). The result is that the rst two columns of each named region are dropped. If drop = list(1,2) is specied, it will be replicated as list(1,2,1), i.e. respectively the rst, second and rst column of the named regions "NamedRegion1", "NamedRegion2", "NamedRegion3" will be dropped.

useCachedValues

drop

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 specied, the return value is a (named) list of data.frames returned in the order they have been specied with the argument name. Note If no specic column types (see argument colTypes) are specied, readNamedRegion tries to determine the resulting column types based on the read cell types. If different cell types are found in a specic column, the most general of those is used and mapped to the corresponding R data type. The order of data types from least to most general is Boolean (logical) < DateTime (POSIXct) < Numeric (numeric) < String (character). E.g. if a column is read that contains cells of type Boolean, Numeric and String then the resulting column in R would be character since character

readNamedRegion is the most general type.

57

Some additional information with respect to forcing data type conversion using forceConversion = TRUE: Forcing conversion from String to Boolean: TRUE is returned if and only if the target string is "true" (ignoring any capitalization). Any other string will return FALSE. Forcing conversion from Numeric to DateTime: since Excel understands Dates/Times as Numerics with some additional formatting, a conversion from a Numeric to a DateTime is actually possible. Numerics in this case represent the number of days since 1900-01-01. Fractional days represent hours, minutes, and seconds. Author(s) Martin Studer Thomas Themel Nicola Lambiase Mirai Solutions GmbH http://www.mirai-solutions.com 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=iAE9a uRtpM 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!

58

readNamedRegionFromFile
# 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") ## Example 3: # mtcars xlsx file from demoFiles subfolder of package XLConnect demoExcelFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(demoExcelFile) # Read the columns 1, 3 and 5 of the named region mtcars (with default header = TRUE) data <- readNamedRegion(wb, name = "mtcars", keep=c(1,3,5))

readNamedRegionFromFile Reading named regions from an Excel le (wrapper function)

Description Reads named regions from an Excel le. Usage readNamedRegionFromFile(file, name, header = "TRUE") Arguments file name header The le name of the workbook to read The name of the named region to read from The argument header species if the rst row should be interpreted as column names. The default value is TRUE.

Details This is a convenience wrapper to read named regions from a le without creating an intermediate workbook object. See readNamedRegion for more details. Author(s) Thomas Themel Mirai Solutions GmbH http://www.mirai-solutions.com

readWorksheet-methods See Also readNamedRegion, readWorksheetFromFile, writeNamedRegionToFile, writeWorksheetToFile, onErrorCell Examples

# multiregion xlsx file from demoFiles subfolder of package XLConnect demoExcelFile <- system.file("demoFiles/multiregion.xlsx", package = "XLConnect") # Load a single named region into a single data.frame. df <- readNamedRegionFromFile(demoExcelFile, name="Iris") # Load multiple regions at once - returns a (named) list # of data.frames. df <- readNamedRegionFromFile(demoExcelFile, name=c("Calendar", "Iris", "IQ"))

59

readWorksheet-methods Reading data from worksheets

Description Reads data from worksheets of a workbook. Usage

## S4 method for signature workbook,numeric readWorksheet(object,sheet,startRow,startCol,endRow,endCol,autofitRow,autofitCol,region,header,rowna ## S4 method for signature workbook,character readWorksheet(object,sheet,startRow,startCol,endRow,endCol,autofitRow,autofitCol,region,header,rowna Arguments object sheet startRow startCol endRow endCol autofitRow The workbook to use The name or index of the worksheet to read from The index of the rst row to read from. Defaults to is determined automatically. meaning that the start row meaning that the start

The index of the rst column to read from. Defaults to column is determined automatically. The index of the last row to read from. Defaults to is determined automatically.

meaning that the end row meaning that the end

The index of the last column to read from. Defaults to column is determined automatically.

logical specifying if leading and trailing empty rows should be skipped. Defaults to TRUE.

60 autofitCol region

readWorksheet-methods logical specifying if leading and trailing empty columns should be skipped. Defaults to TRUE. A range specier in the form A10:B18. This provides an alternative way to specify startRow, startCol, endRow and endCol. Range specications take precedence over index specications. Interpret the rst row of the specied area as column headers. The default is TRUE. 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. Column types to use when reading in the data. Specied as a character vector of the corresponding type names (see XLC; XLC$DATA_TYPE.<?>). You may also use R class names such as numeric, character, logical and POSIXt. The types are applied in the given order to the columns - elements are recycled if necessary. Defaults to character( ) meaning that column types are determined automatically (see the Note section for more information). By default, type conversions are only applied if the specied column type is a more generic type (e.g. from Numeric to String) - otherwise NA is returned. The forceConversion ag can be set to force conversion into less generic types where possible. logical specifying if conversions to less generic types should be forced. Defaults to FALSE meaning that if a column is specied to be of a certain type via the colTypes argument and a more generic type is detected in the column, then NA will be returned (example: column is specied to be DateTime but a more generic String is found). Specifying forceConversion = TRUE will try to enforce a conversion - if it succeeds the corresponding (converted) value will be returned, otherwise NA. See the Note section for some additional information. dateTimeFormat Date/time format used when doing date/time conversions. Defaults to getOption("XLConnect.dateTimeFormat"). This should be a POSIX format specier according to strptime although not all specications have been implemented yet - the most important ones however are available. check.names logical specifying if column names of the resulting data.frame should be checked to ensure that they are syntactically valid variable names and are not duplicated. See the check.names argument of data.frame. Defaults to TRUE. logical specifying whether to read cached formula results from the workbook instead of re-evaluating them. This is particularly helpful in cases for reading data produced by Excel features not supported in XLConnect like references to external workbooks. Defaults to FALSE, which means that formulas will be evaluated by XLConnect. keep Vector of column names or indices to be kept in the output data frame. It is possible to specify either keep or drop, but not both at the same time. Defaults to NULL. If a vector is passed as argument, it will be wrapped into a list. This list gets replicated to match the length of the other arguments. Example: if sheet = c("Sheet1", "Sheet2", "Sheet3") and keep = c(1,2), keep

header rownames

colTypes

forceConversion

useCachedValues

readWorksheet-methods

61

will be internally converted into list(c(1,2)) and then replicated to match the number of sheets, i.e. keep = list(c(1,2), c(1,2), c(1,2)). The result is that the rst two columns of each sheet are kept. If keep = list(1,2) is specied, it will be replicated as list(1,2,1), i.e. respectively the rst, second and rst column of the sheets "Sheet1", "Sheet2", "Sheet3" will be kept. drop Vector of column names or indices to be dropped in the output data frame. It is possible to specify either keep or drop, but not both at the same time. Defaults to NULL. If a vector is passed as argument, it will be wrapped into a list. This list gets replicated to match the length of the other arguments. Example: if sheet = c("Sheet1", "Sheet2", "Sheet3") and drop = c(1,2), drop will be internally converted into list(c(1,2)) and then replicated to match the number of sheets, i.e. drop = list(c(1,2), c(1,2), c(1,2)). The result is that the rst two columns of each sheet are dropped. If drop = list(1,2) is specied, it will be replicated as list(1,2,1), i.e. respectively the rst, second and rst column of the sheets "Sheet1", "Sheet2", "Sheet3" will be dropped.

Details Reads data from the worksheet specied by sheet. Data is read starting at the top left corner specied by startRow and startCol down to the bottom right corner specied by endRow and endCol. If header = TRUE, the rst row is interpreted as column names of the resulting data.frame. If startRow <= then the rst available row in the sheet is assumed. If endRow <= then the last available row in the sheet is assumed. If startCol <= then the minimum column between startRow and endRow is assumed. If endCol <= then the maximum column between startRow and endRow is assumed. In other words, if no boundaries are specied readWorksheet assumes the "bounding box" of the data as the corresponding boundaries. The arguments autofitRow and autofitCol (both defaulting to TRUE) can be used to skip leading and trailing empty rows even in case startRow, endRow, startCol and endCol are specied to values > . This can be useful if data is expected within certain given boundaries but the exact location is not available.

If all four coordinate arguments are missing this behaves as above with startRow = , startCol = , endRow = and endCol = . In this case readWorksheet assumes the "bounding box" of the data as the corresponding boundaries.

All arguments (except object) are vectorized. As such, multiple worksheets (and also multiple data regions from the same worksheet) can be read with one method call. If only one single data region is read, the return value is a data.frame. If multiple data regions are specied, the return value is a list of data.frames returned in the order they have been specied. If worksheets have been specied by name, the list will be a named list named by the corresponding worksheets. Note If no specic column types (see argument colTypes) are specied, readWorksheet tries to determine the resulting column types based on the read cell types. If different cell types are found in a specic column, the most general of those is used and mapped to the corresponding R data type.

62

readWorksheet-methods The order of data types from least to most general is Boolean (logical) < DateTime (POSIXct) < Numeric (numeric) < String (character). E.g. if a column is read that contains cells of type Boolean, Numeric and String then the resulting column in R would be character since character is the most general type. Some additional information with respect to forcing data type conversion using forceConversion = TRUE: Forcing conversion from String to Boolean: TRUE is returned if and only if the target string is "true" (ignoring any capitalization). Any other string will return FALSE. Forcing conversion from Numeric to DateTime: since Excel understands Dates/Times as Numerics with some additional formatting, a conversion from a Numeric to a DateTime is actually possible. Numerics in this case represent the number of days since 1900-01-01. Fractional days represent hours, minutes, and seconds.

Author(s) Martin Studer Thomas Themel Nicola Lambiase Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, writeWorksheet, readNamedRegion, writeNamedRegion, readWorksheetFromFile, 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 worksheet mtcars (providing no specific area bounds; # with default header = TRUE) data <- readWorksheet(wb, sheet = "mtcars")

## Example 2: # mtcars xlsx file from demoFiles subfolder of package XLConnect demoExcelFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(demoExcelFile) # Read worksheet mtcars (providing area bounds; with default header = TRUE) data <- readWorksheet(wb, sheet = "mtcars", startRow = 1, startCol = 3, endRow = 15, endCol = 8)

readWorksheetFromFile

63

## Example 3: # mtcars xlsx file from demoFiles subfolder of package XLConnect demoExcelFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(demoExcelFile) # Read worksheet mtcars (providing area bounds using the region argument; # with default header = TRUE) data <- readWorksheet(wb, sheet = "mtcars", region = "C1:H15")

## Example 4: # conversion xlsx file from demoFiles subfolder of package XLConnect excelFile <- system.file("demoFiles/conversion.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(excelFile) # Read worksheet 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 <- readWorksheet(wb, sheet = "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") ## Example 5: # mtcars xlsx file from demoFiles subfolder of package XLConnect demoExcelFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(demoExcelFile) # Read the columns 1, 3 and 5 from the sheet mtcars (with default header = TRUE) data <- readWorksheet(wb, sheet = "mtcars", keep=c(1,3,5))

readWorksheetFromFile Reading data from worksheets in an Excel le (wrapper function)

Description Reads data from worksheets in an Excel le. Usage readWorksheetFromFile(file, ...)

64 Arguments file ... The path name of the le to read from. Arguments passed to readWorksheet

readWorksheetFromFile

Details See readWorksheet for more information.

Author(s) Thomas Themel Mirai Solutions GmbH http://www.mirai-solutions.com

See Also readWorksheet, readNamedRegionFromFile, writeWorksheetToFile, writeNamedRegionToFile, onErrorCell

Examples
# multiregion xlsx file from demoFiles subfolder of # package XLConnect demoExcelFile <- system.file("demoFiles/multiregion.xlsx", package = "XLConnect") # Read single area from first sheet of existing file, # "B2:C3" in Excel speak df.one <- readWorksheetFromFile(demoExcelFile, sheet = 1, header = FALSE, startCol = 2, startRow = 2, endCol = 3, endRow = 3) # Read three data sets in one from known positions dflist <- readWorksheetFromFile(demoExcelFile, sheet = c("FirstSheet", "FirstSheet", "SecondSheet"), header = TRUE, startRow = c(2,2,3), startCol = c(2,5,2), endCol = c(5,8,6), endRow = c(9,15,153))

removeName-methods

65

removeName-methods

Removing names from workbooks

Description Removes a name from a workbook. Usage ## S4 method for signature workbook removeName(object,name) Arguments object name Details Removes the name named name from the specied workbook object if it does exist. Multiple names can be specied to be removed. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, createName, existsName, getDefinedNames, readNamedRegion, writeNamedRegion Examples
# mtcars xlsx file from demoFiles subfolder of package XLConnect mtcarsFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(mtcarsFile) # Remove the named region called mtcars from the above file # (this named region is defined as mtcars!$A$1:$K$33) removeName(wb, name = "mtcars")

The workbook to use The name to delete

66

removePane-methods

removePane-methods

Removing panes from worksheet

Description Removes the split pane/freeze pane from the specied worksheet. Usage ## S4 method for signature workbook,character removePane(object,sheet) ## S4 method for signature workbook,numeric removePane(object,sheet) Arguments object sheet Note To keep an area of a worksheet visible while you scroll to another area of the worksheet, you can lock specic rows or columns in one area by freezing or splitting panes. When you freeze panes, you keep specic rows or columns visible when you scroll in the worksheet. For example, you might want to keep row and column labels visible as you scroll. When you split panes, you create separate worksheet areas that you can scroll within, while rows or columns in the non-scrolled area remain visible. Author(s) Nicola Lambiase Mirai Solutions GmbH http://www.mirai-solutions.com References How to create a freeze pane/split pane in Ofce 2007 http://office.microsoft.com/en-us/ excel-help/freeze-or-lock-rows-and-columns-HP 1217 48.aspx See Also workbook createFreezePane createSplitPane The workbook to use The name or index of the sheet from which to remove the split pane/freeze pane

removeSheet-methods Examples
# Load workbook (create if not existing) wb <- loadWorkbook("removePaneTest.xlsx", create = TRUE) # Create a worksheet named Sheet1 createSheet(wb, name = "Sheet1") # Create a split pane on Sheet1, with coordinates (1 # 1 (-> J) as left column visible in right pane and 1 createSplitPane(wb, "Sheet1", 1 , 5 , 1 , 1 ) # Remove the split pane from Sheet1 removePane(wb, "Sheet1")

67

, 5 ) expressed as 1/2 th of a point, as top row visible in bottom pane

# Save workbook (this actually writes the file to disk). Now the workbook has no split pane. saveWorkbook(wb)

removeSheet-methods

Removing worksheets from workbooks

Description Removes a worksheet from a workbook. Usage ## S4 method for signature workbook,character removeSheet(object,sheet) ## S4 method for signature workbook,numeric removeSheet(object,sheet) Arguments object sheet Note When removing a worksheet that is the currently active sheet then XLConnect resets the active sheet to the rst possible worksheet in the workbook. Also note that deleting worksheets may result in invalid name references. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com The workbook to use The name or index of the sheet to remove

68 See Also

renameSheet-methods

workbook, createSheet, existsSheet, getSheets, renameSheet, cloneSheet, setActiveSheet Examples

# mtcars xlsx file from demoFiles subfolder of package XLConnect mtcarsFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(mtcarsFile) # Remove the worksheet called mtcars from the above file removeSheet(wb, sheet = "mtcars")

renameSheet-methods

Renaming worksheets from workbooks

Description Renames a worksheet from a workbook. Usage ## S4 method for signature workbook,character renameSheet(object,sheet,newName) ## S4 method for signature workbook,numeric renameSheet(object,sheet,newName) Arguments object sheet newName Note Note that renaming worksheets may result in invalid name references. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, createSheet, existsSheet, getSheets, removeSheet, cloneSheet, setActiveSheet The workbook to use The name or index of the sheet to rename The new name of the sheet

runUnitTests Examples
# mtcars xlsx file from demoFiles subfolder of package XLConnect mtcarsFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(mtcarsFile) # Rename the worksheet called mtcars from the above file to MyCars renameSheet(wb, sheet = "mtcars", newName = "MyCars")

69

runUnitTests

XLConnect Unit Testing Framework

Description Runs XLConnects unit testing suite. Usage runUnitTests() Details This function runs XLConnects unit test suite as dened by the unit tests implemented in the unitTests subfolder of the XLConnect library. Text and HTML protocols are produced - the HTML version should be opened automatically once the test suite completed execution. Note Running XLConnects unit test suite requires the RUnit package to be installed. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com References developers:runit http://rwiki.sciviews.org/doku.php?id=developers:runit CRAN: RUnit http://cran.r-project.org/web/packages/RUnit/index.html Examples
runUnitTests()

70

saveWorkbook-methods

saveWorkbook-methods

Saving Microsoft Excel workbooks

Description Saves a workbook to the corresponding Excel le. This method actually writes the workbook object to disk. Usage ## S4 method for signature workbook,missing saveWorkbook(object,file) ## S4 method for signature workbook,character saveWorkbook(object,file) Arguments object file The workbook to save The le to which to save the workbook ("save as"). If not specied (missing), the workbook will be saved to the workbooks underlying le which is the le specied in loadWorkbook (also see the workbook class for more information). Note that due to currently missing functionality in Apache POI, workbooks can only be saved in the same le format - i.e. if the workbooks underlying le format is xls, then the file argument may only specify another xls le. Also note that when specifying the file argument the workbooks underlying lename changes to reect the "save as" behavior. Paths are expanded using path.expand.

Details Saves the specied workbook object to disk. Note As already mentioned in the documentation of the workbook class, a workbooks underlying Excel le is not saved (or being created in case the le did not exist and create = TRUE has been specied) unless the saveWorkbook method has been called on the object. This provides more exibility to the user to decide when changes are saved and also provides better performance in that several changes can be written in one go (normally at the end, rather than after every operation causing the le to be rewritten again completely each time). This is due to the fact that workbooks are manipulated in-memory and are only written to disk with specically calling saveWorkbook. Further note that calling saveWorkbook more than once leads to an exception. This is due to a current issue in the underlying POI libraries. However, with XLConnect there should be no need to call saveWorkbook more than once so virtually this is no issue.

setActiveSheet-methods Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, loadWorkbook Examples
# Create a new workbook saveMe.xlsx # (assuming the file to not exist already) wb <- loadWorkbook("saveMe.xlsx", create = TRUE) # Create a worksheet called mtcars createSheet(wb, name = "mtcars") # Write built-in dataset mtcars to sheet mtcars created above writeWorksheet(wb, mtcars, sheet = "mtcars") # Save workbook - this actually writes the file saveMe.xlsx to disk saveWorkbook(wb)

71

setActiveSheet-methods Setting the active worksheet in a workbook

Description Sets the active worksheet of a workbook. Usage ## S4 method for signature workbook,character setActiveSheet(object,sheet) ## S4 method for signature workbook,numeric setActiveSheet(object,sheet) Arguments object sheet Note The active worksheet of a workbook is the worksheet that is displayed when the corresponding Excel le is opened. The workbook to use The name or index of the sheet to activate

72 Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also

setAutoFilter-methods

workbook, createSheet, removeSheet, renameSheet, existsSheet, getSheets Examples

# mtcars xlsx file from demoFiles subfolder of package XLConnect mtcarsFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(mtcarsFile) # Sets the active sheet to the sheet mtcars3 setActiveSheet(wb, sheet = "mtcars3")

setAutoFilter-methods Setting auto-lters on worksheets

Description Sets an auto-lter on a specied worksheet. Usage ## S4 method for signature workbook,character setAutoFilter(object,sheet,reference) ## S4 method for signature workbook,numeric setAutoFilter(object,sheet,reference) Arguments object sheet reference Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook The workbook to use The name or index of the sheet on which to set the auto-lter A cell range specication (character) in the form A1:B8

setBorder-methods Examples
# Load workbook (create if not existing) wb <- loadWorkbook("autofilter.xlsx", create = TRUE) # Create a worksheet named mtcars createSheet(wb, name = "mtcars") # Create a named region called mtcars on the sheet called mtcars createName(wb, name = "mtcars", formula = "mtcars!$A$1") # Write built-in data set mtcars to the above defined named region # (using header = TRUE) writeNamedRegion(wb, mtcars, name = "mtcars") # Set an auto-filter for the named region written above setAutoFilter(wb, sheet = "mtcars", reference = aref("A1", dim(mtcars))) # Save workbook (this actually writes the file to disk) saveWorkbook(wb)

73

setBorder-methods

Specifying borders for cell styles

Description Species borders for a cellstyle. Usage ## S4 method for signature cellstyle setBorder(object,side,type,color) Arguments object side type color Details Species the border for a cellstyle. Note that the arguments type and color should be of the same length as side. In other words, for each specied side there should be a corresponding specication of type and color. If this is not the case the arguments will be automatically replicated to the length of side. The cellstyle to edit A vector with any combination of {"bottom", "left", "right", "top", "all"} Species the border type to be used - it is normally specied by a corresponding XLC constant (see the XLC border constant, e.g. XLC$"BORDER.MEDIUM_DASHED") Denes the border color and is normally also specied via an XLC constant.

74 Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, cellstyle, setCellStyle, setStyleAction, XLC Examples
# Load workbook (create if not existing) wb <- loadWorkbook("setBorder.xlsx", create = TRUE) # Create a worksheet createSheet(wb, name = "cellstyles") # Create a custom anonymous cell style cs <- createCellStyle(wb)

setCellFormula-methods

# Specify the border for the cell style created above setBorder(cs, side = c("bottom", "right"), type = XLC$"BORDER.THICK", color = c(XLC$"COLOR.BLACK", XLC$"COLOR.RED")) # Set the cell style created above for the top left cell (A1) in the # cellstyles worksheet setCellStyle(wb, sheet = "cellstyles", row = 1, col = 1, cellstyle = cs) # Save the workbook saveWorkbook(wb)

setCellFormula-methods Setting cell formulas

Description Sets cell formulas for specic cells in a workbook. Usage ## S4 method for signature workbook,character setCellFormula(object,sheet,row,col,formula) ## S4 method for signature workbook,numeric setCellFormula(object,sheet,row,col,formula)

setCellFormula-methods Arguments object sheet row col formula Details Note that the arguments are vectorized such that multiple cells can be set with one method call. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, getCellFormula, Examples
# Load workbook (create if not existing) wb <- loadWorkbook("setCellFormula.xls", create = TRUE) # Create a sheet named mtcars createSheet(wb, name = "mtcars") # Create a named region called mtcars referring to the sheet # called mtcars createName(wb, name = "mtcars", formula = "mtcars!$A$1") # Write built-in data set mtcars to the above defined named region. writeNamedRegion(wb, mtcars, name = "mtcars") # Now, let us get Excel to calculate average weights. # Where did we write the dataset? corners <- getReferenceCoordinates(wb, "mtcars") # Put the average under the wt column colIndex <- which(names(mtcars) == "wt") rowIndex <- corners[2,1] + 1 # Construct the input range & formula input <- paste(idx2cref(c(corners[1,1], colIndex, corners[2,1], colIndex)), collapse=":") formula <- paste("AVERAGE(", input, ")", sep="") setCellFormula(wb, "mtcars", rowIndex, colIndex, formula) # Save workbook (this actually writes the file to disk) saveWorkbook(wb)

75

The workbook to use Name or index of the sheet the cell is on Row index of the cell to edit Column index of the cell to edit The formula to apply to the cell, without the initial = character used in Excel

76

setCellStyle-methods

setCellStyle-methods

Setting cell styles

Description Sets cell styles for specic cells in a workbook. Usage ## S4 method for signature workbook,missing,character setCellStyle(object,formula,sheet,row,col,cellstyle) ## S4 method for signature workbook,missing,numeric setCellStyle(object,formula,sheet,row,col,cellstyle) ## S4 method for signature workbook,character,missing setCellStyle(object,formula,sheet,row,col,cellstyle) Arguments object formula sheet row col cellstyle Details Sets the specied cellstyle for the specied cell (row, col) on the specied sheet or alternatively for the cells referred to by formula. Note that the arguments are vectorized such that multiple cells can be styled with one method call. Use either the argument formula or the combination of sheet, row and col. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, cellstyle, createCellStyle, setDataFormat, setBorder, setFillBackgroundColor, setFillForegroundColor, setFillPattern, setWrapText The workbook to use A formula specication in the form Sheet!B8:C17. Use either the argument formula or the combination of sheet, row and col. Name or index of the sheet the cell is on. Use either the argument formula or the combination of sheet, row and col. Row index of the cell to apply the cellstyle to. Column index of the cell to apply the cellstyle to. cellstyle to apply

setCellStyle-methods Examples
# Load workbook (create if not existing) wb <- loadWorkbook("setCellStyle.xlsx", create = TRUE) # We dont set a specific style action in this demo, so the default # XLConnect will be used (XLC$"STYLE_ACTION.XLCONNECT") # Create a sheet named mtcars createSheet(wb, name = "mtcars") # Create a named region called mtcars referring to the sheet # called mtcars createName(wb, name = "mtcars", formula = "mtcars!$C$4") # Write built-in data set mtcars to the above defined named region. # This will use the default style action XLConnect. writeNamedRegion(wb, mtcars, name = "mtcars") # Now lets color all weight cells of cars with a weight > 3.5 in red # (mtcars$wt > 3.5) # First, create a corresponding (named) cell style heavyCar <- createCellStyle(wb, name = "HeavyCar") # Specify the cell style to use a solid foreground color setFillPattern(heavyCar, fill = XLC$"FILL.SOLID_FOREGROUND") # Specify the foreground color to be used setFillForegroundColor(heavyCar, color = XLC$"COLOR.RED") # Which cars have a weight > 3.5 ? rowIndex <- which(mtcars$wt > 3.5) # NOTE: The mtcars data.frame has been written offset with # top left cell C4 - and we have also written a header row! # So, lets take that into account appropriately. Obviously, # the two steps could be combined directly into one ... rowIndex <- rowIndex + 4 # The same holds for the column index colIndex <- which(names(mtcars) == "wt") + 2 # Set the HeavyCar cell style for the corresponding cells. # Note: the row and col arguments are vectorized! setCellStyle(wb, sheet = "mtcars", row = rowIndex, col = colIndex, cellstyle = heavyCar) # Save workbook (this actually writes the file to disk) saveWorkbook(wb)

77

78

setColumnWidth-methods

setColumnWidth-methods Setting the width of a column in a worksheet

Description Sets the width of a column in a worksheet. Usage ## S4 method for signature workbook,character setColumnWidth(object,sheet,column,width) ## S4 method for signature workbook,numeric setColumnWidth(object,sheet,column,width) Arguments object sheet column width The workbook to use The name or index of the sheet The index of the column to resize The width of the specied column in units of 1/256th of a character width. If width = -1 (default), the column is auto-sized. If negative otherwise, the column will be sized to the sheets default column width.

Details Note that the arguments sheet, column and width are vectorized. As such the column width of multiple columns (potentially on different sheets) can be set with one method call. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, setRowHeight Examples
# mtcars xlsx file from demoFiles subfolder of package XLConnect mtcarsFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(mtcarsFile) # Sets the column width of the 3rd column on sheet mtcars # to 4 /256th (= 15.625) character width setColumnWidth(wb, sheet = "mtcars", column = 3, width = 4

setDataFormat-methods

79

setDataFormat-methods Specifying custom data formats for cell styles

Description Species a custom data format for a cellstyle. Usage ## S4 method for signature cellstyle setDataFormat(object,format) Arguments object format Details Species the data format to be used by the corresponding cellstyle. Data formats are specied the standard Excel way. Refer to the Excel help or to the link below for more information. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com References Excel custom data formats: http://www.ozgrid.com/Excel/CustomFormats.htm See Also workbook, cellstyle, setCellStyle, setStyleAction Examples
# Load workbook (create if not existing) wb <- loadWorkbook("setDataFormat.xlsx", create = TRUE) # Create a worksheet createSheet(wb, name = "cellstyles") # Create a dummy data set with the current date/time (as POSIXct) now <- data.frame(Now = Sys.time()) # Write the value to the cellstyles worksheet in the top left # corner (cell A1)

The cellstyle to use A data format string

80
writeWorksheet(wb, now, sheet = "cellstyles", startRow = 1, startCol = 1, header = FALSE) # Create a custom anonymous cell style cs <- createCellStyle(wb) # Specify a custom data format setDataFormat(cs, format = "dddd d-m-yyyy h:mm AM/PM")

setDataFormatForType-methods

# Set the cell style created above for the top left cell (A1) in # the cellstyles worksheet setCellStyle(wb, sheet = "cellstyles", row = 1, col = 1, cellstyle = cs) # Set column width to display whole time/date string setColumnWidth(wb, sheet = "cellstyles", column = 1, width = 6 # Save the workbook saveWorkbook(wb)

setDataFormatForType-methods Setting the data format for the DATA_FORMAT_ONLY style action

Description Sets the data format for a specic data type as used by the DATA_FORMAT_ONLY style action. Usage ## S4 method for signature workbook setDataFormatForType(object,type,format) Arguments object type format Details Based on the (cell) data type the DATA_FORMAT_ONLY style action (see setStyleAction) sets the data format for the corresponding cells. The data type is normally specied via a corresponding data type constant from the XLC object. Data formats are specied the standard Excel way. Refer to the Excel help or to the link below for more information. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com The workbook to use The data type for which to set the format. A data format string

setFillBackgroundColor-methods References Excel custom data formats: http://www.ozgrid.com/Excel/CustomFormats.htm See Also workbook, setStyleAction Examples
# Copy existing Excel template to working directory file.copy(system.file("demoFiles/template2.xlsx", package = "XLConnect"), "dataformat.xlsx", overwrite = TRUE) # Load workbook wb <- loadWorkbook("dataformat.xlsx") # Set the data format for numeric columns (cells) # (keeping the defaults for all other data types) setDataFormatForType(wb, type = XLC$"DATA_TYPE.NUMERIC", format = " . ") # Set style action to data format only setStyleAction(wb, XLC$"STYLE_ACTION.DATA_FORMAT_ONLY") # Write built-in data set mtcars to the named region # mtcars as defined by the Excel template. writeNamedRegion(wb, mtcars, name = "mtcars") # Save workbook saveWorkbook(wb)

81

setFillBackgroundColor-methods Specifying the ll background color for cell styles

Description Species the ll background color for a cellstyle. Usage ## S4 method for signature cellstyle,numeric setFillBackgroundColor(object,color)

82 Arguments object color The cellstyle to manipulate

setFillForegroundColor-methods

The ll background color to use for the cellstyle. The color is normally specied via a corresponding color constant from the XLC object.

Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, cellstyle, setCellStyle, setStyleAction, XLC Examples
# Load workbook (create if not existing) wb <- loadWorkbook("setFillBackgroundColor.xlsx", create = TRUE) # Create a worksheet createSheet(wb, name = "cellstyles") # Create a custom anonymous cell style cs <- createCellStyle(wb) # Specify the fill background color for the cell style created above setFillBackgroundColor(cs, color = XLC$"COLOR.CORNFLOWER_BLUE") # Specify the fill foreground color setFillForegroundColor(cs, color = XLC$"COLOR.YELLOW") # Specify the fill pattern setFillPattern(cs, fill = XLC$"FILL.BIG_SPOTS") # Set the cell style created above for the top left cell (A1) in the # cellstyles worksheet setCellStyle(wb, sheet = "cellstyles", row = 1, col = 1, cellstyle = cs) # Save the workbook saveWorkbook(wb)

setFillForegroundColor-methods Specifying the ll foreground color for cell styles

Description Species the ll foreground color for a cellstyle.

setFillForegroundColor-methods Usage ## S4 method for signature cellstyle,numeric setFillForegroundColor(object,color) Arguments object color The cellstyle to manipulate

83

The ll foreground color to use for the cellstyle. The color is normally specied via a corresponding color constant from the XLC object.

Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, cellstyle, setCellStyle, setStyleAction, XLC Examples
# Load workbook (create if not existing) wb <- loadWorkbook("setFillForegroundColor.xlsx", create = TRUE) # Create a worksheet createSheet(wb, name = "cellstyles") # Create a custom anonymous cell style cs <- createCellStyle(wb) # Specify the fill background color for the cell style created above setFillBackgroundColor(cs, color = XLC$"COLOR.CORNFLOWER_BLUE") # Specify the fill foreground color setFillForegroundColor(cs, color = XLC$"COLOR.YELLOW") # Specify the fill pattern setFillPattern(cs, fill = XLC$"FILL.BIG_SPOTS") # Set the cell style created above for the top left cell (A1) in the # cellstyles worksheet setCellStyle(wb, sheet = "cellstyles", row = 1, col = 1, cellstyle = cs) # Save the workbook saveWorkbook(wb)

84

setFillPattern-methods

setFillPattern-methods Specifying the ll pattern for cell styles

Description Species the ll pattern for a cellstyle. Usage ## S4 method for signature cellstyle setFillPattern(object,fill) Arguments object fill The cellstyle to manipulate The ll pattern to use for the cellstyle. fill is normally specied via a corresponding ll constant from the XLC object.

Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, cellstyle, setCellStyle, setStyleAction, XLC Examples
# Load workbook (create if not existing) wb <- loadWorkbook("setFillPattern.xlsx", create = TRUE) # Create a worksheet createSheet(wb, name = "cellstyles") # Create a custom anonymous cell style cs <- createCellStyle(wb) # Specify the fill background color for the cell style created above setFillBackgroundColor(cs, color = XLC$"COLOR.CORNFLOWER_BLUE") # Specify the fill foreground color setFillForegroundColor(cs, color = XLC$"COLOR.YELLOW") # Specify the fill pattern setFillPattern(cs, fill = XLC$"FILL.BIG_SPOTS") # Set the cell style created above for the top left cell (A1) in the

setForceFormulaRecalculation-methods
# cellstyles worksheet setCellStyle(wb, sheet = "cellstyles", row = 1, col = 1, cellstyle = cs) # Save the workbook saveWorkbook(wb)

85

setForceFormulaRecalculation-methods Forcing Excel to recalculate formula values when opening a workbook

Description This function controls a ag that forces Excel to recalculate formula values when a workbook is opened. Usage ## S4 method for signature workbook,character setForceFormulaRecalculation(object,sheet,value) ## S4 method for signature workbook,numeric setForceFormulaRecalculation(object,sheet,value) Arguments object sheet value Details The arguments sheet and value are vectorized such that multiple worksheets can be controlled with one method call. Note A typical use for this ag is forcing Excel into updating formulas that reference cells affected by writeWorksheet or writeNamedRegion. The exact behavior of Excel when the ag is set depends on version and le format. Author(s) Thomas Themel Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, getForceFormulaRecalculation The workbook to use The name or index of the sheet for which to force formula recalculation. If sheet = "*", the ag is set for all sheets in the workbook. logical specifying if formula recalculation should be forced or not

86 Examples

setMissingValue-methods

# mtcars xlsx file from demoFiles subfolder of package XLConnect demoExcelFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(demoExcelFile) # Tell Excel to automatically recalculate formulas on sheet mtcars setForceFormulaRecalculation(wb, sheet = "mtcars", TRUE) # The same with a numerical sheet index setForceFormulaRecalculation(wb, sheet = 1, TRUE)

setMissingValue-methods Setting missing value identiers

Description Denes the set of missing values (character or numeric) used when reading and writing data. Usage ## S4 method for signature workbook,ANY setMissingValue(object,value) Arguments object value The workbook to use vector or list of missing value identiers (either character or numeric) that are recognized as missing (NA) when reading data. The rst element of this vector will be used as missing value identier when writing data. If value = NULL (default), missing values are represented by blank cells and only blank cells are recognized as missing.

Details If there are no specic missing value identiers dened the default behavior is to map missing values to blank (empty) cells. Otherwise, each string or numeric cell is checked if it matches one of the dened missing value identiers. In addition, the rst missing value identier (i.e. the rst element of the value argument) is used to represent missing values when writing data. Note that the missing value identiers have to be either character or numeric. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com

setRowHeight-methods See Also workbook, writeNamedRegion, writeWorksheet Examples

# Load workbook (create if not existing) wb <- loadWorkbook("missingValue.xlsx", create = TRUE) # Create a worksheet named airquality createSheet(wb, name = "airquality") # Create a named region called airquality on the sheet called # airquality createName(wb, name = "airquality", formula = "airquality!$A$1") # Set the missing value string to missing setMissingValue(wb, value = "missing") # Write built-in data set airquality to the above defined named region writeNamedRegion(wb, airquality, name = "airquality") # Save workbook saveWorkbook(wb)

87

setRowHeight-methods

Setting the height of a row in a worksheet

Description Sets the height of a row in a worksheet. Usage ## S4 method for signature workbook,character setRowHeight(object,sheet,row,height) ## S4 method for signature workbook,numeric setRowHeight(object,sheet,row,height) Arguments object sheet row height The workbook to use The name or index of the sheet to edit The index of the row to resize The height in points. If height < sheets default row height. (default: -1), the row will be sized to the

88 Details

setSheetColor-methods

Note that the arguments sheet, row and height are vectorized. As such the row height of multiple rows (potentially on different worksheets) can be set with one method call. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, setColumnWidth Examples
# mtcars xlsx file from demoFiles subfolder of package XLConnect mtcarsFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(mtcarsFile) # Sets the row height of the 1st row on sheet mtcars # to 2 points setRowHeight(wb, sheet = "mtcars", row = 1, height = 2 )

setSheetColor-methods Setting colors on worksheet tabs

Description Sets a color on a specied worksheet tab. This only works for xlsx les. Usage ## S4 method for signature workbook,character setSheetColor(object,sheet,color) ## S4 method for signature workbook,numeric setSheetColor(object,sheet,color) Arguments object sheet color The workbook to use The name or index of the sheet on which to set the tab color The color to use for the sheet tab. The color is normally specied via a corresponding color constant from the XLC object.

setSheetPos-methods Author(s) Nicola Lambiase Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, XLC Examples
# Load workbook (create if not existing) wb <- loadWorkbook("sheetcolor.xlsx", create = TRUE) # Create a worksheet named Sheet1 createSheet(wb, name = "Sheet1") # Set the "Sheet1" tab color as red setSheetColor(wb, "Sheet1", XLC$COLOR.RED) # Create a worksheet named Sheet2 createSheet(wb, name = "Sheet2") # Set the tab color of the second workbook sheet as green setSheetColor(wb, 2, XLC$COLOR.GREEN) # Save workbook (this actually writes the file to disk) saveWorkbook(wb)

89

setSheetPos-methods

Setting worksheet position

Description Sets the position of a worksheets in a workbook. Usage ## S4 method for signature workbook,character,numeric setSheetPos(object,sheet,pos) Arguments object sheet The workbook to use The name of the worksheet (character) whose position to set. This argument is vectorized such that the positions of multiple worksheets can be set with one method call. The position index to set for the corresponding sheet. If missing, sheets will be positioned in the order they are specied in the argument sheet.

pos

90 Details

setStyleAction-methods

It is important to note that the worksheet positions will be applied one after the other in the order they have been specied. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, getSheetPos, getSheets Examples
# mtcars xlsx file from demoFiles subfolder of package XLConnect demoExcelFile <- system.file("demoFiles/mtcars.xlsx", package = "XLConnect") # Load workbook wb <- loadWorkbook(demoExcelFile) # Move the mtcars3 worksheet to the front setSheetPos(wb, sheet = "mtcars3", pos = 1)

setStyleAction-methods Controlling application of cell styles when writing data to Excel

Description Controls the application of cellstyles when writing data to Excel. Usage ## S4 method for signature workbook setStyleAction(object,type) Arguments object type The workbook to use Denes the style action to be used when writing data (writeNamedRegion, writeWorksheet) to the specied workbook object

setStyleAction-methods Details The following style actions are supported:

91

XLC$"STYLE_ACTION.XLCONNECT": This is the default. data.frame headers (if specied to be written) are colored in solid light grey (25 percent). character, numeric and logical vectors are written using Excels "General" data format. Time/date vectors e.g. Date or POSIXt) are written with the "mm/dd/yyyy hh:mm:ss" data format. All cells are specied to wrap the text if necessary. The corresponding custom cell styles are called XLConnect.Header, XLConnect.General and XLConnect.Date. XLC$"STYLE_ACTION.NONE": This style action instructs XLConnect to apply no cell styles when writing data. Cell styles are kept as they are. This is useful in a scenario where all styling is predened in an Excel template which is then only lled with data. XLC$"STYLE_ACTION.PREDEFINED": This style action instructs XLConnect to use existing (predened) cellstyles when writing headers and columns. This is useful in a templatebased approach where an Excel template with predened cellstyles for headers and columns is available. Normally, this would be used when the column dimensions (and potentially also the row dimensions) of the data tables are known up-front and as such a layout and corresponding cell styles can be pre-specied. If a data.frame is written including its header, it is assumed that the Excel le being written to has predened cellstyles in the header row. Furthermore, the rst row of data is assumed to contain the cell styles to be replicated for any additional rows. As such, this style action may only be useful if the same column cell style should be applied across all rows. Please refer to the available demos for some examples. XLC$"STYLE_ACTION.NAME_PREFIX": This style action instructs XLConnect to look for custom (named) cellstyles with a specied prex when writing columns and headers. This style name prex can be set via the method setStyleNamePrefix. For column headers, it rst checks if there is a cell style named <STYLE_NAME_PREFIX>.Header.<COLUMN_NAME> . If there is no such cell style, it checks for a cell style named <STYLE_NAME_PREFIX>.Header.<COLUMN_INDEX> . Again, if there is no such cell style, it checks for <STYLE_NAME_PREFIX>.Header (no specic column discrimination). As a nal resort, it just takes the workbook default cell style. For columns, XLConnect rst checks the availability of a cell style named <STYLE_NAME_PREFIX>.Column.<COLUMN_NAME> . If there is no such cell style, it checks for <STYLE_NAME_PREFIX>.Column.<COLUMN_INDEX> . If again there is no such cell style, it checks for <STYLE_NAME_PREFIX>.Column.<COLUMN_DATA_TYPE> with <COLUMN_DATA_TYPE> being the corresponding data type from the set: {Numeric, String, Boolean, DateTime} . As a last resort, it would make use of the workbooks default cell style.

92

setStyleAction-methods XLC$"STYLE_ACTION.DATA_FORMAT_ONLY": This style action instructs XLConnect to only set the data format for a cell but not to apply any other styling but rather keep the existing one. The data format to apply is determined by the data type of the cell (which is in turn determined by the corresponding R data type). The data format for a specic type can be set via the method setDataFormatForType. The default data format is "General" for the data types Numeric , String and Boolean and is "mm/dd/yyyy hh:mm:ss" for the data type DateTime .

Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, cellstyle, createCellStyle, writeNamedRegion, writeWorksheet, setStyleNamePrefix, setDataFormatForType Examples
# Load workbook (create if not existing) wb <- loadWorkbook("styleaction.xlsx", create = TRUE) # Set style action to name prefix setStyleAction(wb, XLC$"STYLE_ACTION.NAME_PREFIX") # Set the name prefix to MyPersonalStyle setStyleNamePrefix(wb, "MyPersonalStyle") # We now create a named cell style to be used for the header # (column names) of a data.frame headerCellStyle <- createCellStyle(wb, name = "MyPersonalStyle.Header") # Specify the cell style to use a solid foreground color setFillPattern(headerCellStyle, fill = XLC$"FILL.SOLID_FOREGROUND") # Specify the foreground color to be used setFillForegroundColor(headerCellStyle, color = XLC$"COLOR.LIGHT_CORNFLOWER_BLUE") # Specify a thick black bottom border setBorder(headerCellStyle, side = "bottom", type = XLC$"BORDER.THICK", color = XLC$"COLOR.BLACK") # We now create a named cell style to be used for # the column named wt (as you will see below, we will # write the built-in data.frame mtcars) wtColumnCellStyle <- createCellStyle(wb, name = "MyPersonalStyle.Column.wt") # Specify the cell style to use a solid foreground color

setStyleNamePrex-methods
setFillPattern(wtColumnCellStyle, fill = XLC$"FILL.SOLID_FOREGROUND") # Specify the foreground color to be used setFillForegroundColor(wtColumnCellStyle, color = XLC$"COLOR.LIGHT_ORANGE") # We now create a named cell style to be used for # the 3rd column in the data.frame wtColumnCellStyle <- createCellStyle(wb, name = "MyPersonalStyle.Column.3") # Specify the cell style to use a solid foreground color setFillPattern(wtColumnCellStyle, fill = XLC$"FILL.SOLID_FOREGROUND") # Specify the foreground color to be used setFillForegroundColor(wtColumnCellStyle, color = XLC$"COLOR.LIME") # Create a sheet named mtcars createSheet(wb, name = "mtcars") # Create a named region called mtcars referring to # the sheet called mtcars createName(wb, name = "mtcars", formula = "mtcars!$A$1") # Write built-in data set mtcars to the above defined named region. # The style action name prefix will be used when writing the data # as defined above. writeNamedRegion(wb, mtcars, name = "mtcars") # Save workbook (this actually writes the file to disk) saveWorkbook(wb)

93

setStyleNamePrefix-methods Setting the style name prex for the "name prex" style action

Description Sets the style name prex for the "name prex" style action. Usage ## S4 method for signature workbook setStyleNamePrefix(object,prefix)

94 Arguments object prefix Details The workbook to use The name prex

setWrapText-methods

Sets the prefix for the "name prex" style action. See the method setStyleAction for more information. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, cellstyle, setStyleAction, createCellStyle

setWrapText-methods

Specifying text wrapping behaviour

Description Species if text should be wrapped in a cell. Usage ## S4 method for signature cellstyle setWrapText(object,wrap) Arguments object wrap The cellstyle to manipulate If wrap = TRUE, the text is wrapped if it exceeds the width of the cell - otherwise not.

Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, cellstyle, setCellStyle, setStyleAction

show-methods Examples
# Load workbook (create if not existing) wb <- loadWorkbook("setWrapText.xlsx", create = TRUE) # Create a worksheet createSheet(wb, name = "cellstyles") # Create a dummy data set with some long text text <- data.frame( Text = "Some very very very very very very very long text") # Write the value to the cellstyles worksheet in the # top left corner (cell A1) writeWorksheet(wb, text, sheet = "cellstyles", startRow = 1, startCol = 1, header = FALSE) # Create a custom anonymous cell style cs <- createCellStyle(wb) # Specify to wrap the text setWrapText(cs, wrap = TRUE) # Set the cell style created above for the top left cell (A1) # in the cellstyles worksheet setCellStyle(wb, sheet = "cellstyles", row = 1, col = 1, cellstyle = cs) # Save the workbook saveWorkbook(wb)

95

show-methods

Display a workbook object

Description Displays a workbook by printing it. This actually calls the workbooks print method. Usage ## S4 method for signature workbook show(object) Arguments object Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com The workbook to display

96 See Also workbook, print Examples

summary-methods

# Load existing demo Excel file mtcars.xlsx from the XLConnect package wb.mtcars <- loadWorkbook(system.file("demoFiles/mtcars.xlsx", package = "XLConnect")) # Display the wb.mtcars object wb.mtcars # Alternatively, show can be called explicitely show(wb.mtcars)

summary-methods

Summarizing workbook objects

Description Outputs a workbook summary including the underlying Excel lename, contained worksheets, hidden sheets, very hidden sheets, dened names and the active sheet name. Usage ## S4 method for signature workbook summary(object) Arguments object Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, getSheets, isSheetHidden, isSheetVeryHidden, getDefinedNames, getActiveSheetName Examples
# Load existing demo Excel file mtcars.xlsx from the XLConnect package wb.mtcars <- loadWorkbook(system.file("demoFiles/mtcars.xlsx", package = "XLConnect")) # Print a workbook summary summary(wb.mtcars)

The workbook to summarize

unhideSheet-methods

97

unhideSheet-methods

Unhiding worksheets in a workbook

Description Unhides the specied worksheets in a workbook. Usage ## S4 method for signature workbook,character unhideSheet(object,sheet) ## S4 method for signature workbook,numeric unhideSheet(object,sheet) Arguments object sheet Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, hideSheet, isSheetHidden, isSheetVeryHidden, isSheetVisible Examples
# Load workbook (create if not existing) wb <- loadWorkbook("unhideWorksheet.xlsx", create = TRUE) # Create sheet airquality createSheet(wb, name = "airquality") # Write the built-in data set airquality to worksheet # airquality writeWorksheet(wb, airquality, sheet = "airquality") # Create sheet CO2 createSheet(wb, name = "CO2") # Write the built-in data set CO2 to worksheet C 2 writeWorksheet(wb, CO2, sheet = "CO2") # Hide sheet airquality hideSheet(wb, sheet = "airquality")

The workbook to use The name or index of the sheet to unhide

98
# Unhide sheet airquality unhideSheet(wb, sheet = "airquality")

unmergeCells-methods

unmergeCells-methods

Unmerging cells

Description Unmerges cells in a worksheet. Usage ## S4 method for signature workbook,character unmergeCells(object,sheet,reference) ## S4 method for signature workbook,numeric unmergeCells(object,sheet,reference) Arguments object sheet reference The workbook to use The name or index of the sheet on which to unmerge cells A cell range specication (character) in the form A1:B8. Note that the specication must exactly correspond to the range of the merged cells.

Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook, mergeCells, idx2cref Examples
# Load workbook (create if not existing) wb <- loadWorkbook("unmergeCells.xlsx", create = TRUE) # Create a worksheet called merge createSheet(wb, name = "merge") # Merge the cells A1:B8 on the worksheet created above mergeCells(wb, sheet = "merge", reference = "A1:B8") # Unmerge the cells A1:B8 unmergeCells(wb, sheet = "merge", reference = "A1:B8")

workbook-class

99

workbook-class

Class "workbook"

Description This is XLConnects main entity representing a Microsoft Excel workbook. S4 objects of this class and corresponding methods are used to manipulate the underlying Excel workbook instances. Objects from the Class Objects can be created by calls of the form loadWorkbook(filename, create). This is a shortcut form of new("workbook", filename, create) with some additional error checking. Slots filename: Object of class character which represents the lename of the underlying Microsoft Excel workbook. jobj: Object of class jobjRef (see package rJava) which represents a Java object reference that is used in the back-end to manipulate the underlying Excel workbook instance. These slots should not be accessed directly in user code. workbook objects should only be manipulated via the corresponding methods. Note XLConnect supports both Excel 97-2003 (*.xls) and OOXML (Excel 2007+, *.xlsx) le formats.

A workbooks underlying Excel le is not saved (or being created in case the le did not exist and create = TRUE has been specied) unless the saveWorkbook method has been called on the object. This provides more exibility to the user to decide when changes are saved and also provides better performance in that several changes can be written in one go (normally at the end, rather than after every operation causing the le to be rewritten again completely each time). This is due to the fact that workbooks are manipulated in-memory and are only written to disk with specically calling saveWorkbook. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com References Wikipedia: Ofce Open XML http://en.wikipedia.org/wiki/Office_Open_XML

100 See Also loadWorkbook, saveWorkbook Examples

# Create a new workbook myWorkbook.xlsx # (assuming the file to not exist already) wb <- loadWorkbook("myWorkbook.xlsx", create = TRUE) # Create a worksheet called mtcars createSheet(wb, name = "mtcars")

writeNamedRegion-methods

# Write built-in dataset mtcars to sheet mtcars created above writeWorksheet(wb, mtcars, sheet = "mtcars") # Save workbook - this actually writes the file myWorkbook.xlsx to disk saveWorkbook(wb)

writeNamedRegion-methods Writing named regions to a workbook

Description Writes named regions to a workbook. Usage ## S4 method for signature workbook,ANY writeNamedRegion(object,data,name,header,rownames) Arguments object data name header rownames The workbook to use Data to write Name of the named region to write to Species if the column names should be written. The default is TRUE. Name (character) of column to use for the row names of the provided data object. If specied, the row names of the data object (data.frame) will be included as an additional column with the specied name. If rownames = NULL (default), no row names will be included.

Details Writes data to the named region specied by name. Note that data is assumed to be a data.frame and is coerced to one if this is not already the case. The argument header species if the column names should be written. Note also that the arguments are vectorized and as such multiple named regions can be written with one call. In this case data is assumed to be a list of data objects (data.frames).

writeNamedRegion-methods Note

101

Named regions are automatically redened to the area occupied by the written cells. This guarantees that the complete set of data can be re-read using readNamedRegion. Also, this allows the named region just to be dened as the top left cell to be written to. There is no need to know the exact size of the data in advance. When writing data to Excel, writeNamedRegion further applies cell styles to the cells as dened by the workbooks "style action" (see setStyleAction).

Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com

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=iAE9a uRtpM

See Also workbook, writeWorksheet, appendNamedRegion, appendWorksheet, readNamedRegion, readWorksheet, writeNamedRegionToFile

Examples
# Load workbook (create if not existing) wb <- loadWorkbook("writeNamedRegion.xlsx", create = TRUE) # Create a worksheet named mtcars createSheet(wb, name = "mtcars") # Create a named region called mtcars on the sheet called mtcars createName(wb, name = "mtcars", formula = "mtcars!$A$1") # Write built-in data set mtcars to the above defined named region # (using header = TRUE) writeNamedRegion(wb, mtcars, name = "mtcars") # Save workbook (this actually writes the file to disk) saveWorkbook(wb)

102

writeNamedRegionToFile

writeNamedRegionToFile Writing named regions to an Excel le (wrapper function)

Description Writes named regions to an Excel le. Usage writeNamedRegionToFile(file, data, name, formula=NA, ..., styleAction = XLC$STYLE_ACTION.XLCONNECT) Arguments file data name formula The path name of the le to write to Data to write Name of the named region to write to If formula is specied, each item denes the formula of the named region identied by the corresponding entry of name. Use this if you want to create the document from scratch instead of writing to a template! Additional arguments passed to writeNamedRegion Style action to be used when writing the data. The default is XLC$STYLE_ACTION.XLCONNECT. See setStyleAction for more information.

... styleAction

Author(s) Thomas Themel Mirai Solutions GmbH http://www.mirai-solutions.com See Also writeNamedRegion, writeWorksheetToFile, readNamedRegionFromFile, readWorksheetFromFile Examples
# multiregion xlsx file from demoFiles subfolder of package XLConnect demoExcelFile <- system.file("demoFiles/multiregion.xlsx", package = "XLConnect") template <- "template-ws.xlsx" file.copy(demoExcelFile, template) # Write single data.frame to a named region in an existing file writeNamedRegionToFile(template, name = "Iris", iris)

writeWorksheet-methods

103

# Write to a new file, defining the sheet and named region as we write. # Format according to XLConnect defaults writeNamedRegionToFile("iris.xlsx", name = "Iris", data = iris, formula = "IrisData!$C$4", styleAction = "XLCONNECT")

writeWorksheet-methods Writing data to worksheets

Description Writes data to worksheets of a workbook. Usage ## S4 method for signature workbook,ANY,character writeWorksheet(object,data,sheet,startRow,startCol,header,rownames) ## S4 method for signature workbook,ANY,numeric writeWorksheet(object,data,sheet,startRow,startCol,header,rownames) Arguments object data sheet startRow startCol header rownames The workbook to write to Data to write The name or index of the sheet to write to Index of the rst row to write to. The default is startRow = 1. Index of the rst column to write to. The default is startCol = 1. Species if the column names should be written. The default is TRUE. Name (character) of column to use for the row names of the provided data object. If specied, the row names of the data object (data.frame) will be included as an additional column with the specied name. If rownames = NULL (default), no row names will be included.

Details Writes data to the worksheet specied by sheet. data is assumed to be a data.frame and is coerced to one if this is not already the case. startRow and startCol dene the top left corner of the data region to be written. Note that the arguments are vectorized and as such multiple data objects (data.frames) can be written to different worksheets in one call. In this case data is assumed to be a list of data.frames. Note When writing data to Excel, writeWorksheet further applies cell styles to the cells as dened by the workbooks "style action" (see setStyleAction).

104 Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also

writeWorksheetToFile

workbook, writeNamedRegion, appendWorksheet, appendNamedRegion, readWorksheet, readNamedRegion, writeWorksheetToFile Examples

# Load workbook (create if not existing) wb <- loadWorkbook("writeWorksheet.xlsx", create = TRUE) # Create a worksheet called CO2 createSheet(wb, name = "CO2") # Write built-in data set CO2 to the worksheet created above; # offset from the top left corner and with default header = TRUE writeWorksheet(wb, CO2, sheet = "CO2", startRow = 4, startCol = 2) # Save workbook (this actually writes the file to disk) saveWorkbook(wb)

writeWorksheetToFile

Writing data to worksheets in an Excel le (wrapper function)

Description Writes data to worksheets in an Excel le. Usage writeWorksheetToFile(file, data, sheet, ..., styleAction = XLC$STYLE_ACTION.XLCONNECT) Arguments file data sheet ... styleAction The path name of the le to write to. Data to write The name or index of the sheet to write to Additional arguments passed to writeWorksheet Style action to be used when writing the data - not vectorized! The default is XLC$STYLE_ACTION.XLCONNECT. See setStyleAction for more information.

Author(s) Thomas Themel Mirai Solutions GmbH http://www.mirai-solutions.com

XLC See Also writeWorksheet, writeNamedRegionToFile, readWorksheetFromFile, readNamedRegionFromFile Examples

# multiregion xlsx file from demoFiles subfolder of package XLConnect demoExcelFile <- system.file("demoFiles/multiregion.xlsx", package = "XLConnect") # create a copy of the template template <- "template-ws.xlsx" file.copy(demoExcelFile, template) # Write single data.frame to a specified location in an existing file writeWorksheetToFile(template, data=iris, sheet="FirstSheet", startRow=9, startCol = 9) # create a copy of the template template <- "template-multi-ws.xlsx" # Write a few copies of the data.frame all over a new file writeWorksheetToFile(template, data = list(i1 = iris, i2 = iris, i3 = iris), sheet = c("FirstSheet", "SecondSheet", "FirstSheet"), startRow = c(1,1 1,2 1), startCol = c(1,11,21))

105

XLC

XLConnect Constants

Description List structure dening several constants used across XLConnect. Format The format is: List of 9 $ ERROR.WARN : chr "WARN" $ ERROR.STOP : chr "STOP" $ DATA_TYPE.BOOLEAN $ DATA_TYPE.NUMERIC $ DATA_TYPE.STRING $ DATA_TYPE.DATETIME $ STYLE_ACTION.XLCONNECT $ STYLE_ACTION.NONE $ STYLE_ACTION.PREDEFINED

: : : : : : :

chr chr chr chr chr chr chr

"BOOLEAN" "NUMERIC" "STRING" "DATETIME" "XLCONNECT" "NONE" "PREDEFINED"

106 $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ STYLE_ACTION.NAME_PREFIX : STYLE_ACTION.DATA_FORMAT_ONLY: BORDER.DASHED : BORDER.DASH_DOT : BORDER.DASH_DOT_DOT : BORDER.DOTTED : BORDER.DOUBLE : BORDER.HAIR : BORDER.MEDIUM : BORDER.MEDIUM_DASHED : BORDER.MEDIUM_DASH_DOT : BORDER.MEDIUM_DASH_DOT_DOT : BORDER.NONE : BORDER.SLANTED_DASH_DOT : BORDER.THICK : BORDER.THIN : COLOR.BLACK : COLOR.WHITE : COLOR.RED : COLOR.BRIGHT_GREEN : COLOR.BLUE : COLOR.YELLOW : COLOR.PINK : COLOR.TURQUOISE : COLOR.DARK_RED : COLOR.GREEN : COLOR.DARK_BLUE : COLOR.DARK_YELLOW : COLOR.VIOLET : COLOR.TEAL : COLOR.GREY_25_PERCENT : COLOR.GREY_5 _PERCENT : COLOR.CORNFLOWER_BLUE : COLOR.MAROON : COLOR.LEMON_CHIFFON : COLOR.ORCHID : COLOR.CORAL : COLOR.ROYAL_BLUE : COLOR.LIGHT_CORNFLOWER_BLUE : COLOR.SKY_BLUE : COLOR.LIGHT_TURQUOISE : COLOR.LIGHT_GREEN : COLOR.LIGHT_YELLOW : COLOR.PALE_BLUE : COLOR.ROSE : COLOR.LAVENDER : COLOR.TAN : COLOR.LIGHT_BLUE : chr chr num num num num num num num num num num num num num num num num num num num num num num num num num num num num num num num num num num num num num num num num num num num num num num "STYLE_NAME_PREFIX" "DATA_FORMAT_ONLY" 3 9 11 7 6 4 2 8 1 12 13 5 1 8 9 1 11 12 13 14 15 16 17 18 19 2 21 22 23 24 25 26 28 29 3 31 4 41 42 43 44 45 46 47 48

XLC

XLC $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ COLOR.AQUA COLOR.LIME COLOR.GOLD COLOR.LIGHT_ORANGE COLOR.ORANGE COLOR.BLUE_GREY COLOR.GREY_4 _PERCENT COLOR.DARK_TEAL COLOR.SEA_GREEN COLOR.DARK_GREEN COLOR.OLIVE_GREEN COLOR.BROWN COLOR.PLUM COLOR.INDIGO COLOR.GREY_8 _PERCENT COLOR.AUTOMATIC FILL.NO_FILL FILL.SOLID_FOREGROUND FILL.FINE_DOTS FILL.ALT_BARS FILL.SPARSE_DOTS FILL.THICK_HORZ_BANDS FILL.THICK_VERT_BANDS FILL.THICK_BACKWARD_DIAG FILL.THICK_FORWARD_DIAG FILL.BIG_SPOTS FILL.BRICKS FILL.THIN_HORZ_BANDS FILL.THIN_VERT_BANDS FILL.THIN_BACKWARD_DIAG FILL.THIN_FORWARD_DIAG FILL.SQUARES FILL.DIAMONDS : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : num num num num num num num num num num num num num num num num num num num num num num num num num num num num num num num num num 49 5 51 52 53 54 55 56 57 58 59 6 61 62 63 64 1 2 3 4 5 6 7 8 9 1 11 12 13 14 15 16

107

Details The XLC list structure denes several constants used throughout XLConnect. The general convention for enumeration types is to address corresponding constants via XLC$"<ENUM_TYPE>.<VALUE>" where <ENUM_TYPE> species the name of the enumeration and <VALUE> species a corresponding enumeration value. An example is XLC$"COLOR.RED" where "COLOR" is the enumeration type and "RED" is the corresponding color enumeration value. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com

108

xlcDump

xlcDump

Dumping data sets to Excel les

Description Dumps data sets to Excel les by writing each object to a separate worksheet. Usage xlcDump(list, ..., file = "dump.xlsx", pos = -1, overwrite = FALSE) Arguments list character vector of names of objects inside environment pos to dump into an Excel le. Objects will be written using writeWorksheet - as such any object will be coerced to a data.frame. If missing, the list of objects will be determined via the function ls which takes any arguments specied via . . . . Arguments that will be passed to the ls function for getting a list of object names in case the list argument is missing. Excel le to which objects will be dumped. Can be an existing or a new le. Defaults to "dump.xlsx". Environment in which to look for objects. Can be specied either as an integer specifying the position in the search list, as a character naming an element in the search list or as an environment. Defaults to -1 which refers to the current environment. logical specifying if data should be overwritten if objects with the same name have already been dumped to the Excel file.

... file pos

overwrite

Details Each object is written to a separate worksheet named by the name of the object. Objects are written using the writeWorksheet method - as such any object will be coerced to data.frame. Value Named logical vector specifying if objects have been dumped or not. An object may not be dumped because there was an issue with the coercion to a data.frame or the object already existed (and overwrite = FALSE) in the workbook. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com

xlcEdit See Also

109

xlcRestore, writeNamedRegion, writeWorksheet, writeNamedRegionToFile, writeWorksheetToFile, xlcEdit Examples

require(datasets) xlcDump(c("airquality", "CO2", "iris", "PlantGrowth", "swiss"), file = "myDump.xlsx", pos = "package:datasets") xlcRestore(file = "myDump.xlsx", overwrite = TRUE)

xlcEdit

Editing data sets in an Excel le editor

Description Provides the capability to edit an object/data.frame in an Excel le editor. After editing, the object is restored in the R session with the corresponding changes. Usage xlcEdit(obj, pos = globalenv(), ext = ".xlsx") Arguments obj pos ext Details This function uses xlcDump and xlcRestore to dump objects to and restore objects from Excel les. An OS command is invoked to open the temporary Excel le in the default editor. Changes to the le have to be saved in order for them to take effect in the restored object. Value Invisibly returns the value of the xlcRestore operation. Note This function only works under Windows and MacOS with a corresponding Excel le editor, e.g. MS Excel or LibreOfce. Attempts to use this function under another OS will result in an error being thrown. Object (data.frame) to edit. Where to look for the object specied by obj. See pos argument of get for more information. Extension to use for the Excel le being created. Defaults to ".xlsx".

110 Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also

xlcFreeMemory

xlcDump, xlcRestore, writeNamedRegion, writeWorksheet, writeNamedRegionToFile, writeWorksheetToFile Examples

## Not run: myObj = mtcars xlcEdit(myObj) ## End(Not run)

xlcFreeMemory

Freeing Java Virtual Machine memory

Description Frees Java Virtual Machine (JVM) memory. Usage xlcFreeMemory(...) Arguments ... Details This function uses Javas Runtime class to run the garbage collector. Java memory is freed by rst running Rs garbage collector (gc) and then Javas garbage collector. This sequence is important as Rs gc may release objects which in turn allows Javas garbage collector to release some objects. Note, in general there should be no need to make active use of this with XLConnect. Both R and Java automatically perform garbage collection at times. However, this function might be useful to reclaim memory after removing a large data object that has been written/read to/from Excel. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com Further arguments to be passed to Rs garbage collector (gc).

xlcMemoryReport References java.lang.Runtime: http://download.oracle.com/javase/6/docs/api/java/lang/Runtime.html See Also xlcMemoryReport, gc Examples

xlcFreeMemory()

111

xlcMemoryReport

Reporting free Java Virtual Machine memory

Description Reports the amount of free memory in the Java Virtual Machine (JVM). Usage xlcMemoryReport() Details This function uses Javas Runtime class to query the free JVM memory. Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com References java.lang.Runtime: http://download.oracle.com/javase/6/docs/api/java/lang/Runtime.html See Also xlcFreeMemory Examples
xlcMemoryReport()

112

xlcRestore

xlcRestore

Restoring objects from Excel les

Description Restores objects from Excel les that have been dumped using xlcDump. Usage xlcRestore(file = "dump.xlsx", pos = -1, overwrite = FALSE) Arguments file pos Excel le from which to restore objects. This is normally a le that has been produced with xlcDump. Defaults to "dump.xlsx". Environment into which to restore objects. Can be specied either as an integer specifying the position in the search list, as a character naming an element in the search list or as an environment. Defaults to -1 which refers to the current environment. logical specifying if data objects should be overwritten if they already exist inside the environment pos.

overwrite

Value Named logical vector specifying if objects have been restored or not. An object may not be restored because there was an issue with reading the data from the worksheet or the object already existed in the environment pos (and overwrite = FALSE). Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also xlcDump, readNamedRegion, readWorksheet, readNamedRegionFromFile, readWorksheetFromFile, xlcEdit Examples
require(datasets) xlcDump(c("airquality", "CO2", "iris", "PlantGrowth", "swiss"), file = "myDump.xlsx", pos = "package:datasets") xlcRestore(file = "myDump.xlsx", overwrite = TRUE)

$-methods

113

$-methods

Executing workbook methods in object$method(...) form

Description Allows to execute workbook methods in workbook-object$method(...) form. Arguments x Details x$method(...) (where x is a workbook-object) is equivalent to method(x, ...) Note The workbook $-operator allows to call workbook-methods in workbook-object$method(...) form. This form might be considered more convenient or readable for programmers coming from other object-oriented languages such as Java, C#, ... Author(s) Martin Studer Mirai Solutions GmbH http://www.mirai-solutions.com See Also workbook Examples
# Load workbook (create if not existing) wb <- loadWorkbook("dollar.xlsx", create = TRUE) # Create a worksheet called CO2 wb$createSheet(name = "CO2") # Write built-in data set CO2 to the worksheet created above wb$writeWorksheet(CO2, sheet = "CO2", startRow = 4, startCol = 2) # Save workbook wb$saveWorkbook()

The object (workbook, cellstyle) to use

Index
Topic IO appendNamedRegion-methods, 6 appendWorksheet-methods, 8 readNamedRegion, 55 readNamedRegionFromFile, 58 readWorksheet-methods, 59 readWorksheetFromFile, 63 writeNamedRegion-methods, 100 writeNamedRegionToFile, 102 writeWorksheet-methods, 103 writeWorksheetToFile, 104 Topic classes cellstyle-class, 10 workbook-class, 99 Topic datasets mirai, 52 XLC, 105 Topic error onErrorCell-methods, 53 Topic le loadWorkbook, 50 saveWorkbook-methods, 70 xlcDump, 108 xlcRestore, 112 Topic list XLC, 105 Topic methods $-methods, 113 addImage-methods, 5 appendNamedRegion-methods, 6 appendWorksheet-methods, 8 clearNamedRegion-methods, 12 clearRange-methods, 13 clearRangeFromReference-methods, 15 clearSheet-methods, 16 cloneSheet-methods, 17 createCellStyle-methods, 18 createFreezePane-methods, 20 114 createName-methods, 21 createSheet-methods, 23 createSplitPane-methods, 24 existsName-methods, 26 existsSheet-methods, 27 extraction-methods, 28 getActiveSheetIndex-methods, 30 getActiveSheetName-methods, 31 getBoundingBox-methods, 31 getCellFormula-methods, 33 getCellStyle-methods, 34 getDefinedNames-methods, 35 getForceFormulaRecalculation-methods, 36 getLastColumn-methods, 37 getLastRow-methods, 38 getReferenceCoordinates-methods, 39 getReferenceFormula-methods, 40 getSheetPos-methods, 41 getSheets-methods, 42 hideSheet-methods, 42 isSheetHidden-methods, 46 isSheetVeryHidden-methods, 47 isSheetVisible-methods, 49 mergeCells-methods, 51 print-methods, 54 readNamedRegion, 55 readWorksheet-methods, 59 removeName-methods, 65 removePane-methods, 66 removeSheet-methods, 67 renameSheet-methods, 68 saveWorkbook-methods, 70 setActiveSheet-methods, 71 setAutoFilter-methods, 72 setBorder-methods, 73 setCellFormula-methods, 74 setCellStyle-methods, 76

INDEX setColumnWidth-methods, 78 setDataFormat-methods, 79 setDataFormatForType-methods, 80 setFillBackgroundColor-methods, 81 setFillForegroundColor-methods, 82 setFillPattern-methods, 84 setForceFormulaRecalculation-methods, 85 setMissingValue-methods, 86 setRowHeight-methods, 87 setSheetColor-methods, 88 setSheetPos-methods, 89 setStyleAction-methods, 90 setStyleNamePrefix-methods, 93 setWrapText-methods, 94 show-methods, 95 summary-methods, 96 unhideSheet-methods, 97 unmergeCells-methods, 98 writeNamedRegion-methods, 100 writeWorksheet-methods, 103 Topic misc runUnitTests, 69 xlcEdit, 109 Topic package XLConnect-package, 4 Topic print print-methods, 54 show-methods, 95 summary-methods, 96 Topic utilities $-methods, 113 addImage-methods, 5 aref, 9 aref2idx, 10 cellstyle-class, 10 clearNamedRegion-methods, 12 clearRange-methods, 13 clearRangeFromReference-methods, 15 clearSheet-methods, 16 cloneSheet-methods, 17 col2idx, 18 createCellStyle-methods, 18 createFreezePane-methods, 20 createName-methods, 21 createSheet-methods, 23 createSplitPane-methods, 24

115 cref2idx, 25 existsName-methods, 26 existsSheet-methods, 27 extraction-methods, 28 extractSheetName, 29 getActiveSheetIndex-methods, 30 getActiveSheetName-methods, 31 getBoundingBox-methods, 31 getCellFormula-methods, 33 getCellStyle-methods, 34 getDefinedNames-methods, 35 getForceFormulaRecalculation-methods, 36 getLastColumn-methods, 37 getLastRow-methods, 38 getReferenceCoordinates-methods, 39 getReferenceFormula-methods, 40 getSheetPos-methods, 41 getSheets-methods, 42 hideSheet-methods, 42 idx2aref, 44 idx2col, 45 idx2cref, 45 isSheetHidden-methods, 46 isSheetVeryHidden-methods, 47 isSheetVisible-methods, 49 mergeCells-methods, 51 onErrorCell-methods, 53 removeName-methods, 65 removePane-methods, 66 removeSheet-methods, 67 renameSheet-methods, 68 runUnitTests, 69 setActiveSheet-methods, 71 setAutoFilter-methods, 72 setBorder-methods, 73 setCellFormula-methods, 74 setCellStyle-methods, 76 setColumnWidth-methods, 78 setDataFormat-methods, 79 setDataFormatForType-methods, 80 setFillBackgroundColor-methods, 81 setFillForegroundColor-methods, 82 setFillPattern-methods, 84 setForceFormulaRecalculation-methods, 85 setMissingValue-methods, 86

116 setRowHeight-methods, 87 setSheetColor-methods, 88 setSheetPos-methods, 89 setStyleAction-methods, 90 setStyleNamePrefix-methods, 93 setWrapText-methods, 94 summary-methods, 96 unhideSheet-methods, 97 unmergeCells-methods, 98 XLC, 105 xlcDump, 108 xlcEdit, 109 xlcFreeMemory, 110 xlcMemoryReport, 111 xlcRestore, 112 [ (extraction-methods), 28 [,workbook-method (extraction-methods), 28 [-methods (extraction-methods), 28 [<- (extraction-methods), 28 [<-,workbook-method (extraction-methods), 28 [<--methods (extraction-methods), 28 [[ (extraction-methods), 28 [[,workbook-method (extraction-methods), 28 [[-methods (extraction-methods), 28 [[<- (extraction-methods), 28 [[<-,workbook-method (extraction-methods), 28 [[<--methods (extraction-methods), 28 $ ($-methods), 113 $,cellstyle-method ($-methods), 113 $,workbook-method ($-methods), 113 $-methods, 113 addImage (addImage-methods), 5 addImage,workbook-method (addImage-methods), 5 addImage-methods, 5 appendNamedRegion, 8, 101, 104 appendNamedRegion (appendNamedRegion-methods), 6 appendNamedRegion,workbook,ANY-method (appendNamedRegion-methods), 6 appendNamedRegion,workbook-method (appendNamedRegion-methods), 6 appendNamedRegion-methods, 6 appendWorksheet, 7, 101, 104

INDEX appendWorksheet (appendWorksheet-methods), 8 appendWorksheet,workbook,ANY,character-method (appendWorksheet-methods), 8 appendWorksheet,workbook,ANY,numeric-method (appendWorksheet-methods), 8 appendWorksheet-methods, 8 aref, 9, 10, 18, 25, 4446 aref2idx, 9, 10, 14, 18, 25, 4446 cellstyle, 18, 19, 34, 73, 74, 76, 79, 8184, 9092, 94, 113 cellstyle-class, 10 clearNamedRegion, 1416 clearNamedRegion (clearNamedRegion-methods), 12 clearNamedRegion,workbook,character-method (clearNamedRegion-methods), 12 clearNamedRegion-methods, 12 clearRange, 13, 15, 16 clearRange (clearRange-methods), 13 clearRange,workbook,character-method (clearRange-methods), 13 clearRange,workbook,numeric-method (clearRange-methods), 13 clearRange-methods, 13 clearRangeFromReference, 13, 14, 16 clearRangeFromReference (clearRangeFromReference-methods), 15 clearRangeFromReference,workbook,character-method (clearRangeFromReference-methods), 15 clearRangeFromReference-methods, 15 clearSheet, 1315 clearSheet (clearSheet-methods), 16 clearSheet,workbook,character-method (clearSheet-methods), 16 clearSheet,workbook,numeric-method (clearSheet-methods), 16 clearSheet-methods, 16 cloneSheet, 23, 27, 68 cloneSheet (cloneSheet-methods), 17 cloneSheet,workbook,character-method (cloneSheet-methods), 17 cloneSheet,workbook,numeric-method (cloneSheet-methods), 17 cloneSheet-methods, 17 col2idx, 9, 10, 18, 25, 4446

INDEX createCellStyle, 10, 11, 76, 92, 94 createCellStyle (createCellStyle-methods), 18 createCellStyle,workbook,character-method (createCellStyle-methods), 18 createCellStyle,workbook,missing-method (createCellStyle-methods), 18 createCellStyle-methods, 18 createFreezePane, 24, 66 createFreezePane (createFreezePane-methods), 20 createFreezePane,workbook,character-method (createFreezePane-methods), 20 createFreezePane,workbook,numeric-method (createFreezePane-methods), 20 createFreezePane-methods, 20 createName, 5, 26, 35, 39, 40, 65 createName (createName-methods), 21 createName,workbook-method (createName-methods), 21 createName-methods, 21 createSheet, 17, 27, 42, 68, 72 createSheet (createSheet-methods), 23 createSheet,workbook-method (createSheet-methods), 23 createSheet-methods, 23 createSplitPane, 21, 66 createSplitPane (createSplitPane-methods), 24 createSplitPane,workbook,character-method (createSplitPane-methods), 24 createSplitPane,workbook,numeric-method (createSplitPane-methods), 24 createSplitPane-methods, 24 cref2idx, 10, 18, 25, 4446 data.frame, 56, 60 existsName, 22, 35, 39, 40, 65 existsName (existsName-methods), 26 existsName,workbook-method (existsName-methods), 26 existsName-methods, 26 existsSheet, 17, 23, 68, 72 existsSheet (existsSheet-methods), 27 existsSheet,workbook-method (existsSheet-methods), 27 existsSheet-methods, 27 extraction-methods, 28 extractSheetName, 29

117

gc, 110, 111 get, 109 getActiveSheetIndex, 31 getActiveSheetIndex (getActiveSheetIndex-methods), 30 getActiveSheetIndex,workbook-method (getActiveSheetIndex-methods), 30 getActiveSheetIndex-methods, 30 getActiveSheetName, 30, 96 getActiveSheetName (getActiveSheetName-methods), 31 getActiveSheetName,workbook-method (getActiveSheetName-methods), 31 getActiveSheetName-methods, 31 getBoundingBox (getBoundingBox-methods), 31 getBoundingBox,workbook,character-method (getBoundingBox-methods), 31 getBoundingBox,workbook,numeric-method (getBoundingBox-methods), 31 getBoundingBox-methods, 31 getCellFormula, 75 getCellFormula (getCellFormula-methods), 33 getCellFormula,workbook,character-method (getCellFormula-methods), 33 getCellFormula,workbook,numeric-method (getCellFormula-methods), 33 getCellFormula-methods, 33 getCellStyle (getCellStyle-methods), 34 getCellStyle,workbook-method (getCellStyle-methods), 34 getCellStyle-methods, 34 getDefinedNames, 22, 26, 65, 96 getDefinedNames (getDefinedNames-methods), 35 getDefinedNames,workbook-method (getDefinedNames-methods), 35 getDefinedNames-methods, 35 getForceFormulaRecalculation, 85 getForceFormulaRecalculation (getForceFormulaRecalculation-methods), 36

118

INDEX

getForceFormulaRecalculation,workbook,character-method hideSheet (hideSheet-methods), 42 (getForceFormulaRecalculation-methods) , hideSheet,workbook,character-method 36 (hideSheet-methods), 42 hideSheet,workbook,numeric-method getForceFormulaRecalculation,workbook,numeric-method (hideSheet-methods), 42 (getForceFormulaRecalculation-methods), hideSheet-methods, 42 36 getForceFormulaRecalculation-methods, idx2aref, 9, 10, 18, 25, 44, 45, 46 36 idx2col, 9, 10, 18, 25, 44, 45, 46 getLastColumn (getLastColumn-methods), idx2cref, 9, 10, 18, 25, 44, 45, 45, 52, 98 37 isSheetHidden, 43, 48, 49, 96, 97 getLastColumn,workbook,character-method isSheetHidden (isSheetHidden-methods), (getLastColumn-methods), 37 46 getLastColumn,workbook,numeric-method isSheetHidden,workbook,character-method (getLastColumn-methods), 37 (isSheetHidden-methods), 46 getLastColumn-methods, 37 isSheetHidden,workbook,numeric-method getLastRow (getLastRow-methods), 38 (isSheetHidden-methods), 46 getLastRow,workbook,character-method isSheetHidden-methods, 46 (getLastRow-methods), 38 isSheetVeryHidden, 43, 47, 49, 96, 97 getLastRow,workbook,numeric-method isSheetVeryHidden (getLastRow-methods), 38 (isSheetVeryHidden-methods), 47 getLastRow-methods, 38 isSheetVeryHidden,workbook,character-method getReferenceCoordinates, 33 (isSheetVeryHidden-methods), 47 getReferenceCoordinates isSheetVeryHidden,workbook,numeric-method (getReferenceCoordinates-methods), (isSheetVeryHidden-methods), 47 39 isSheetVeryHidden-methods , 47 getReferenceCoordinates,workbook-method isSheetVisible , 43 , 47, 48 , 97 (getReferenceCoordinates-methods), isSheetVisible 39 (isSheetVisible-methods), 49 getReferenceCoordinates-methods, 39 isSheetVisible,workbook,character-method getReferenceFormula, 39 (isSheetVisible-methods), 49 getReferenceFormula isSheetVisible,workbook,numeric-method (getReferenceFormula-methods), (isSheetVisible-methods), 49 40 isSheetVisible-methods , 49 getReferenceFormula,workbook-method (getReferenceFormula-methods), 40 getReferenceFormula-methods, 40 getSheetPos, 42, 90 getSheetPos (getSheetPos-methods), 41 getSheetPos,workbook,character-method (getSheetPos-methods), 41 getSheetPos-methods, 41 getSheets, 17, 23, 27, 36, 41, 68, 72, 90, 96 getSheets (getSheets-methods), 42 getSheets,workbook-method (getSheets-methods), 42 getSheets-methods, 42 hideSheet, 4749, 97 loadWorkbook, 50, 70, 71, 99, 100 mergeCells, 98 mergeCells (mergeCells-methods), 51 mergeCells,workbook,character-method (mergeCells-methods), 51 mergeCells,workbook,numeric-method (mergeCells-methods), 51 mergeCells-methods, 51 mirai, 52 onErrorCell, 57, 59, 62, 64 onErrorCell (onErrorCell-methods), 53 onErrorCell,workbook-method (onErrorCell-methods), 53

INDEX onErrorCell-methods, 53 print, 95, 96 print (print-methods), 54 print,workbook-method (print-methods), 54 print-methods, 54 readNamedRegion, 7, 8, 22, 26, 28, 35, 53, 55, 58, 59, 62, 65, 101, 104, 112 readNamedRegion,workbook-method (readNamedRegion), 55 readNamedRegion-methods (readNamedRegion), 55 readNamedRegionFromFile, 53, 57, 58, 64, 102, 105, 112 readWorksheet, 7, 8, 28, 53, 57, 64, 101, 104, 112 readWorksheet (readWorksheet-methods), 59 readWorksheet,workbook,character-method (readWorksheet-methods), 59 readWorksheet,workbook,numeric-method (readWorksheet-methods), 59 readWorksheet-methods, 59 readWorksheetFromFile, 53, 59, 62, 63, 102, 105, 112 removeName, 22, 26, 35, 39, 40 removeName (removeName-methods), 65 removeName,workbook-method (removeName-methods), 65 removeName-methods, 65 removePane, 21, 24 removePane (removePane-methods), 66 removePane,workbook,character-method (removePane-methods), 66 removePane,workbook,numeric-method (removePane-methods), 66 removePane-methods, 66 removeSheet, 17, 23, 27, 42, 68, 72 removeSheet (removeSheet-methods), 67 removeSheet,workbook,character-method (removeSheet-methods), 67 removeSheet,workbook,numeric-method (removeSheet-methods), 67 removeSheet-methods, 67 renameSheet, 17, 23, 27, 42, 68, 72 renameSheet (renameSheet-methods), 68

119 renameSheet,workbook,character-method (renameSheet-methods), 68 renameSheet,workbook,numeric-method (renameSheet-methods), 68 renameSheet-methods, 68 runUnitTests, 69 saveWorkbook, 51, 99, 100 saveWorkbook (saveWorkbook-methods), 70 saveWorkbook,workbook,character-method (saveWorkbook-methods), 70 saveWorkbook,workbook,missing-method (saveWorkbook-methods), 70 saveWorkbook-methods, 70 setActiveSheet, 68 setActiveSheet (setActiveSheet-methods), 71 setActiveSheet,workbook,character-method (setActiveSheet-methods), 71 setActiveSheet,workbook,numeric-method (setActiveSheet-methods), 71 setActiveSheet-methods, 71 setAutoFilter (setAutoFilter-methods), 72 setAutoFilter,workbook,character-method (setAutoFilter-methods), 72 setAutoFilter,workbook,numeric-method (setAutoFilter-methods), 72 setAutoFilter-methods, 72 setBorder, 19, 34, 76 setBorder (setBorder-methods), 73 setBorder,cellstyle-method (setBorder-methods), 73 setBorder-methods, 73 setCellFormula, 34 setCellFormula (setCellFormula-methods), 74 setCellFormula,workbook,character-method (setCellFormula-methods), 74 setCellFormula,workbook,numeric-method (setCellFormula-methods), 74 setCellFormula-methods, 74 setCellStyle, 11, 19, 34, 74, 79, 8284, 94 setCellStyle (setCellStyle-methods), 76 setCellStyle,workbook,character,missing-method (setCellStyle-methods), 76 setCellStyle,workbook,missing,character-method (setCellStyle-methods), 76

120

INDEX

setCellStyle,workbook,missing,numeric-method setForceFormulaRecalculation (setCellStyle-methods), 76 (setForceFormulaRecalculation-methods), 85 setCellStyle-methods, 76 setForceFormulaRecalculation,workbook,character-method setColumnWidth, 88 (setForceFormulaRecalculation-methods), setColumnWidth 85 (setColumnWidth-methods), 78 setForceFormulaRecalculation,workbook,numeric-method setColumnWidth,workbook,character-method (setForceFormulaRecalculation-methods), (setColumnWidth-methods), 78 85 setColumnWidth,workbook,numeric-method setForceFormulaRecalculation-methods, (setColumnWidth-methods), 78 85 setColumnWidth-methods, 78 setMissingValue setDataFormat, 19, 34, 76 (setMissingValue-methods), 86 setDataFormat (setDataFormat-methods), setMissingValue,workbook,ANY-method 79 (setMissingValue-methods), 86 setDataFormat,cellstyle-method setMissingValue,workbook-method (setDataFormat-methods), 79 (setMissingValue-methods), 86 setDataFormat-methods, 79 setMissingValue-methods, 86 setDataFormatForType, 92 setRowHeight, 78 setDataFormatForType setRowHeight (setRowHeight-methods), 87 (setDataFormatForType-methods), setRowHeight,workbook,character-method 80 (setRowHeight-methods), 87 setDataFormatForType,workbook-method setRowHeight,workbook,numeric-method (setDataFormatForType-methods), (setRowHeight-methods), 87 80 setRowHeight-methods , 87 setDataFormatForType-methods, 80 setSheetColor (setSheetColor-methods), setFillBackgroundColor, 19, 34, 76 88 setFillBackgroundColor setSheetColor,workbook,character-method (setFillBackgroundColor-methods), (setSheetColor-methods), 88 81 setSheetColor,workbook,numeric-method setFillBackgroundColor,cellstyle,numeric-method (setSheetColor-methods), 88 (setFillBackgroundColor-methods), setSheetColor-methods, 88 81 setSheetPos, 41, 42 setFillBackgroundColor-methods, 81 setSheetPos (setSheetPos-methods), 89 setFillForegroundColor, 19, 34, 76 setSheetPos,workbook,character,missing-method setFillForegroundColor (setSheetPos-methods), 89 (setFillForegroundColor-methods), 82 setSheetPos,workbook,character,numeric-method (setSheetPos-methods), 89 setFillForegroundColor,cellstyle,numeric-method (setFillForegroundColor-methods), setSheetPos-methods, 89 82 setStyleAction, 11, 19, 34, 74, 7984, 94, setFillForegroundColor-methods, 82 101104 setFillPattern, 19, 34, 76 setStyleAction (setStyleAction-methods), 90 setFillPattern (setFillPattern-methods), 84 setStyleAction,workbook-method (setStyleAction-methods), 90 setFillPattern,cellstyle-method (setFillPattern-methods), 84 setStyleAction-methods, 90 setFillPattern-methods, 84 setStyleNamePrefix, 19, 34, 91, 92 setForceFormulaRecalculation, 36 setStyleNamePrefix

INDEX (setStyleNamePrefix-methods), 93 setStyleNamePrefix,workbook-method (setStyleNamePrefix-methods), 93 setStyleNamePrefix-methods, 93 setWrapText, 19, 34, 76 setWrapText (setWrapText-methods), 94 setWrapText,cellstyle-method (setWrapText-methods), 94 setWrapText-methods, 94 show (show-methods), 95 show,workbook-method (show-methods), 95 show-methods, 95 strptime, 55, 60 summary (summary-methods), 96 summary,workbook-method (summary-methods), 96 summary-methods, 96 unhideSheet, 43, 4749 unhideSheet (unhideSheet-methods), 97 unhideSheet,workbook,character-method (unhideSheet-methods), 97 unhideSheet,workbook,numeric-method (unhideSheet-methods), 97 unhideSheet-methods, 97 unmergeCells, 52 unmergeCells (unmergeCells-methods), 98 unmergeCells,workbook,character-method (unmergeCells-methods), 98 unmergeCells,workbook,numeric-method (unmergeCells-methods), 98 unmergeCells-methods, 98 workbook, 5, 7, 8, 1017, 1924, 2628, 3043, 4655, 5759, 62, 6568, 7072, 7476, 7890, 92, 9498, 100, 101, 103, 104, 113 workbook-class, 99 writeNamedRegion, 7, 8, 22, 26, 28, 35, 57, 62, 65, 85, 87, 90, 92, 102, 104, 109, 110 writeNamedRegion (writeNamedRegion-methods), 100 writeNamedRegion,workbook,ANY-method (writeNamedRegion-methods), 100 writeNamedRegion,workbook-method (writeNamedRegion-methods), 100

121 writeNamedRegion-methods, 100 writeNamedRegionToFile, 59, 64, 101, 102, 105, 109, 110 writeWorksheet, 7, 8, 28, 57, 62, 85, 87, 90, 92, 101, 104, 105, 108110 writeWorksheet (writeWorksheet-methods), 103 writeWorksheet,workbook,ANY,character-method (writeWorksheet-methods), 103 writeWorksheet,workbook,ANY,numeric-method (writeWorksheet-methods), 103 writeWorksheet-methods, 103 writeWorksheetToFile, 59, 64, 102, 104, 104, 109, 110 XLC, 53, 55, 60, 73, 74, 80, 8284, 88, 89, 105 xlcDump, 108, 109, 110, 112 xlcEdit, 109, 109, 112 xlcFreeMemory, 110, 111 xlcMemoryReport, 111, 111 XLConnect (XLConnect-package), 4 XLConnect-package, 4 xlcRestore, 109, 110, 112