tabBook {crunch}

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),
  output_format = c("json", "xlsx", "csv"),
  file,
  filter = NULL,
  use_legacy_endpoint = envOrOption("use.legacy.tabbook.endpoint", FALSE, expect_lgl =
    TRUE),
  ...
)

Arguments

multitable

a Multitable object

dataset

CrunchDataset, which may be subset with a filter expression on the rows, and a selection of variables to use 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.

output_format

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

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.

filter

a Crunch filter object or a vector of names of filters defined in the dataset.

use_legacy_endpoint

Logical, indicating whether to use a 'legacy' endpoint for compatibility (this endpoint will be removed in the future). Defaults to FALSE, but can be set in the function, or with the environment variable R_USE_LEGACY_TABBOOK_ENDPOINT or R option use.legacy.tabbook.endpoint.

...

Additional "options" passed to the tab book POST request. More details can be found in the crunch API documentation

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.

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" or "csv", 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.

Examples

## Not run: 
# Excel export
m <- newMultitable(~ gender + age4 + marstat, data = ds)
tabBook(m, ds, format = "xlsx", file = "wealthy-tab-book.xlsx", filter = "wealthy")

# csv export
tabBook(
    m,
    ds[c("q5a", "q8", "q2a_1", "q2a_2")],
    output_format = "csv",
    file = "tabbook.csv",
    format = list(
        pval_colors = FALSE,
        decimal_places = list(percentages = 0L, other = 2L),
        show_empty = FALSE
    ),
    sig_threshold = 0.05,
    doc_layout = list(toc = FALSE, variable_sheets = "one_sheet"),
    fields = c(
        "col_percent", "row_percent", "count_unweighted", "mean",
        "valid_count_weighted", "valid_count_unweighted"
    ),
    page_layout = list(
        rows = list(
            top = c("base_weighted", "base_unweighted"),
            bottom = c("scale_mean", "scale_median")
        ),
        measure_layout = "long"
    )
)

# JSON export (loads into R)
book <- tabBook(m, ds)
tables <- prop.table(book, 2)


## End(Not run)