further doc fixes

Author: rubenarslan

R/codebook.R

@@ -6,7 +6,7 @@
 #' 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
+#' 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.
@@ -142,6 +142,8 @@ codebook <- function(results, reliabilities = NULL,
 
 #' Codebook survey overview
 #'
+#' An overview of the number of rows and groups, and of the durations participants
+#' needed to respond (if those data are available).
 #'
 #' @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
@@ -194,6 +196,7 @@ codebook_survey_overview <- function(results, survey_repetition = "single",
 
 #' Codebook missingness
 #'
+#' An overview table of missingness patterns generated using [md_pattern()].
 #'
 #' @param results a data frame
 #' @param indent add # to this to make the headings in the components lower-level. defaults to beginning at h2
@@ -215,7 +218,8 @@ codebook_missingness <- function(results, indent = "##") {
 
 #' Metadata as JSON-LD
 #'
-#' Echo a list of a metadata as JSON-LD in a script tag.
+#' Echo a list of a metadata, generated using [metadata_list()] as JSON-LD in a
+#' script tag.
 #'
 #' @param results a data frame, ideally with attributes set on variables
 #' @export
@@ -234,7 +238,8 @@ metadata_jsonld <- function(results) {
 
 #' Tabular codebook
 #'
-#' Renders a tabular codebook including attributes and data summaries.
+#' Renders a tabular codebook including attributes and data summaries. The table
+#' is generated using [DT::datatable()] and can be exported to CSV, Excel, etc.
 #'
 #'
 #' @param results a data frame, ideally with attributes set on variables
@@ -312,7 +317,7 @@ codebook_component_single_item <- function(item, item_name, indent = '##') {
 #' Codebook metadata table
 #'
 #' will generate a table combining metadata from variable attributes
-#' with data summaries generated using skimr
+#' with data summaries generated using [skimr::skim_to_wide()]
 #'
 #' @param results a data frame, ideally with attributes set on variables
 #'
@@ -483,7 +488,8 @@ metadata_list <- function(results) {
 
 skim_to_wide_labelled <- function(...) {
   suppressMessages(
-    skimr::skim_with(labelled = skimr::get_skimmers()$factor)
+    skimr::skim_with(labelled = skimr::get_skimmers()$factor,
+                     labelled_spss = skimr::get_skimmers()$factor)
   )
   on.exit(skimr::skim_with_defaults())
   skimr::skim_to_wide(...)

R/correct_attributes.R

@@ -8,7 +8,7 @@
 #' @param only_labelled_missings don't set values to missing if there's no label for them
 #' @param negative_values_are_missing by default we label negative values as missing
 #' @param ninety_nine_problems SPSS users often store values as 99/999, should we do this for values with 5*MAD of the median
-#' @param learn_from_labels if there are labels for missings of the form \preformatted{[-1]} no answer, set -1 in the data to the corresponding tagged missing
+#' @param learn_from_labels if there are labels for missings of the form `[-1] no answer`, set -1 in the data to the corresponding tagged missing
 #' @param missing also set these values to missing (or enforce for 99/999 within 5*MAD)
 #' @param non_missing don't set these values to missing
 #' @param vars only edit these variables
@@ -124,7 +124,7 @@ detect_missings <- function(data, only_labelled_missings = TRUE,
 #'
 #' You can use this function if some of your items have lost their attributes during wrangling
 #' Variables have to have the same name (Duh) and no attributes should be overwritten.
-#' But use with care.
+#' But use with care. Similar to [labelled::copy_labels()].
 #'
 #'
 #' @param df_no_attributes the data frame with missing attributes
@@ -156,8 +156,7 @@ rescue_attributes <- function(df_no_attributes, df_with_attributes) {
 #' Detect item scales
 #'
 #' Did you create aggregates of items like this
-#' scale <- scale_1 + scale_2R + scale_3R
-#' ?
+#' `scale <- scale_1 + scale_2R + scale_3R`?
 #' If you run this function on a dataset, it will detect these
 #' relationships and set the appropriate attributes. Once they are set,
 #' the codebook package can perform reliability computations for you.
@@ -207,7 +206,7 @@ detect_scales <- function(data, quiet = FALSE) {
 
 #' Zap attributes
 #'
-#' Modelled on havens zap_labels, but more encompassing. By default removes
+#' Modelled on [haven::zap_labels()], but more encompassing. By default removes
 #' the following attributes:
 #' format.spss, format.sas, format.stata, label, labels, na_values, na_range,
 #' display_width
@@ -258,7 +257,7 @@ zap_attributes.data.frame <- function(x, attributes = NULL) {
 
 #' Zap variable label
 #'
-#' Modelled on havens zap_labels, zaps variable labels.
+#' Modelled on [haven::zap_labels()], zaps variable labels (not value labels).
 #'
 #' @param x the data frame or variable
 #' @export
@@ -270,6 +269,6 @@ zap_label.data.frame <- function(x) {
   x
 }
 zap_label.default <- function(x) {
-  attributes(x)$label <- NULL
+  attr(x, "label") <- NULL
   x
 }

R/misc.R

@@ -14,12 +14,12 @@ require_package <- function(package) {
 
 #' Missing data patterns
 #'
-#' Generate missingness patterns using mice, with options to reduce
-#' the complexity of the output.
+#' Generate missingness patterns using [mice::md.pattern()],
+#' with options to reduce the complexity of the output.
 #'
 #' @param data the dataset
 #' @param only_vars_with_missings defaults to TRUE, omitting variables that have no missings
-#' @param min_freq mininum number of rows to have this missingness pattern
+#' @param min_freq minimum number of rows to have this missingness pattern
 #' @export
 #' @examples
 #' data("nhanes", package = "mice")
@@ -133,3 +133,36 @@ export_table <- function(df) {
                   pageLength = 200
                 ))
 }
+
+
+
+
+#' Summary function for labelled vector
+#'
+#'
+#' @param object a labelled vector
+#' @param ... passed to summary.factor
+#'
+#' @export
+#' @examples
+#' example("labelled", "haven")
+#' summary(x)
+#'
+summary.labelled <- function(object, ...) {
+  summary(haven::as_factor(object, levels = "both"), ...)
+}
+
+#' Summary function for labelled_spss vector
+#'
+#'
+#' @param object a labelled_spss vector
+#' @param ... passed to summary.factor
+#'
+#' @export
+#' @examples
+#' example("labelled", "haven")
+#' summary(x)
+#'
+summary.labelled_spss <- function(object, ...) {
+  summary(haven::as_factor(object, levels = "both"), ...)
+}

R/plot_helpers.R

@@ -1,7 +1,8 @@
 #' Derive a likert object from items
 #'
 #' Pass a data.frame containing several items composing one scale, get a
-#' likert object, which you can plot. Intelligently makes use of labels and value labels if present.
+#' [likert::likert()] object, which you can plot.
+#' Intelligently makes use of labels and value labels if present.
 #'
 #' @param items a data frame of items composing one scale
 #'

R/psych_print.R

@@ -1,6 +1,6 @@
-#' Pretty-print a psych::alpha object
+#' Pretty-print a Cronbach's alpha object
 #'
-#' Make the tables HTML instead of code.
+#' Turn a [psych::alpha()] object into HTML tables.
 #'
 #' @param x a psych alpha object
 #' @param indent add # to this to make the headings in the components lower-level. defaults to beginning at h5
@@ -15,9 +15,9 @@ knit_print.alpha <- function(x, indent = '#####', ...) {
   asis_knit_child(require_file("_knit_print_psych.Rmd"))
 }
 
-#' Print a psych::multilevel.reliability object for knitr
+#' Print a [psych::multilevel.reliability()] object for knitr
 #'
-#' Just prints the normal output.
+#' Just prints the normal output of [psych::multilevel.reliability()].
 #'
 #' @param x a psych alpha object
 #' @param indent add # to this to make the headings in the components lower-level. defaults to beginning at h5
@@ -35,9 +35,9 @@ knit_print.multilevel <- function(x, indent = '#####', ...) {
 }
 
 
-#' Print a stats::cor.test object for knitr
+#' Print a [stats::cor.test()] object for knitr
 #'
-#' Just prints the normal output.
+#' Just prints the normal output of [stats::cor.test()].
 #'
 #' @param x a psych alpha object
 #' @param indent add # to this to make the headings in the components lower-level. defaults to beginning at h5
@@ -52,33 +52,3 @@ knit_print.htest <- function(x, indent = '#####', ...) {
     paste0(utils::capture.output(print(x)), collapse = "\n"),
     "\n```\n\n\n"))
 }
-
-#' Summary function for labelled vector
-#'
-#'
-#' @param object a labelled vector
-#' @param ... passed to summary.factor
-#'
-#' @export
-#' @examples
-#' example("labelled", "haven")
-#' summary(x)
-#'
-summary.labelled <- function(object, ...) {
-  summary(haven::as_factor(object, levels = "both"), ...)
-}
-
-#' Summary function for labelled_spss vector
-#'
-#'
-#' @param object a labelled_spss vector
-#' @param ... passed to summary.factor
-#'
-#' @export
-#' @examples
-#' example("labelled", "haven")
-#' summary(x)
-#'
-summary.labelled_spss <- function(object, ...) {
-  summary(haven::as_factor(object, levels = "both"), ...)
-}

R/reliability.R

@@ -1,8 +1,12 @@
 #' Compute reliabilities
 #'
 #' If you pass the object resulting from a call to formr_results to this function, it will compute reliabilities for each scale.
-#' Internally, each reliability computation is passed to a future. If you are calculating multilevel reliabilities, it may be worthwhile to parallelise this operation using future::plan
-#' If you don't plan on any complicated parallelisation, you probably do not need to call this function directly, but can rely on it being automatically called during codebook generation.
+#' Internally, each reliability computation is passed to a [future::future()].
+#' If you are calculating multilevel reliabilities, it may be worthwhile to
+#' parallelise this operation using [future::plan()].
+#' If you don't plan on any complicated parallelisation, you probably do not
+#' need to call this function directly, but can rely on it being automatically
+#' called during codebook generation.
 #' If you do plan to do that, you can pass the results of this operation to the codebook function.
 #'
 #' @param results a formr results table with attributes set on items and scales

R/rmarkdown_helpers.R

@@ -2,14 +2,14 @@
 #'
 #' This slightly modifies the [knitr::knit_child()] function to have different defaults.
 #' - the environment defaults to the calling environment.
-#' - the output receives the class knit_asis, so that the output will be rendered "as is" by knitr when calling inside a chunk (no need to set results='asis' as a chunk option).
-#' - defaults to quiet = TRUE
+#' - the output receives the class `knit_asis`, so that the output will be rendered "as is" by knitr when calling inside a chunk (no need to set `results='asis'` as a chunk option).
+#' - defaults to `quiet = TRUE`
 #'
-#' Why default to the calling environment? Typically this function defaults to the global environment. This makes sense if you want to use knit_children in the same context as the rest of the document.
-#' However, you may also want to use knit_children inside functions to e.g. summarise a regression using a set of commands (e.g. plot some diagnostic graphs and a summary for a regression nicely formatted).
+#' Why default to the calling environment? Typically this function defaults to the global environment. This makes sense if you want to use knit children in the same context as the rest of the document.
+#' However, you may also want to use knit children inside functions to e.g. summarise a regression using a set of commands (e.g. plot some diagnostic graphs and a summary for a regression nicely formatted).
 #'
 #' Some caveats:
-#' - the function has to return to the top-level. There's no way to [cat()] this from loops or an if-condition without without setting results='asis'. You can however concatenate these objects with [paste.knit_asis()]
+#' - the function has to return to the top-level. There's no way to [cat()] this from loops or an if-condition without without setting `results='asis'`. You can however concatenate these objects with [paste.knit_asis()]
 #'
 #'
 #' @param input if you specify a file path here, it will be read in before being passed to knitr (to avoid a working directory mess)
@@ -71,13 +71,13 @@ asis_knit_child <- function(input = NULL, text = NULL, ...,
 
 #' Paste and output as is (render markup)
 #'
-#' Helper function for knit_asis objects, useful when e.g. [asis_knit_child()] was used in a loop.
+#' Helper function for `knit_asis` objects, useful when e.g. [asis_knit_child()] was used in a loop.
 #'
-#' Works like [paste()] with both the sep and the collapse argument set to two empty lines
+#' Works like [base::paste()] with both the sep and the collapse argument set to two empty lines
 #'
-#' @param ... passed to [paste()]
-#' @param sep defaults to two empty lines, passed to [paste()]
-#' @param collapse defaults to two empty lines, passed to [paste()]
+#' @param ... passed to [base::paste()]
+#' @param sep defaults to two empty lines, passed to [base::paste()]
+#' @param collapse defaults to two empty lines, passed to [base::paste()]
 #'
 #' @export
 #' @examples
@@ -86,7 +86,7 @@ paste.knit_asis <- function(..., sep = "\n\n\n", collapse = "\n\n\n") {
   knitr::asis_output(paste(..., sep = sep, collapse = collapse))
 }
 
-#' Print new lines in knit_asis outputs
+#' Print new lines in `knit_asis` outputs
 #'
 #' @param x the knit_asis object
 #' @param ... ignored
@@ -101,12 +101,14 @@ print.knit_asis <- function(x, ...) {
 #' Render codebook based on file
 #'
 #'
-#' Render text
+#' Submit a data file and an rmarkdown template as a file to generate a codebook.
+#' Used chiefly in the webapp.
 #'
-#' @param file file to make codebook from (sav, rds, dta, etc.)
+#' @param file path to a file to make codebook from (sav, rds, dta, por, xpt, csv, csv2, tsv, etc.)
 #' @param text codebook template
 #' @param remove_file whether to remove file after rendering
 #' @param ... all other arguments passed to [rmarkdown::render()]
+#' @md
 #'
 #' @export
 

cran-comments.md

@@ -11,7 +11,7 @@ This is a second resubmission. In this version I have:
     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
+* slightly changed the docs to be clearer and use markdown to link functions
 
 In the first resubmission I