- improve docs

- add examples for codebook functions

Author: rubenarslan

.gitignore

@@ -6,3 +6,4 @@ plans/
 tests/test_codebook_*
 tests/test_codebook.html
 inst/doc
+figure/

DESCRIPTION

@@ -1,11 +1,12 @@
 Package: codebook
-Title: Cook Codebooks from Survey Metadata Encoded in Attributes in R
+Title: Automatic Codebooks from Survey Metadata Encoded in Attributes
 Description: Easily automate the following tasks to describe data frames: 
   computing reliabilities (internal consistencies, retest, multilevel) for psychological scales, 
   summarise the distributions of scales and items graphically and using descriptive statistics,
-  combine this information with metadata such as item labels and labelled values that is derived from R attributes.
-  To do so, the package relies on rmarkdown partials. To mark up the metadata you need to use haven semantics.
-Version: 0.5.6
+  combine this information with metadata (such as item labels and labelled values) that is derived from R attributes.
+  To do so, the package relies on 'rmarkdown' partials, so you can generate HTML, PDF, and Word documents. Codebooks
+  are also available as tables (CSV, Excel, etc.).
+Version: 0.5.7
 Authors@R: person("Ruben", "Arslan", email = "ruben.arslan@gmail.com", role = c("aut", "cre"))
 Depends: R (>= 3.0.1)
 URL: https://github.com/rubenarslan/codebook

NEWS.md

@@ -1,3 +1,6 @@
+# codebook 0.5.7
+- changed description and documentation
+
 # codebook 0.5.6
 - changed license to MIT
 

R/codebook.R

@@ -2,9 +2,16 @@
 
 #' Generate rmarkdown codebook
 #'
-#' If you pass the object resulting from a call to formr_results to this function, it will generate a markdown codebook for this object.
+#' Pass a data frame to this function to make a codebook for that dataset.
+#' If the dataset has metadata (attributes) set on its variables, these will be
+#' used to make the codebook more informative. Examples are item, value, and
+#' missing labels.
+#' Data frames imported via [haven::read_dta], [haven::read_sav], or from
+#' [formr.org](https://formr.org) will have these attributes in the right format.
+#' By calling this function inside a knitr code chunk, the
+#' codebook will become part of the document you are generating.
 #'
-#' @param results a formr results table with attributes set on items and scales
+#' @param results a data frame, ideally with attributes set on variables
 #' @param reliabilities a named list with one entry per scale and one or several printable reliability computations for this scale. if NULL, computed on-the-fly using compute_reliabilities
 #' @param survey_repetition defaults to "auto" which is to try to determine the level of repetition from the "session" and "created" variables. Other values are: single, repeated_once, repeated_many
 #' @param missingness_report whether to print a missingness report. Turn off if this gets too complicated and you need a custom solution (e.g. in case of random missings).
@@ -14,7 +21,10 @@
 #'
 #' @export
 #' @examples
-#' # see vignette
+#' # will generate figures in a figure/ subdirectory
+#' data("bfi")
+#' bfi <- bfi[, c("BFIK_open_1", "BFIK_open_1")]
+#' md <- codebook(bfi, survey_repetition = "single", metadata_table = FALSE)
 codebook <- function(results, reliabilities = NULL,
     survey_repetition = c('auto', 'single', 'repeated_once', 'repeated_many'),
     missingness_report = TRUE, metadata_table = TRUE,
@@ -49,10 +59,6 @@ codebook <- function(results, reliabilities = NULL,
                                          "repeated_many"))
     }
   }
