Final revisions for first CRAN release.

.Rbuildignore

@@ -18,3 +18,5 @@
 ^update_csl.sh$
 ^CITATION\.cff$
 ^vignettes/papaja.Rmd$
+^vignettes/papaja.tex$
+^CRAN-SUBMISSION$

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: papaja
 Title: Prepare American Psychological Association Journal Articles with
   R Markdown
-Version: 0.1.0.9999
+Version: 0.1.0
 Description: Tools to create dynamic, submission-ready manuscripts, which
   conform to American Psychological Association manuscript guidelines. We
   provide R Markdown document formats for manuscripts (PDF and Word) and
@@ -15,7 +15,7 @@ Authors@R: c(
     , person("Joseph V.", "Casillas", email = "joseph.casillas@rutgers.edu", role = c("ctb"))
     , person("Rudolf", "Siegel", email = "rudolf.siegel@uni-saarland.de", role = c("ctb"))
   )
-Date: 2022-03-18
+Date: 2022-06-22
 URL: https://github.com/crsh/papaja
 BugReports: https://github.com/crsh/papaja/issues
 Depends:

NAMESPACE

@@ -70,6 +70,7 @@ S3method(sanitize_terms,list)
 S3method(summary,papaja_wsci)
 S3method(transmute_df_into_label,apa_results)
 S3method(transmute_df_into_label,apa_results_table)
+export(add_equals)
 export(add_glue_to_apa_results)
 export(apa6_doc)
 export(apa6_docx)

R/apa6_formats.R

@@ -25,8 +25,8 @@
 #'   When creating PDF documents the output device for figures defaults to
 #'   \code{c("pdf", "png")}, so that each figure is saved in all four formats
 #'   at a resolution of 300 dpi.
