crunch (version 1.20.0)

tabBook: Compute a Tab Book

Description

This function allows you to generate a tab book from a multitable and data. As with other functions, you can select the rows and columns you want to work with by subsetting the dataset you pass into the function.

Usage

tabBook(multitable, dataset, weight = crunch::weight(dataset),
  format = c("json", "xlsx"), file, ...)

Arguments

multitable

a Multitable object

dataset

CrunchDataset, which may have been subsetted with a filter expression on the rows and a selection of variables on the columns.

weight

a CrunchVariable that has been designated as a potential weight variable for dataset, or NULL for unweighted results. Default is the currently applied weight.

format

character export format: currently supported values are "json" (default) and "xlsx".

file

character local filename to write to. A default filename will be generated from the multitable's name if one is not supplied and the "xlsx" format is requested. Not required for "json" format export.

...

Additional "options" passed to the tab book POST request.

Value

If "json" format is requested, the function returns an object of class TabBookResult, containing a list of MultitableResult objects, which themselves contain CrunchCubes. If "xlsx" is requested, the function invisibly returns the filename (file, if specified, or the the autogenerated file name). If you request "json" and wish to access the JSON data underlying the TabBookResult, pass in a path for file and you will get a JSON file written there as well.

Details

By specifying a "json" format, instead of generating an Excel workbook, you'll get a TabBookResult object, containing nested CrunchCube results. You can then further format these and construct custom tab reports.

Examples

# NOT RUN {
m <- newMultitable(~ gender + age4 + marstat, data=ds)
tabBook(m, ds[ds$income > 1000000,], format="xlsx", file="wealthy-tab-book.xlsx")
book <- tabBook(m, ds) # Returns a TabBookResult
tables <- prop.table(book, 2)
# }