docs: templates

DESCRIPTION

@@ -9,7 +9,7 @@ Description: Create beautiful and customizable tables to summarize several
     and it can produce tables in HTML, LaTeX, Word, Markdown, PDF, PowerPoint,
     Excel, RTF, JPG, or PNG. Tables can easily be embedded in 'Rmarkdown' or 
     'knitr' dynamic documents.
-Version: 0.9.1
+Version: 0.9.1.9000
 Authors@R: c(person("Vincent", "Arel-Bundock", 
                    email = "vincent.arel-bundock@umontreal.ca", 
                    role = c("aut", "cre"),

R/datasummary.R

@@ -26,6 +26,7 @@
 #' `datasummary` in order to affect the behavior of other functions behind
 #' the scenes, for instance:
 #' * `kableExtra::kbl(escape=FALSE)` to avoid escaping math characters in `kableExtra` tables.
+#' @template options
 #' @examples
 #'
 #' \dontrun{

R/datasummary_balance.R

@@ -14,6 +14,7 @@
 #' @param dinm_statistic string: "std.error" or "p.value"
 #' @inheritParams modelsummary
 #' @inheritParams datasummary
+#' @template options
 #' @export
 #' @examples
 #' \dontrun{

R/datasummary_correlation.R

@@ -15,6 +15,7 @@
 #'     `datasummary_correlation_format` can often be useful for formatting the
 #'     output of custom correlation functions.
 #' }
+#' @template options
 #' @param ... other parameters are passed through to the table-making
 #'     packages.
 #' @export

R/datasummary_crosstab.R

@@ -30,6 +30,7 @@
 #'   Finally, the `formula` and `statistic` formulas are combined into a single
 #'   formula which is fed directly to the `datasummary` function to produce the
 #'   table.
+#' @template options
 #' @examples
 #' \dontrun{
 #'   # crosstab of two variables, showing counts, row percentages, and row/column totals

R/datasummary_skim.R

@@ -14,6 +14,7 @@
 #' }
 #' @param type of variables to summarize: "numeric" or "categorical" (character)
 #'
+#' @template options
 #' @examples
 #'
 #' \dontrun{

R/modelsummary.R

@@ -117,181 +117,9 @@ globalVariables(c('.', 'term', 'part', 'estimate', 'conf.high', 'conf.low',
 #' @importFrom generics glance tidy
 #' @details
 #'
-#' `options`
-#'
-#' `modelsummary` supports 4 table-making packages: `kableExtra`, `gt`,
-#' `flextable`, and `huxtable`. Some of these packages have overlapping
-#' functionalities. For example, 3 of those packages can export to LaTeX. To
-#' change the default backend used for a specific file format, you can use
-#' the `options` function:
-#'
-#' `options(modelsummary_html = 'kableExtra')`
-#' `options(modelsummary_latex = 'gt')`
-#' `options(modelsummary_word = 'huxtable')`
-#' `options(modelsummary_png = 'gt')`
-#'
-#' `modelsummary` can use two sets of packages to extract information from
-#' statistical models: `broom` and the `easystats` family (`performance` and
-#' `parameters`). By default, it uses `broom` first and `easystats` as a
-#' fallback if `broom` fails. You can change the order of priorities
-#' or include goodness-of-fit extracted by *both* packages by setting:
-#'
-#' `options(modelsummary_get = "broom")`
-#' `options(modelsummary_get = "easystats")`
-#' `options(modelsummary_get = "all")`
-#'
-#' By default, LaTeX tables enclose all numeric entries in the `\num{}` command
-#' from the siunitx package. To prevent this behavior, or to enclose numbers
-#' in dollar signs (for LaTeX math mode), users can call:
-#'
-#' `options(modelsummary_format_numeric_latex = "plain")`
-#' `options(modelsummary_format_numeric_latex = "mathmode")`
-#'
-#' A similar option can be used to display numerical entries using MathJax in
-#' HTML tables:
-#'
-#' `options(modelsummary_format_numeric_html = "mathjax")`
-#'
-#' `output` argument:
-#'
-#' The `modelsummary_list` output type is a lightweight representation of the
-#' model results. The `modelsummary` function can export to this format by
-#' setting the `output` argument, and it can accept objects of this format
-#' as input models to create a table. This can be useful to save raw
-#' results, in order to print a table later, without having to save and
-#' extract from the entire model object. Note that the confidence intervals
-#' are only stored in a `modelsummary_list` if explicitly requested:
-#'
-#' `backup <- modelsummary(models, output = "modelsummary_list"`
-#' `                       statistic = "conf.int")`
-#' `modelsummary(backup)`
-#'
-#' When a file name with a valid extension is supplied to the `output` argument,
-#' the table is written immediately to file. If you want to customize your table
-#' by post-processing it with an external package, you need to choose a
-#' different output format and saving mechanism. Unfortunately, the approach
-#' differs from package to package:
-#' * `gt`: set `output="gt"`, post-process your table, and use the `gt::gtsave` function.
-#' * `kableExtra`: set `output` to your destination format (e.g., "latex", "html", "markdown"), post-process your table, and use `kableExtra::save_kable` function.
-#'
-#'
-#' `vcov` argument:
-#'
-#' To use a string such as "robust" or "HC0", your model must be supported
-#' by the `sandwich` package. This includes objects such as: lm, glm,
-#' survreg, coxph, mlogit, polr, hurdle, zeroinfl, and more.
-#'
-#' NULL, "classical", "iid", and "constant" are aliases which do not modify
-#' uncertainty estimates and simply report the default standard errors stored
-#' in the model object.
-#'
-#' One-sided formulas such as `~clusterid` are passed to the `sandwich::vcovCL`
-#' function.
-#'
-#' Matrices and functions producing variance-covariance matrices are first
-#' passed to `lmtest`. If this does not work, `modelsummary` attempts to take
-#' the square root of the diagonal to adjust "std.error", but the other
-#' uncertainty estimates are not be adjusted.
-#'
-#' Numeric vectors are formatted according to `fmt` and placed in brackets.
-#' Character vectors printed as given, without parentheses.
-#'
-#' If your model type is supported by the `lmtest` package, the
-#' `vcov` argument will try to use that package to adjust all the
-#' uncertainty estimates, including "std.error", "statistic", "p.value", and
-#' "conf.int". If your model is not supported by `lmtest`, only the "std.error"
-#' will be adjusted by, for example, taking the square root of the matrix's
-#' diagonal.
-#' @examples
-#' \dontrun{
-#'
-#' # The `modelsummary` website includes \emph{many} examples and tutorials:
-#' # https://vincentarelbundock.github.io/modelsummary
-#'
-#' library(modelsummary)
-#'
-#' # load data and estimate models
-#' data(trees)
-#' models <- list()
-#' models[['Bivariate']] <- lm(Girth ~ Height, data = trees)
-#' models[['Multivariate']] <- lm(Girth ~ Height + Volume, data = trees)
-#'
-#' # simple table
-#' modelsummary(models)
-#'
-#' # statistic
-#' modelsummary(models, statistic = NULL)
-#' modelsummary(models, statistic = 'p.value')
-#' modelsummary(models, statistic = 'statistic')
-#' modelsummary(models, statistic = 'conf.int', conf_level = 0.99)
-#' modelsummary(models, statistic = c("t = {statistic}",
-#'                                    "se = {std.error}",
-#'                                    "conf.int"))
-#'
-#' # estimate
-#' modelsummary(models,
-#'   statistic = NULL,
-#'   estimate = "{estimate} [{conf.low}, {conf.high}]")
-#' modelsummary(models,
-#'   estimate = c("{estimate}{stars}",
-#'                "{estimate} ({std.error})"))
-#'
-#' # vcov
-#' modelsummary(models, vcov = "robust")
-#' modelsummary(models, vcov = list("classical", "stata"))
-#' modelsummary(models, vcov = sandwich::vcovHC)
-#' modelsummary(models,
-#'   vcov = list(stats::vcov, sandwich::vcovHC))
-#' modelsummary(models,
-#'   vcov = list(c("(Intercept)"="", "Height"="!"),
-#'               c("(Intercept)"="", "Height"="!", "Volume"="!!")))
-#'
-#' # vcov with custom names
-#' modelsummary(
-#'   models,
-#'   vcov = list("Stata Corp" = "stata",
-#'               "Newey Lewis & the News" = "NeweyWest"))
-#'
-#' # coef_rename
-#' modelsummary(models, coef_map = c('Volume' = 'Large', 'Height' = 'Tall'))
-#'
-#' # coef_map
-#' modelsummary(models, coef_map = c('Volume' = 'Large', 'Height' = 'Tall'))
-#' modelsummary(models, coef_map = c('Volume', 'Height'))
-#'
-#' # title
-#' modelsummary(models, title = 'This is the title')
-#'
-#' # title with LaTeX label (for numbering and referencing)
-#' modelsummary(models, title = 'This is the title \\label{tab:description}')
-#'
-#' # add_rows
-#' rows <- tibble::tribble(~term, ~Bivariate, ~Multivariate,
-#'   'Empty row', '-', '-',
-#'   'Another empty row', '?', '?')
-#' attr(rows, 'position') <- c(1, 3)
-#' modelsummary(models, add_rows = rows)
-#'
-#' # notes
-#' modelsummary(models, notes = list('A first note', 'A second note'))
-#'
-#' # gof_map: data.frame
-#' gm <- modelsummary::gof_map
-#' gof_custom$omit[gof_custom$raw == 'deviance'] <- FALSE
-#' gof_custom$fmt[gof_custom$raw == 'r.squared'] <- "%.5f"
-#' modelsummary(models, gof_map = gof_custom)
-#'
-#' # gof_map: list of lists
-#' f1 <- function(x) format(round(x, 3), big.mark=",")
-#' f2 <- function(x) format(round(x, 0), big.mark=",")
-#' gm <- list(
-#'   list("raw" = "nobs", "clean" = "N", "fmt" = f2),
-#'   list("raw" = "AIC", "clean" = "aic", "fmt" = f1))
-#' modelsummary(models,
-#'   fmt = f1,
-#'   gof_map = gm)
-#'
-#' }
+#' @template modelsummary_details
+#' @template options
+#' @template modelsummary_examples
 #'
 #' @export
 modelsummary <- function(

man-roxygen/modelsummary_details.R

@@ -0,0 +1,51 @@
+#' 
+#' ## `output`
+#'
+#' The `modelsummary_list` output type is a lightweight representation of the
+#' model results. The `modelsummary` function can export to this format by
+#' setting the `output` argument, and it can accept objects of this format
+#' as input models to create a table. This can be useful to save raw
+#' results, in order to print a table later, without having to save and
+#' extract from the entire model object. Note that the confidence intervals
+#' are only stored in a `modelsummary_list` if explicitly requested:
+#'
+#' `backup <- modelsummary(models, output = "modelsummary_list"`
+#' `                       statistic = "conf.int")`
+#' `modelsummary(backup)`
+#'
+#' When a file name with a valid extension is supplied to the `output` argument,
+#' the table is written immediately to file. If you want to customize your table
+#' by post-processing it with an external package, you need to choose a
+#' different output format and saving mechanism. Unfortunately, the approach
+#' differs from package to package:
+#'
+#' * `gt`: set `output="gt"`, post-process your table, and use the `gt::gtsave` function.
+#' * `kableExtra`: set `output` to your destination format (e.g., "latex", "html", "markdown"), post-process your table, and use `kableExtra::save_kable` function.
+#'
+#' ## `vcov`
+#'
+#' To use a string such as "robust" or "HC0", your model must be supported
+#' by the `sandwich` package. This includes objects such as: lm, glm,
+#' survreg, coxph, mlogit, polr, hurdle, zeroinfl, and more.
+#'
+#' NULL, "classical", "iid", and "constant" are aliases which do not modify
+#' uncertainty estimates and simply report the default standard errors stored
+#' in the model object.
+#'
+#' One-sided formulas such as `~clusterid` are passed to the `sandwich::vcovCL`
+#' function.
+#'
+#' Matrices and functions producing variance-covariance matrices are first
+#' passed to `lmtest`. If this does not work, `modelsummary` attempts to take
+#' the square root of the diagonal to adjust "std.error", but the other
+#' uncertainty estimates are not be adjusted.
+#'
+#' Numeric vectors are formatted according to `fmt` and placed in brackets.
+#' Character vectors printed as given, without parentheses.
+#'
+#' If your model type is supported by the `lmtest` package, the
+#' `vcov` argument will try to use that package to adjust all the
+#' uncertainty estimates, including "std.error", "statistic", "p.value", and
+#' "conf.int". If your model is not supported by `lmtest`, only the "std.error"
+#' will be adjusted by, for example, taking the square root of the matrix's
+#' diagonal.

man-roxygen/modelsummary_examples.R

@@ -0,0 +1,92 @@
+#'
+#' @examples
+#' \dontrun{
+#'
+#' # The `modelsummary` website includes \emph{many} examples and tutorials:
+#' # https://vincentarelbundock.github.io/modelsummary
+#'
+#' library(modelsummary)
+#'
+#' # load data and estimate models
+#' data(trees)
+#' models <- list()
+#' models[['Bivariate']] <- lm(Girth ~ Height, data = trees)
+#' models[['Multivariate']] <- lm(Girth ~ Height + Volume, data = trees)
+#'
+#' # simple table
+#' modelsummary(models)
+#'
+#' # statistic
+#' modelsummary(models, statistic = NULL)
+#' modelsummary(models, statistic = 'p.value')
+#' modelsummary(models, statistic = 'statistic')
+#' modelsummary(models, statistic = 'conf.int', conf_level = 0.99)
+#' modelsummary(models, statistic = c("t = {statistic}",
+#'                                    "se = {std.error}",
+#'                                    "conf.int"))
+#'
+#' # estimate
+#' modelsummary(models,
+#'   statistic = NULL,
+#'   estimate = "{estimate} [{conf.low}, {conf.high}]")
+#' modelsummary(models,
+#'   estimate = c("{estimate}{stars}",
+#'                "{estimate} ({std.error})"))
+#'
+#' # vcov
+#' modelsummary(models, vcov = "robust")
+#' modelsummary(models, vcov = list("classical", "stata"))
+#' modelsummary(models, vcov = sandwich::vcovHC)
+#' modelsummary(models,
+#'   vcov = list(stats::vcov, sandwich::vcovHC))
+#' modelsummary(models,
+#'   vcov = list(c("(Intercept)"="", "Height"="!"),
+#'               c("(Intercept)"="", "Height"="!", "Volume"="!!")))
+#'
+#' # vcov with custom names
+#' modelsummary(
+#'   models,
+#'   vcov = list("Stata Corp" = "stata",
+#'               "Newey Lewis & the News" = "NeweyWest"))
+#'
+#' # coef_rename
+#' modelsummary(models, coef_map = c('Volume' = 'Large', 'Height' = 'Tall'))
+#'
+#' # coef_map
+#' modelsummary(models, coef_map = c('Volume' = 'Large', 'Height' = 'Tall'))
+#' modelsummary(models, coef_map = c('Volume', 'Height'))
+#'
+#' # title
+#' modelsummary(models, title = 'This is the title')
+#'
+#' # title with LaTeX label (for numbering and referencing)
+#' modelsummary(models, title = 'This is the title \\label{tab:description}')
+#'
+#' # add_rows
+#' rows <- tibble::tribble(~term, ~Bivariate, ~Multivariate,
+#'   'Empty row', '-', '-',
+#'   'Another empty row', '?', '?')
+#' attr(rows, 'position') <- c(1, 3)
+#' modelsummary(models, add_rows = rows)
+#'
+#' # notes
+#' modelsummary(models, notes = list('A first note', 'A second note'))
+#'
+#' # gof_map: data.frame
+#' gm <- modelsummary::gof_map
+#' gof_custom$omit[gof_custom$raw == 'deviance'] <- FALSE
+#' gof_custom$fmt[gof_custom$raw == 'r.squared'] <- "%.5f"
+#' modelsummary(models, gof_map = gof_custom)
+#'
+#' # gof_map: list of lists
+#' f1 <- function(x) format(round(x, 3), big.mark=",")
+#' f2 <- function(x) format(round(x, 0), big.mark=",")
+#' gm <- list(
+#'   list("raw" = "nobs", "clean" = "N", "fmt" = f2),
+#'   list("raw" = "AIC", "clean" = "aic", "fmt" = f1))
+#' modelsummary(models,
+#'   fmt = f1,
+#'   gof_map = gm)
+#'
+#' }
+#'