-#' @seealso [bookdown::pdf_document2], [bookdown::word_document2]
-#' @examples NULL
+#' @return R Markdown output format to pass to [rmarkdown::render()]
+#' @seealso [bookdown::pdf_document2()], [bookdown::word_document2()]
 #' @export
 
 apa6_pdf <- function(
@@ -83,14 +83,14 @@ apa6_pdf <- function(
   config$knitr$opts_chunk$dpi <- 300
   config$clean_supporting <- FALSE # Always keep images files
 
-  config$pre_knit <- function(input, ...) { modify_input_file(input=input) }
+  config$pre_knit <- function(input, ...) { modify_input_file(input = input) }
 
   ## Overwrite preprocessor to set CSL defaults
   saved_files_dir <- NULL
 
   # Preprocessor functions are adaptations from the RMarkdown package
   # (https://github.com/rstudio/rmarkdown/blob/master/R/pdf_document.R)
-  config$pre_processor <- function(metadata, input_file, runtime, knit_meta, files_dir, output_dir) {
+  pre_processor <- function(metadata, input_file, runtime, knit_meta, files_dir, output_dir) {
     # save files dir (for generating intermediates)
     saved_files_dir <<- files_dir
 
@@ -108,7 +108,7 @@ apa6_pdf <- function(
     args
   }
 
-  config$post_processor <- function(metadata, input_file, output_file, clean, verbose) {
+  post_processor <- function(metadata, input_file, output_file, clean, verbose) {
 
     output_text <- readLines(output_file, encoding = "UTF-8")
 
@@ -168,6 +168,9 @@ apa6_pdf <- function(
     bookdown_post_processor(metadata = metadata, input = input_file, output = output_file, clean = clean, verbose = verbose)
   }
 
+  config$pre_processor <- pre_processor
+  config$post_processor <- post_processor
+
   config
 }
 
@@ -227,7 +230,7 @@ apa6_docx <- function(
 
   # Preprocessor functions are adaptations from the RMarkdown package
   # (https://github.com/rstudio/rmarkdown/blob/master/R/pdf_document.R)
-  config$pre_processor <- function(metadata, input_file, runtime, knit_meta, files_dir, output_dir, from = .from) {
+  pre_processor <- function(metadata, input_file, runtime, knit_meta, files_dir, output_dir, from = .from) {
     # save files dir (for generating intermediates)
     saved_files_dir <<- files_dir
 
@@ -250,7 +253,7 @@ apa6_docx <- function(
     args
   }
 
-  config$post_processor <- function(metadata, input_file, output_file, clean, verbose) {
+  post_processor <- function(metadata, input_file, output_file, clean, verbose) {
 
     # Add correct running head
     docx_files <- zip::zip_list(zipfile = output_file)$filename
@@ -282,6 +285,9 @@ apa6_docx <- function(
     )
   }
 
+  config$pre_processor <- pre_processor
+  config$post_processor <- post_processor
+
   config
 }
 

R/apa_factorial_plot.R

@@ -37,7 +37,7 @@
 #' @param ylab Character or expression. Label for *y* axis.
 #' @param main Character or expression. For up to two factors, simply specify the main title. If you stratify the data by more than two factors,
 #' either specify a single value that will be added to automatically generated main title, *or* specify an array of multiple titles, one for each plot area.
-#' @return A (nested) list of plot options. *Note that the structure of the return value is about to change in a forthcoming release of papaja.*
+#' @return A named (nested) list of plot options including raw and derived data. *Note that the structure of the return value is about to change in a forthcoming release of papaja.*
 #' @inheritDotParams graphics::plot.window
 #' @details
 #'    The measure of dispersion can be either [conf_int()] for between-subjects confidence intervals, [se()] for standard errors,
@@ -392,7 +392,9 @@ apa_factorial_plot.default <- function(
     output$args <- do.call("apa_factorial_plot_single", ellipsis)
   }
 
-  old.mfrow <- par("mfrow") # Save original plot architecture
+  oldpar <- par(no.readonly = TRUE)
+  on.exit(par(oldpar))
+
   ## Three factors
 
 
@@ -449,7 +451,6 @@ apa_factorial_plot.default <- function(
 
       output$args[[paste0("plot", i)]] <- do.call("apa_factorial_plot_single", ellipsis.i)
     }
-    par(mfrow=old.mfrow)
   }
 
   ## Four factors
@@ -495,7 +496,6 @@ apa_factorial_plot.default <- function(
         output$args[[paste0("plot", i, j)]] <- do.call("apa_factorial_plot_single", ellipsis.i)
       }
     }
-    par(mfrow=old.mfrow)
   }
   invisible(output)
 }

R/apa_interval.R

@@ -26,16 +26,14 @@
 #'   multiple intervals are returned as a named `list` of `character` vectors
 #'   of length 1.
 #'
-#' @seealso \code{\link{apa_num}}
+#' @seealso [apa_num()]
 #' @export
 #' @examples
-#' \dontrun{
 #' apa_confint(1, 2, conf.int = 0.95)
 #' apa_confint(c(1, 2), conf.int = 0.95)
 #' apa_confint(matrix(c(1, 2), ncol = 2), conf.int = 0.95)
 #' apa_confint(confint(lm(cars)))
 #' apa_confint(confint(lm(cars)), digits = 3)
-#' }
 
 apa_interval <- function(
     x

R/apa_num.R

@@ -28,6 +28,12 @@
 #'   `x` exceeds the length of the parameter vectors. If `x` is a `matrix` or
 #'   `data.frame`, the vectors specify the formatting of either rows or columns
 #'   according to the value of `margin`.
+#'
+#'   We recommend to use `apa_num()`, rather than `printnum()` or `print_num()`,
+#'   which are aliases kept only for backward compatibility.
+#' @return An object of the same class as `x` with all numeric values converted
+#'   to character.
+#' @seealso [apa_p()], [apa_df()]
 #' @examples
 #' apa_num(1/3)
 #' apa_num(1/3, gt1 = FALSE)
@@ -379,6 +385,8 @@ apa_num.tiny_labelled <-function(x, ...){
 #' @param x Numeric. The \emph{p} value(s) to report.
 #' @param digits Integer. The desired number of digits after the decimal point, passed on to \code{\link{formatC}}.
 #' @inheritParams apa_num.numeric
+#' @inherit apa_num return
+#' @seealso [apa_num()], [apa_df()]
 #' @examples
 #' apa_p(0.05)
 #' apa_p(0.0005)
@@ -422,6 +430,10 @@ print_p <- apa_p
 #' @param elementwise Logical. Determines whether the number of trailing digits
 #'   should be determined for each element of `x` separately (the default),
 #'   or for the complete vector `x`.
+#' @inherit apa_num return
+#' @seealso [apa_num()], [apa_p()]
+#' @examples
+#' apa_df(c(1, 1.23151))
 #' @export
 
 apa_df <- function(x, digits = 2L, elementwise = TRUE) {
@@ -460,8 +472,8 @@ print_df <- apa_df
 #' @param x Character.
 #' @keywords internal
 #'
-#' @examples
-#' papaja:::print_scientific("1.25e+04")
+# #' @examples
+# #' papaja:::print_scientific("1.25e+04")
 
 print_scientific <- function(x) {
   x <- gsub("e\\+00$", "", x)

R/apa_print_BFBayesFactor.R

@@ -92,13 +92,12 @@
 #'   \doi{10.1016/j.spl.2014.05.010}
 #' @family apa_print
 #' @importFrom stats formula terms setNames median
-#' @keywords internal
 #' @method apa_print BFBayesFactor
 #' @export
 #'
 #' @examples
 #' # ANOVA
-#' \dontrun{
+#' \donttest{
 #' data(sleep, package = "BayesFactor")
 #' bayesian_anova <- BayesFactor::anovaBF(
 #'   extra ~ group + ID
@@ -352,7 +351,6 @@ apa_print.BFBayesFactor <- function(
 
 
 #' @rdname apa_print.BFBayesFactor
-#' @keywords internal
 #' @method apa_print BFBayesFactorTop
 #' @export
 

R/apa_print_list.R

@@ -98,7 +98,7 @@ apa_print.list <- function(
   conf.int <- ellipsis_ci$conf.int
 
   if(length(x) == 1) apa_print(x[[1]]) else {
-    if(class(x[[1]]) != "lm") stop("Currently, only model comparisons for 'lm' objects are supported.")
+    if(!is(x[[1]], "lm")) stop("Currently, only model comparisons for 'lm' objects are supported.")
   }
 
   validate(conf.int, check_class = "numeric", check_length = 1, check_range = c(0, 1))

R/apa_print_merMod.R

@@ -23,7 +23,7 @@
 #' @evalRd apa_results_return_value()
 #'
 #' @examples
-#' \dontrun{
+#' \donttest{
 #'   # Fit a linear mixed model using the lme4 package
 #'   # or the lmerTest package (if dfs and p values are desired)
 #'   library(lmerTest)

R/apa_results_table.R

@@ -67,6 +67,8 @@ print.apa_results_table <- function(x, ...) {
 #'
 #' @inheritParams base::Extract
 #' @rdname extract_apa_results_table
+#' @return A (vector of) character values as extracted from an object of class
+#'   `apa_results_table`.
 #' @export
 
 `$.apa_results_table` <- function(x, name) {

R/apa_table.R

@@ -43,6 +43,8 @@
 #'   a `list` of matrices or data frames with a common structure. Can be either
 #'   `indent` or `table_spanner`. See details.
 #' @inheritDotParams knitr::kable
+#' @return A character vector of the table source code of class `knit_asis`, see
+#'   [knitr::asis_output()].
 #'
 #' @details
 #'   When using `apa_table`, the type of the output (LaTeX or Word) is
@@ -66,7 +68,7 @@
 #'   documents and will be printed to the document. To omit the printed options
 #'   set `placement = NULL`.
 #'
-#' @seealso \code{\link[knitr]{kable}}, \code{\link{apa_num}}
+#' @seealso [knitr::kable()], [apa_num()]
 #' @examples
 #'
 #' my_table <- t(apply(cars, 2, function(x) # Create data
@@ -672,10 +674,7 @@ apa_table.markdown <- function(
 #' @param format.args List. A named list of arguments to be passed to \code{\link{apa_num}} to format numeric values.
 #'
 #' @keywords internal
-#' @seealso \code{\link{apa_num}}
-#'
-#' @examples
-#' NULL
+#' @seealso [apa_num()]
 
 format_cells <- function(x, format.args = NULL) {
   format.args$x <- x
@@ -692,10 +691,7 @@ format_cells <- function(x, format.args = NULL) {
 #' @param added_stub_head Character. Used as stub head (name of first column).
 #' @param force Logical. Should row names be added even if they are the numbers 1:nrow(x)?
 #' @keywords internal
-#' @seealso \code{\link{apa_table}}
-#'
-#' @examples
-#' NULL
+#' @seealso [apa_table()]
 
 add_row_names <- function(x, added_stub_head, force = FALSE) {
   if(!is.null(rownames(x)) && (all(rownames(x) != 1:nrow(x))) || force) {
@@ -727,10 +723,7 @@ add_row_names <- function(x, added_stub_head, force = FALSE) {
 #'    indent. Names of list elements will be used as titles for indented sections.
 #' @param filler Character. Symbols used to indent stubs.
 #' @keywords internal
-#' @seealso \code{\link{apa_table}}
-#'
-#' @examples
-#' NULL
+#' @seealso [apa_table()]
 
 indent_stubs <- function(x, lines, filler = "\ \ \ ") {
   # x <- lapply(x, function(y) default_label(data.frame(y, check.names = FALSE, fix.empty.names = FALSE, stringsAsFactors = FALSE)))
@@ -768,10 +761,7 @@ indent_stubs <- function(x, lines, filler = "\ \ \ ") {
 #' @param n_cols Numeric. Number of columns of the table.
 #' @param add_group_midrules Logical.Determines whether group midrules are added.
 #' @keywords internal
-#' @seealso \code{\link{apa_table}}
-#'
-#' @examples
-#' NULL
+#' @seealso [apa_table()]
 
 add_col_spanners <- function(table_lines, col_spanners, n_cols, add_group_midrules = TRUE) {
 
@@ -863,10 +853,7 @@ remove_excess_table_spanner_columns <- function(x) {
 #'    element.
 #' @param added_stub_head Character. Vector of names for first unnamed columns. See \code{\link{apa_table}}.
 #' @keywords internal
-#' @seealso \code{\link{apa_table}}
-#'
-#' @examples
-#' NULL
+#' @seealso [apa_table()]
 
 merge_tables <- function(x, empty_cells, row_names, added_stub_head) {
 

R/arrange_anova.R

@@ -23,13 +23,13 @@
 #'
 #' @keywords internal
 #' @seealso [print_anova()], [print_model_comp()]
-#' @examples
-#'  \dontrun{
-#'    ## From Venables and Ripley (2002) p. 165.
-#'    npk_aov <- aov(yield ~ block + N * P * K, npk)
-#'    arrange_anova(summary(npk_aov))
-#'  }
-#'
+# #' @examples
+# #'  \dontrun{
+# #'    ## From Venables and Ripley (2002) p. 165.
+# #'    npk_aov <- aov(yield ~ block + N * P * K, npk)
+# #'    arrange_anova(summary(npk_aov))
+# #'  }
+
 
 arrange_anova <- function(x, ...) {
   UseMethod("arrange_anova")