-  suppressMessages(
-    skimr::skim_with(labelled = skimr::get_skimmers()$factor)
-  )
-  on.exit(skimr::skim_with_defaults())
 
   if (is.null(reliabilities)) {
     reliabilities <- compute_reliabilities(results, survey_repetition)
@@ -137,11 +143,15 @@ codebook <- function(results, reliabilities = NULL,
 #' Codebook survey overview
 #'
 #'
-#' @param results a formr results table which has the following columns: session, created, modified, expired, ended
+#' @param results a data frame which has the following columns: session, created, modified, expired, ended
 #' @param survey_repetition defaults to single (other values: repeated_once, repeated_many). controls whether internal consistency, retest reliability or multilevel reliability is computed
 #' @param indent add # to this to make the headings in the components lower-level. defaults to beginning at h2
 #'
 #' @export
+#' @examples
+#' # will generate figures in a figure/ subdirectory
+#' data("bfi")
+#' codebook_survey_overview(bfi)
 codebook_survey_overview <- function(results, survey_repetition = "single",
                                      indent = "##") {
   stopifnot(exists("session", results))
@@ -185,10 +195,13 @@ codebook_survey_overview <- function(results, survey_repetition = "single",
 #' Codebook missingness
 #'
 #'
-#' @param results a formr results table which has the following columns: session, created, modified, expired, ended
+#' @param results a data frame
 #' @param indent add # to this to make the headings in the components lower-level. defaults to beginning at h2
 #'
 #' @export
+#' @examples
+#' data("bfi")
+#' codebook_missingness(bfi)
 codebook_missingness <- function(results, indent = "##") {
   options <- list(
     fig.path = paste0(knitr::opts_chunk$get("fig.path"), "overview_"),
@@ -202,10 +215,13 @@ codebook_missingness <- function(results, indent = "##") {
 
 #' Metadata as JSON-LD
 #'
+#' Echo a list of a metadata as JSON-LD in a script tag.
 #'
-#' @param results a formr results table which has the following columns: session, created, modified, expired, ended
-#'
+#' @param results a data frame, ideally with attributes set on variables
 #' @export
+#' @examples
+#' data("bfi")
+#' metadata_jsonld(bfi)
 metadata_jsonld <- function(results) {
   options <- list(
     fig.path = paste0(knitr::opts_chunk$get("fig.path"), "metadata_"),
@@ -221,10 +237,16 @@ metadata_jsonld <- function(results) {
 #' Renders a tabular codebook including attributes and data summaries.
 #'
 #'
-#' @param results a formr results table which has the following columns: session, created, modified, expired, ended
+#' @param results a data frame, ideally with attributes set on variables
 #' @param indent add # to this to make the headings in the components lower-level. defaults to beginning at h2
 #'
 #' @export
+#' @examples
+#' data("bfi")
+#' \dontrun{
+#' # doesn't show interactively, because a html widget needs to be registered
+#' codebook_items(bfi)
+#' }
 codebook_items <- function(results, indent = "##") {
   options <- list(
     fig.path = paste0(knitr::opts_chunk$get("fig.path"), "overview_"),
@@ -245,6 +267,12 @@ codebook_items <- function(results, indent = "##") {
 #' @param indent add # to this to make the headings in the components lower-level. defaults to beginning at h2
 #'
 #' @export
+#' @examples
+#' # will generate figure in a figure/ subdirectory
+#' data("bfi")
+#' bfi <- bfi[,c("BFIK_open", paste0("BFIK_open_", 1:4))]
+#' codebook_component_scale(bfi[,1], "BFIK_open", bfi[,-1],
+#'    reliabilities = list(BFIK_open = psych::alpha(bfi[,-1])))
 codebook_component_scale <- function(scale, scale_name, items, reliabilities,
                                      indent = '##') {
   stopifnot( exists("scale_item_names", attributes(scale)))
@@ -254,6 +282,10 @@ codebook_component_scale <- function(scale, scale_name, items, reliabilities,
     fig.path = paste0(knitr::opts_chunk$get("fig.path"), scale_name, "_"),
     cache.path = paste0(knitr::opts_chunk$get("cache.path"), scale_name, "_")
   )
+  old_opt <- options('knitr.duplicate.label')$knitr.duplicate.label
+  options(knitr.duplicate.label = 'allow')
+  on.exit(options(knitr.duplicate.label = old_opt))
+
   asis_knit_child(require_file("_codebook_scale.Rmd"), options = options)
 }
 
@@ -265,6 +297,10 @@ codebook_component_scale <- function(scale, scale_name, items, reliabilities,
 #' @param indent add # to this to make the headings in the components lower-level. defaults to beginning at h2
 #'
 #' @export
+#' @examples
+#' # will generate figure in a figure/ subdirectory
+#' #' data("bfi")
+#' codebook_component_single_item(bfi$BFIK_open_1, "BFIK_open_1")
 codebook_component_single_item <- function(item, item_name, indent = '##') {
   options <- list(
     fig.path = paste0(knitr::opts_chunk$get("fig.path"), item_name, "_"),
@@ -278,11 +314,14 @@ codebook_component_single_item <- function(item, item_name, indent = '##') {
 #' will generate a table combining metadata from variable attributes
 #' with data summaries generated using skimr
 #'
-#' @param results a data frame
+#' @param results a data frame, ideally with attributes set on variables
 #'
 #' @export
+#' @examples
+#' data("bfi")
+#' codebook_table(bfi)
 codebook_table <- function(results) {
-  skimmed <- skimr::skim_to_wide(results)
+  skimmed <- skim_to_wide_labelled(results)
 
   metadata <- dplyr::bind_rows(
     # var = results$session
@@ -356,9 +395,13 @@ codebook_table <- function(results) {
 #'
 #' Returns a list containing variable metadata (attributes) and data summaries.
 #'
-#' @param results a data frame
+#' @param results a data frame, ideally with attributes set on variables
 #'
 #' @export
+#' @examples
+#' data("bfi")
+#' md_list <- metadata_list(bfi)
+#' md_list$variableMeasured[[20]]
 metadata_list <- function(results) {
   name <- deparse(substitute(results))
   metadata <- attributes(results)
@@ -411,7 +454,7 @@ metadata_list <- function(results) {
         }
 
       }
-      x$data_summary <- skimr::skim_to_wide(results[[var]])
+      x$data_summary <- skim_to_wide_labelled(results[[var]])
       x$data_summary$variable <- NULL
       if (exists("type", x$data_summary)) {
         if (!exists("value", x)) {
@@ -436,3 +479,12 @@ metadata_list <- function(results) {
 
   metadata
 }
+
+
+skim_to_wide_labelled <- function(...) {
+  suppressMessages(
+    skimr::skim_with(labelled = skimr::get_skimmers()$factor)
+  )
+  on.exit(skimr::skim_with_defaults())
+  skimr::skim_to_wide(...)
+}

README.Rmd

@@ -15,19 +15,27 @@ knitr::opts_chunk$set(
 # Codebook Cookbook
 [![Travis-CI Build Status](https://travis-ci.org/rubenarslan/codebook.svg?branch=master)](https://travis-ci.org/rubenarslan/codebook) [![codecov](https://codecov.io/gh/rubenarslan/codebook/branch/master/graph/badge.svg)](https://codecov.io/gh/rubenarslan/codebook)
 
+## Description
+
+Easily automate the following tasks to describe data frames: 
+  computing reliabilities (internal consistencies, retest, multilevel) for psychological scales, 
+  summarise the distributions of scales and items graphically and using descriptive statistics,
+  combine this information with metadata (such as item labels and labelled values) that is derived from R attributes.
+  To do so, the package relies on 'rmarkdown' partials, so you can generate HTML, PDF, and Word documents. Codebooks
+  are also available as tables (CSV, Excel, etc.).
+  
 ## Generate markdown codebooks from the attributes of the variables in your data frame
 
 RStudio and a few of the tidyverse package already usefully display the information contained in the attributes of the variables in your data frame. The [haven](https://github.com/hadley/haven) package also manages to grab variable documentation from SPSS or Stata files.
 
 The codebook package takes those attributes and the data and tries to produce a good-looking codebook, i.e. a place to get an overview of the variables in a dataset. The codebook processes single items, but also "scales", i.e. psychological questionnaires that are aggregated to extract a construct. For scales, the appropriate reliability coefficients (internal consistencies for single measurements, retest reliabilities for repeated measurements, multilevel reliability for multilevel data) are computed.
 For items and scales, the distributions are summarised graphically and numerically.
 
-This package integrates tightly with formr ([formr.org](https://formr.org)), an online survey framework and especially the data frames produced and marked up by the [formr R package](https://github.com/rubenarslan/formr), but is completely independent of it.
-
-To do this, this package uses rmarkdown _partials_, that can be integrated in a larger rmarkdown document and then translated to HTML or PDF format.
+This package integrates tightly with formr ([formr.org](https://formr.org)), an online survey framework and especially the data frames produced and marked up by the [formr R package](https://github.com/rubenarslan/formr). However, codebook is completely independent of it.
 
 ## Documentation
-Confer the help or: https://rubenarslan.github.io/codebook
+Confer the help or: https://rubenarslan.github.io/codebook.
+See the [vignette](https://rubenarslan.github.io/codebook/articles/codebook.html) for a quick example of an HTML document generated using `codebook`.
 
 ## Use as a webapp
 

README.md

@@ -5,21 +5,24 @@ Codebook Cookbook
 
 [![Travis-CI Build Status](https://travis-ci.org/rubenarslan/codebook.svg?branch=master)](https://travis-ci.org/rubenarslan/codebook) [![codecov](https://codecov.io/gh/rubenarslan/codebook/branch/master/graph/badge.svg)](https://codecov.io/gh/rubenarslan/codebook)
 
+Description
+-----------
+
+Easily automate the following tasks to describe data frames: computing reliabilities (internal consistencies, retest, multilevel) for psychological scales, summarise the distributions of scales and items graphically and using descriptive statistics, combine this information with metadata (such as item labels and labelled values) that is derived from R attributes. To do so, the package relies on 'rmarkdown' partials, so you can generate HTML, PDF, and Word documents. Codebooks are also available as tables (CSV, Excel, etc.).
+
 Generate markdown codebooks from the attributes of the variables in your data frame
 -----------------------------------------------------------------------------------
 
 RStudio and a few of the tidyverse package already usefully display the information contained in the attributes of the variables in your data frame. The [haven](https://github.com/hadley/haven) package also manages to grab variable documentation from SPSS or Stata files.
 
 The codebook package takes those attributes and the data and tries to produce a good-looking codebook, i.e. a place to get an overview of the variables in a dataset. The codebook processes single items, but also "scales", i.e. psychological questionnaires that are aggregated to extract a construct. For scales, the appropriate reliability coefficients (internal consistencies for single measurements, retest reliabilities for repeated measurements, multilevel reliability for multilevel data) are computed. For items and scales, the distributions are summarised graphically and numerically.
 
-This package integrates tightly with formr ([formr.org](https://formr.org)), an online survey framework and especially the data frames produced and marked up by the [formr R package](https://github.com/rubenarslan/formr), but is completely independent of it.
-
-To do this, this package uses rmarkdown *partials*, that can be integrated in a larger rmarkdown document and then translated to HTML or PDF format.
+This package integrates tightly with formr ([formr.org](https://formr.org)), an online survey framework and especially the data frames produced and marked up by the [formr R package](https://github.com/rubenarslan/formr). However, codebook is completely independent of it.
 
 Documentation
 -------------
 
-Confer the help or: <https://rubenarslan.github.io/codebook>
+Confer the help or: <https://rubenarslan.github.io/codebook>. See the [vignette](https://rubenarslan.github.io/codebook/articles/codebook.html) for a quick example of an HTML document generated using `codebook`.
 
 Use as a webapp
 ---------------

cran-comments.md

@@ -1,5 +1,19 @@
 ## Resubmission
-This is a resubmission. In this version I have:
+This is a second resubmission. In this version I have:
+
+* changed the title to omit "in R"
+* changed the description to put 'rmarkdown' in single quotes
+* added small executable examples to the codebook functions in the codebook.R. 
+  Some of these examples will, by necessity, create files. 
+  I know other examples also do this (e.g. knitr), but I'm unsure whether it's 
+  desirable. I've noted/warned about file creation in every example.
+  * the function `codebook_items` cannot be run in examples. 
+    It causes an error during checking, probably because it indirectly includes 
+    an htmlwidget. It works fine in non-example use (tests, vignettes, 
+    interactively). Therefore, I wrapped the example in dontrun.
+* slightly changed the docs to be clearer
+
+In the first resubmission I
 
 * changed the LICENSE to MIT and used the appropriate file template (before I had BSD_2_clause and didn't know I had to use a specific file template)