diff --git a/DESCRIPTION b/DESCRIPTION index f398efb4..d0ce2bc1 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -18,8 +18,7 @@ License: LGPL (>= 3) Remotes: haozhu233/kableExtra Depends: R (>= 3.5.0), - crunch, - kableExtra (>= 1.1.0.9000) + crunch Imports: rlang, openxlsx, @@ -33,7 +32,8 @@ Suggests: jsonlite, knitr, rmarkdown, - testthat (>= 2.1.0) + testthat (>= 2.1.0), + kableExtra (>= 1.1.0.9000) RoxygenNote: 7.1.0 VignetteBuilder: knitr Encoding: UTF-8 diff --git a/NEWS.md b/NEWS.md index de18c2a2..2cf3e61e 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,9 +1,13 @@ ## crunchtabs 1.2.8 +- Documentation for generating codebooks (#180) +- Tests and fixes for broken tests (#176) +- Spacing and font type for codebooks (#178) - Additional refinements for codebooks such as title, subtitle, sample description (#152) - Fixes for warnings in existing code (#158) - Bugfix for logo assignment in excel (#155) -- Added pagebreak_in_banner which stops multi-banner crosstabs from being spread across pages using "to be continued" (#161) +- Added pagebreak_in_banner which stops multi-banner crosstabs from being spread across pages using "to be continued" (#161, #169) +- Major rework of codebooks (#165, #172, #170, #160, #159) ## crunchtabs 1.2.7 diff --git a/README.md b/README.md index 5ee28393..17ad0ae6 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,12 @@ # crunchtabs +Crunchtabs allow for the automatic generation of toplines, crosstabulation and codebooks directly from a crunch dataset. + ![CI](https://github.com/Crunch-io/crunchtabs/workflows/CI/badge.svg?branch=master) [![codecov](https://codecov.io/gh/Crunch-io/crunchtabs/branch/master/graph/badge.svg)](https://codecov.io/gh/Crunch-io/crunchtabs) ## Quick Start -For a broader introduction please see our [introductory vignette](https://crunch-io.github.io/crunchtabs/articles/Overview.html) +For a broader introduction please see our [introductory vignette](https://crunch-io.github.io/crunchtabs/articles/Overview.html). For codebooks, see [codebooks]((https://crunch-io.github.io/crunchtabs/articles/Codebooks.html)) ### 1. Install tinytex @@ -73,6 +75,24 @@ writeExcel(ct_summary, filename = "output") # output.xlsx will be written ![Cross Tabulation Excel Example from the Example Dataset](vignettes/example-003-excel-ct.png) + +## Generating Codebooks + +To generate a codebook, you must install the development version of kableExtra + +``` +devtools::install_github("haozhu233/kableExtra") + +# library(crunchtabs) +# login() + +ds = loadDataset("Example dataset") +# Use ds = newExampleDataset() if not found! + +writeCodeBookLatex(ds) +``` + + ## For developers The repository includes a Makefile to facilitate some common tasks. diff --git a/inst/codebook_latex_wrap.tex b/inst/codebook_latex_wrap.tex index a2b501a9..799c9642 100644 --- a/inst/codebook_latex_wrap.tex +++ b/inst/codebook_latex_wrap.tex @@ -68,8 +68,6 @@ <> <> -<> - \begin{document} \setlength{\tabcolsep}{1em} \setlength{\LTleft}{0pt} @@ -78,6 +76,7 @@ \vspace{.25in} <> +<> <> \renewcommand{\listtablename}{Table of Contents} diff --git a/tests/testthat/fixtures/writeCodeBookLatexFull.rds b/tests/testthat/fixtures/writeCodeBookLatexFull.rds index df80087a..46c4cd87 100644 Binary files a/tests/testthat/fixtures/writeCodeBookLatexFull.rds and b/tests/testthat/fixtures/writeCodeBookLatexFull.rds differ diff --git a/tests/testthat/fixtures/writeCodeBookLatexLongCat.rds b/tests/testthat/fixtures/writeCodeBookLatexLongCat.rds index b61cc632..37cb56b1 100644 Binary files a/tests/testthat/fixtures/writeCodeBookLatexLongCat.rds and b/tests/testthat/fixtures/writeCodeBookLatexLongCat.rds differ diff --git a/tests/testthat/fixtures/writeCodeBookLatexOne.rds b/tests/testthat/fixtures/writeCodeBookLatexOne.rds index 184a5eee..1bfdca3a 100644 Binary files a/tests/testthat/fixtures/writeCodeBookLatexOne.rds and b/tests/testthat/fixtures/writeCodeBookLatexOne.rds differ diff --git a/vignettes/Codebooks.Rmd b/vignettes/Codebooks.Rmd new file mode 100644 index 00000000..e995b031 --- /dev/null +++ b/vignettes/Codebooks.Rmd @@ -0,0 +1,111 @@ +--- +title: "Codebooks" +author: "Brandon Bertelsen" +date: "`r Sys.Date()`" +output: + rmarkdown::html_vignette: + toc: true +vignette: > + %\VignetteIndexEntry{Vignette Title} + %\VignetteEngine{knitr::knitr} + %\VignetteEncoding{UTF-8} +--- + +## Codebooks! + +A codebook is used as a reference to document the contents of a survey by displaying unweighted counts and other types of survey metadata that may be important to someone using those data outside of the context of the crunch web application or other toplines/crosstabs prepared by crunchtabs + +### Generating Codebooks + +Creating a codebook from a crunch dataset is easy! In the examples below we will work with the example dataset. + +```{r, eval = FALSE} +library(crunchtabs) +login() +# If you already have an example dataset available in your account +# ds <- loadDataset("Example dataset") +ds <- newExampledataset() + +writeCodeBookLatex(ds) +``` + +![Codebook Example](codebook-example-001.png) + + +By default, if you supply a dataset to the the function `writeCodeBookLatex` it will name the resulting file after the dataset as well as set a title on the document with the same moniker. The resulting PDF document will be automatically opened after a short delay as the dataset is manipulated and written to PDF. + +In some cases, your dataset may have an extremely long or otherwise problematic name, in this case, you can use the URL to the dataset. + +```{r, eval = FALSE} +writeCodeBookLatex(ds, url = "https://api.crunch.io/datasets/") +``` + +> Appendices: If your data contain a categorical question with more than 20 categories, it will be pushed into an appendix by default. You can control this behavior by using the parameter `appendx = FALSE` + +## Options + +There are a number of optional settings that you can control such as: displaying a table of contents, a sample descriptions, changing the title or subtitle, or adding a logo. In this section, we will present each of these. + +### Table of Contents + +A table of contents can be added by using the `table_of_contents` parameter. Providing a table of contents that shows the variable alias (`crunch::alias`) followed by a short description of the variable that is derived from the crunch name (`crunch::name`) and, of course, the page number where the related codebook item(s) can be found. + +```{r, eval = FALSE} +writeCodeBookLatex(ds, table_of_contents = TRUE) +``` + +![Table of contents](codebook-toc-example-002.png) + +### Appendices + +By default, an appendix will be created for any categorical question that has more than 20 categories. This is done with the intent to avoid useless scrolling by the user. However, should you not care for an appendix you can use the parameter `appendix = FALSE`. If you choose to not use an appendix, it may also be desirable to set `suppress_zero_counts=TRUE` to avoid long presentations of empty categories in dataset order. + +```{r, eval = FALSE} +writeCodeBookLatex(ds, appendix = FALSE) +``` + +### Titles, Sub-headings and other Descriptives + +Currently you can change the title and subtitle as well as provide descriptives like sample description and field window. + +```{r, eval = FALSE} +writeCodeBookLatex( + ds, + title = "An Amazing Title", + subtitle = "A Breathtaking Subtitle", + field_period = "To infinity... and beyond!", + sample_desc = "US Voting Adults", + preamble = "e^{ \\pm i\\theta } = \\cos \\theta \\pm i\\sin \\theta" +) +``` + +![Table of contents](codebook-options-example-003.png) + +### Logos + +Default logos for YouGov and YouGov Blue have been included in the package for easy reference. If neither have suit your purposes you can also specify a path to a PNG formatted image. We recommend an image size of 50 pixels in height and 250-350 pixels in width. If you would like your sub-brand logo added to the package please submit an issue on github (https://github.com/Crunch-io/crunchtabs/issues) + +```{r, eval = FALSE} +writeCodeBookLatex(ds, logo = "yougov") +# writeCodeBookLatex(ds, logo = "ygblue") +``` + +![Table of contents](codebook-logos-example-004.png) + +### Suppress Zeroes + +Although not recommended, there are some questions that have a significant amount of zero-filled categories (country of residence for example). This can lead to the end-user of the codebook scrolling through information that is useless to them. + +```{r, eval = FALSE} +writeCodeBookLatex(ds, suppress_zero_counts = TRUE) +``` + +### Table Alignment + +The table alignment on the page can be adjusted to one of: "l" for left (the default), "c" for center, or "r" for right by using the `position` parameter. + +```{r, eval = FALSE} +writeCodeBookLatex(ds, position = "c") +``` + +![Table of contents](codebook-centered-example-005.png) diff --git a/vignettes/FAQ.Rmd b/vignettes/FAQ.Rmd index 45f42e1a..aadb1fa9 100644 --- a/vignettes/FAQ.Rmd +++ b/vignettes/FAQ.Rmd @@ -225,6 +225,15 @@ ct = sortAliases(ct, var = "d", pin_to_bottom = "Don't know") writeLatex(ct, ...) ``` +### How do I stop crosstabs from breaking in the middle of a tab? + +In 1.2.8 a new feature was added that allows you to avoid page breaks within a banner. Some users were adding manual latex page breaks to avoid this behavior. Now, you can set the `pagebreak_in_banner` parameter to FALSE and crunchtabs will automatically push the banner to the next page to avoid a page break. + +```{r} +crosstabs_theme <- themeNew(..., pagebreak_in_banner = FALSE) +``` + + ### How do I request a new feature? We welcome features requests as new issues to the [crunchtabs github repository](https://github.com/Crunch-io/crunchtabs/issues) diff --git a/vignettes/codebook-centered-example-005.png b/vignettes/codebook-centered-example-005.png new file mode 100644 index 00000000..817fd617 Binary files /dev/null and b/vignettes/codebook-centered-example-005.png differ diff --git a/vignettes/codebook-example-001.png b/vignettes/codebook-example-001.png new file mode 100644 index 00000000..5d4a4d02 Binary files /dev/null and b/vignettes/codebook-example-001.png differ diff --git a/vignettes/codebook-logos-example-004.png b/vignettes/codebook-logos-example-004.png new file mode 100644 index 00000000..4179054f Binary files /dev/null and b/vignettes/codebook-logos-example-004.png differ diff --git a/vignettes/codebook-options-example-003.png b/vignettes/codebook-options-example-003.png new file mode 100644 index 00000000..23289bf3 Binary files /dev/null and b/vignettes/codebook-options-example-003.png differ diff --git a/vignettes/codebook-toc-example-002.png b/vignettes/codebook-toc-example-002.png new file mode 100644 index 00000000..b10ed438 Binary files /dev/null and b/vignettes/codebook-toc-example-002.png differ