table1xls (version 0.4.0)

XLtable1: "Table 1" Style List of Tables exported to a spreadsheet

Description

Formats and exports a series of shared-structure tables, and saves the file.

Usage

XLtable1(wb, sheet, DF, colvar = NULL, fun = XLoneWay, title = "Table 1",
  colTitle = NULL, colNames = NULL, row1 = 1, col1 = 1, digits = NULL,
  useNA = "ifany", ..., purge = FALSE)

Arguments

wb

a workbook-class object

sheet

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

DF

a rectangular array with all variables to be tabulated.

colvar

vector; specifies the variable to cross-tabulate for fun=XLtwoWay (see 'Details' for convenience options), or to stratify for XLunivariate. Has to be the entire variable, rather than just a name.

fun

The table1xls function to apply for each variable. Default XLoneWay. Other supported functions are XLtwoWay,XLunivariate.

title

character: an optional overall title to the table. Default "Table 1".

colTitle

character: the title to be placed above the first column of the column variable. Default NULL.

colNames

character: when relevant, more descriptive names for columns in case colvar is used. Default NULL, which will use the unique values of colvar as names.

row1, col1

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

digits

numeric: how many digits (after the decimal point) to show in the percents? Defaults to 1 if n>=500 or if using XLunivariate, and 0 otherwise.

useNA

How to handle missing values. Passed on to table (see help on that function for options).

...

additional arguments as needed, to pass on to fun; for example, non-default summary function choices for XLunivariate.

purge

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

Value

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

Details

Auto-generation of a series of tables of the same type for a single dataset. One-way and two-way contingency tables and numerical summaries are all supported, but all summaries call the same atomic fun.

The function employs convenience conventions for two-way tabulation: first, if colvar is specified and fun is left blank, then fun will be set to XLtwoWay. Second, if fun=XLtwoWay and colvar is left blank, then colvar will be set to the last column of DF.

For numerical summaries, use fun=XLunivariate. If you specify colvar, two-way summaries stratified by colvar will be returned.

Note that this function does not mix and match. Just make several calls to XLtable1 with different sub-datasets and different values of fun, and combine the results in your report document.

In a similar vein, two-way summaries do not return the marginal one-way summaries as a byproduct. For example, if you use fun=XLtwoWay, then in order to get column totals for the generated two-way output, you will need to call XLtable1 again on the same data, using the default fun=XLoneWay.

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

See Also

XLoneWay,XLtwoWay,XLunivariate.

Examples

# NOT RUN {
table1<-XLwriteOpen("table1.xls") 

## A default, option-free call generates one-way tables
XLtable1(table1,'cars1',mtcars[,c(2,8:11)])
## You can prettify a bit, first by changing variable names

names(mtcars)[c(2,8:11)]=c("Cylinders","V/S","Auto/Manual","Gears","Carbureutors")
XLtable1(table1,'cars1',mtcars[,c(2,8:11)],
         title="'mtcars': Summary of Categorical Variables",col1=4)

## Now two-way, generated implicitly by specifying 'colvar' (unless fun=XLunivariate)
XLtable1(table1,'cars2',mtcars[,8:11],colvar=mtcars$Cylinders,
         title="Cylinders vs. categorical variables",colTitle="Cylinders")

## Finally, two-way numerical summaries for continuous variables
names(mtcars)[c(1,3:7)]=c('MPG','Engine Vol.','HP',"Axle Ratio","Weight","Quarter Mile")
XLtable1(table1,'carsContinuous',mtcars[,c(1,3:7)],fun=XLunivariate,colvar=mtcars$Cylinders,
         title="Cylinders vs. continuous variables",colTitle="Cylinders")

cat("Look for",paste(getwd(),"table1.xls",sep='/'),"to see the results!\n")
# }