table1xls (version 0.4.0)

XLunivariate: Univariate Statistics Exported to Excel

Description

Calculates univariate summary statistics (optionally stratified), exports the formatted output to a spreadsheet, and saves the file.

Usage

XLunivariate(wb, sheet, calcvar, colvar = rep("", length(calcvar)),
  table1mode = FALSE, fun1 = list(fun = roundmean, name = "Mean"),
  fun2 = list(fun = roundSD, name = "SD"), seps = c("", " (", ")"),
  sideBySide = FALSE, title = NULL, rowTitle = "", rowNames = NULL,
  colNames = rowNames, ord = NULL, row1 = 1, col1 = 1, purge = FALSE,
  ...)

Arguments

wb

a workbook-class object

sheet

numeric or character: a worksheet name (character) or position (numeric) within wb.

calcvar

vector: variable to calculate the statistics for (usually numeric, can be logical).

colvar

vector: categorical variable to stratify calcvar's summaries over. Will show as columns in output only if sideBySide=TRUE; otherwise as rows. Default behavior if left unspecified, is to calculate overall summaries for a single row/column output.

table1mode

logical: is the function called from XLtable1? If TRUE, some modifications will be made to the output. Default FALSE.

fun1, fun2

two lists describing the utility functions that will calculate the statistics. Each list has a fun component for the function, and a name component for its name as it would appear in the column header.

seps

character vector of length 3, specifying the formatted separators before the output of fun1$fun, between the two outputs, and after the output of fun2$fun. Default behavior encloses the second output in parentheses. See 'Examples'.

sideBySide

logical: should output be arranged horizontally rather than vertically? Default FALSE.

title

character: an optional overall title to the table. Default (NULL) is no title.

rowTitle

character: the title to be placed above the row name column (default empty string)

rowNames

character vector of row names. Default behavior (NULL): automatically determined from data

colNames

column names for stratifying variable, used when sideBySide=TRUE. Default: equal to rowNames.

ord

numeric vector specifying row-index order (i.e., a re-ordering of rowvar's levels) in the produced table. Default (NULL) is no re-ordering.

row1, col1

numeric: the first row and column occupied by the table (title included if relevant).

purge

logical: should sheet be created anew, by first removing the previous copy if it exists? (default FALSE)

...

parameters passed on to fun1$fun,fun2$fun

Value

The function returns invisibly, after writing the data into sheet and saving the file.

Details

This function evaluates up to 2 univariate functions on the input vector calcvar, either as a single sample, or grouped by strata defined via colvar (which is named this way for compatibility with XLtable1). It produces a single-column or single-row table (apart from row/column headers), with each interior cell containing the formatted results from the two functions. The table is exported to a spreadsheet and the file is saved.

The cell can be formatted to show a combined result, e.g. "Mean (SD)" which is the default. Tne function is quite mutable: both fun1$fun, fun2$fun and the strings separating their formatted output can be user-defined. The functions can return either a string (i.e., a formatted output) or a number that will be interpreted as a string in subsequent formatting. The default calls roundmean,roundSD and prints the summaries in "mean(SD)" format.

See the XLtwoWay help page, for behavior regarding new-sheet creation, overwriting, etc.

See Also

Uses writeWorksheet to access the spreadsheet, rangeString for some utilities that can be used as fun1$fun,fun2$fun. For one-way (univariate) contingency tables, XLoneWay.

Examples

# NOT RUN {
book2<-XLwriteOpen("chick2.xls") 
## Plain-vanilla
XLunivariate(book2,"weightByDiet",ChickWeight$weight,ChickWeight$Diet,
             title="Mean Weights by Diet",rowTitle="Diet")

## Replace mean/SD with median/range, put results beside previous
XLunivariate(book2,"weightByDiet",ChickWeight$weight,ChickWeight$Diet,
             title="Median Weights by Diet",rowTitle="Diet",col1=8,
             fun1=list(fun=roundmedian,name="Median"),fun2=list(fun=rangeString,name="range"))

### You can also do only one statistic... by "killing" one of the functions
XLunivariate(book2,"weightByAge",ChickWeight$weight,ChickWeight$Time,
             title="Mean Weights by Age",rowTitle="Age (Days)",seps=rep("",3),
             fun2=list(fun=emptee,name=""))
cat("Look for",paste(getwd(),"chick2.xls",sep='/'),"to see the results!\n")
# }