From 9a944e0b72cfc386d07998d3a4ac074206093fb6 Mon Sep 17 00:00:00 2001 From: Daniel Date: Mon, 10 Jun 2024 21:33:35 +0200 Subject: [PATCH 1/8] Formatting issue with print_md() applied to compare_parameters() Fixes https://github.com/easystats/insight/issues/887 --- R/print_md.R | 1 + man/display.parameters_model.Rd | 18 ++++++++++++++++++ 2 files changed, 19 insertions(+) diff --git a/R/print_md.R b/R/print_md.R index 5a4990f54..61c5b8655 100644 --- a/R/print_md.R +++ b/R/print_md.R @@ -123,6 +123,7 @@ print_md.parameters_simulate <- print_md.parameters_model # compare parameters ------------------------- +#' @rdname display.parameters_model #' @export print_md.compare_parameters <- function(x, digits = 2, diff --git a/man/display.parameters_model.Rd b/man/display.parameters_model.Rd index f351e0c63..33b2e7532 100644 --- a/man/display.parameters_model.Rd +++ b/man/display.parameters_model.Rd @@ -10,6 +10,7 @@ \alias{format.parameters_model} \alias{print_html.parameters_model} \alias{print_md.parameters_model} +\alias{print_md.compare_parameters} \alias{print_table} \title{Print tables in different output formats} \usage{ @@ -129,6 +130,23 @@ ... ) +\method{print_md}{compare_parameters}( + x, + digits = 2, + ci_digits = digits, + p_digits = 3, + caption = NULL, + subtitle = NULL, + footer = NULL, + select = NULL, + split_components = TRUE, + ci_brackets = c("(", ")"), + zap_small = FALSE, + groups = NULL, + engine = "tt", + ... +) + print_table(x, digits = 2, p_digits = 3, theme = "default", ...) } \arguments{ From e7339a447441f6c9cf6b14db2405da9d96b8b2bd Mon Sep 17 00:00:00 2001 From: Daniel Date: Mon, 10 Jun 2024 21:45:24 +0200 Subject: [PATCH 2/8] docs --- R/format.R | 1 + R/print.compare_parameters.R | 25 ++++ R/print_html.R | 1 + R/print_md.R | 2 +- man/display.parameters_model.Rd | 18 --- man/print.compare_parameters.Rd | 234 ++++++++++++++++++++++++++++++++ 6 files changed, 262 insertions(+), 19 deletions(-) create mode 100644 man/print.compare_parameters.Rd diff --git a/R/format.R b/R/format.R index 790489abf..9e589b9f4 100644 --- a/R/format.R +++ b/R/format.R @@ -240,6 +240,7 @@ format.parameters_brms_meta <- format.parameters_model # Compare parameters ---------------------- +#' @rdname print.compare_parameters #' @inheritParams print.parameters_model #' @export format.compare_parameters <- function(x, diff --git a/R/print.compare_parameters.R b/R/print.compare_parameters.R index 8845d0701..40dd6d556 100644 --- a/R/print.compare_parameters.R +++ b/R/print.compare_parameters.R @@ -1,3 +1,28 @@ +#' @title Print comparisons of model parameters +#' @name print.compare_parameters +#' +#' @description A `print()`-method for objects from [`compare_parameters()`]. +#' +#' @param x,object An object returned by [`compare_parameters()`]. +#' @inheritParams print.parameters_model +#' @inheritSection print.parameters_model Global Options to Customize Messages and Tables when Printing +#' +#' @return Invisibly returns the original input object. +#' +#' @examples +#' \donttest{ +#' data(iris) +#' lm1 <- lm(Sepal.Length ~ Species, data = iris) +#' lm2 <- lm(Sepal.Length ~ Species + Petal.Length, data = iris) +#' +#' # custom style +#' result <- compare_parameters(lm1, lm2, select = "{estimate}{stars} ({se})") +#' print(result) +#' +#' # custom style, in HTML +#' result <- compare_parameters(lm1, lm2, select = "{estimate}
({se})|{p}") +#' print_html(result) +#' } #' @export print.compare_parameters <- function(x, split_components = TRUE, diff --git a/R/print_html.R b/R/print_html.R index d71aa194b..d67fd51b5 100644 --- a/R/print_html.R +++ b/R/print_html.R @@ -138,6 +138,7 @@ print_html.parameters_simulate <- print_html.parameters_model #' @export print_html.parameters_sem <- print_html.parameters_model +#' @rdname print.compare_parameters #' @export print_html.compare_parameters <- function(x, caption = NULL, diff --git a/R/print_md.R b/R/print_md.R index 61c5b8655..0fbe401c6 100644 --- a/R/print_md.R +++ b/R/print_md.R @@ -123,7 +123,7 @@ print_md.parameters_simulate <- print_md.parameters_model # compare parameters ------------------------- -#' @rdname display.parameters_model +#' @rdname print.compare_parameters #' @export print_md.compare_parameters <- function(x, digits = 2, diff --git a/man/display.parameters_model.Rd b/man/display.parameters_model.Rd index 33b2e7532..f351e0c63 100644 --- a/man/display.parameters_model.Rd +++ b/man/display.parameters_model.Rd @@ -10,7 +10,6 @@ \alias{format.parameters_model} \alias{print_html.parameters_model} \alias{print_md.parameters_model} -\alias{print_md.compare_parameters} \alias{print_table} \title{Print tables in different output formats} \usage{ @@ -130,23 +129,6 @@ ... ) -\method{print_md}{compare_parameters}( - x, - digits = 2, - ci_digits = digits, - p_digits = 3, - caption = NULL, - subtitle = NULL, - footer = NULL, - select = NULL, - split_components = TRUE, - ci_brackets = c("(", ")"), - zap_small = FALSE, - groups = NULL, - engine = "tt", - ... -) - print_table(x, digits = 2, p_digits = 3, theme = "default", ...) } \arguments{ diff --git a/man/print.compare_parameters.Rd b/man/print.compare_parameters.Rd new file mode 100644 index 000000000..05211d052 --- /dev/null +++ b/man/print.compare_parameters.Rd @@ -0,0 +1,234 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/format.R, R/print.compare_parameters.R, +% R/print_html.R, R/print_md.R +\name{format.compare_parameters} +\alias{format.compare_parameters} +\alias{print.compare_parameters} +\alias{print_html.compare_parameters} +\alias{print_md.compare_parameters} +\title{Print comparisons of model parameters} +\usage{ +\method{format}{compare_parameters}( + x, + split_components = TRUE, + select = NULL, + digits = 2, + ci_digits = digits, + p_digits = 3, + ci_width = NULL, + ci_brackets = NULL, + zap_small = FALSE, + format = NULL, + groups = NULL, + engine = NULL, + ... +) + +\method{print}{compare_parameters}( + x, + split_components = TRUE, + caption = NULL, + subtitle = NULL, + footer = NULL, + digits = 2, + ci_digits = digits, + p_digits = 3, + zap_small = FALSE, + groups = NULL, + column_width = NULL, + ci_brackets = c("(", ")"), + select = NULL, + ... +) + +\method{print_html}{compare_parameters}( + x, + caption = NULL, + subtitle = NULL, + footer = NULL, + digits = 2, + ci_digits = digits, + p_digits = 3, + zap_small = FALSE, + groups = NULL, + select = NULL, + ci_brackets = c("(", ")"), + font_size = "100\%", + line_padding = 4, + column_labels = NULL, + engine = "gt", + ... +) + +\method{print_md}{compare_parameters}( + x, + digits = 2, + ci_digits = digits, + p_digits = 3, + caption = NULL, + subtitle = NULL, + footer = NULL, + select = NULL, + split_components = TRUE, + ci_brackets = c("(", ")"), + zap_small = FALSE, + groups = NULL, + engine = "tt", + ... +) +} +\arguments{ +\item{x, object}{An object returned by \code{\link[=compare_parameters]{compare_parameters()}}.} + +\item{split_components}{Logical, if \code{TRUE} (default), For models with +multiple components (zero-inflation, smooth terms, ...), each component is +printed in a separate table. If \code{FALSE}, model parameters are printed +in a single table and a \code{Component} column is added to the output.} + +\item{select}{Determines which columns and and which layout columns are +printed. There are three options for this argument: +\enumerate{ +\item Selecting columns by name or index +\cr +\code{select} can be a character vector (or numeric index) of column names that +should be printed. There are two pre-defined options for selecting columns: +\code{select = "minimal"} prints coefficients, confidence intervals and p-values, +while \code{select = "short"} prints coefficients, standard errors and p-values. +\item A string expression with layout pattern +\cr +\code{select} is a string with "tokens" enclosed in braces. These tokens will +be replaced by their associated columns, where the selected columns will +be collapsed into one column. However, it is possible to create multiple +columns as well. Following tokens are replaced by the related coefficients +or statistics: \code{{estimate}}, \code{{se}}, \code{{ci}} (or \code{{ci_low}} and \code{{ci_high}}), +\code{{p}} and \code{{stars}}. The token \code{{ci}} will be replaced by \verb{\{ci_low\}, \{ci_high\}}. +Furthermore, a \code{|} separates values into new cells/columns. If +\code{format = "html"}, a \verb{
} inserts a line break inside a cell. See +'Examples'. +\item A string indicating a pre-defined layout +\cr +\code{select} can be one of the following string values, to create one of the +following pre-defined column layouts: +\itemize{ +\item \code{"ci"}: Estimates and confidence intervals, no asterisks for p-values. +This is equivalent to \code{select = "{estimate} ({ci})"}. +\item \code{"se"}: Estimates and standard errors, no asterisks for p-values. This is +equivalent to \code{select = "{estimate} ({se})"}. +\item \code{"ci_p"}: Estimates, confidence intervals and asterisks for p-values. This +is equivalent to \code{select = "{estimate}{stars} ({ci})"}. +\item \code{"se_p"}: Estimates, standard errors and asterisks for p-values. This is +equivalent to \code{select = "{estimate}{stars} ({se})"}.. +\item \code{"ci_p2"}: Estimates, confidence intervals and numeric p-values, in two +columns. This is equivalent to \code{select = "{estimate} ({ci})|{p}"}. +\item \code{"se_p2"}: Estimate, standard errors and numeric p-values, in two columns. +This is equivalent to \code{select = "{estimate} ({se})|{p}"}. +} +} + +For \code{model_parameters()}, glue-like syntax is still experimental in the +case of more complex models (like mixed models) and may not return expected +results.} + +\item{digits, ci_digits, p_digits}{Number of digits for rounding or +significant figures. May also be \code{"signif"} to return significant +figures or \code{"scientific"} to return scientific notation. Control the +number of digits by adding the value as suffix, e.g. \code{digits = "scientific4"} +to have scientific notation with 4 decimal places, or \code{digits = "signif5"} +for 5 significant figures (see also \code{\link[=signif]{signif()}}).} + +\item{ci_brackets}{Logical, if \code{TRUE} (default), CI-values are +encompassed in square brackets (else in parentheses).} + +\item{zap_small}{Logical, if \code{TRUE}, small values are rounded after +\code{digits} decimal places. If \code{FALSE}, values with more decimal +places than \code{digits} are printed in scientific notation.} + +\item{groups}{Named list, can be used to group parameters in the printed output. +List elements may either be character vectors that match the name of those +parameters that belong to one group, or list elements can be row numbers +of those parameter rows that should belong to one group. The names of the +list elements will be used as group names, which will be inserted as "header +row". A possible use case might be to emphasize focal predictors and control +variables, see 'Examples'. Parameters will be re-ordered according to the +order used in \code{groups}, while all non-matching parameters will be added +to the end.} + +\item{...}{Arguments passed to or from other methods.} + +\item{caption}{Table caption as string. If \code{NULL}, depending on the model, +either a default caption or no table caption is printed. Use \code{caption = ""} +to suppress the table caption.} + +\item{footer}{Can either be \code{FALSE} or an empty string (i.e. \code{""}) to +suppress the footer, \code{NULL} to print the default footer, or a string. The +latter will combine the string value with the default footer.} + +\item{column_width}{Width of table columns. Can be either \code{NULL}, a named +numeric vector, or \code{"fixed"}. If \code{NULL}, the width for each table column is +adjusted to the minimum required width. If a named numeric vector, value +names are matched against column names, and for each match, the specified +width is used. If \code{"fixed"}, and table is split into multiple components, +columns across all table components are adjusted to have the same width.} +} +\value{ +Invisibly returns the original input object. +} +\description{ +A \code{print()}-method for objects from \code{\link[=compare_parameters]{compare_parameters()}}. +} +\section{Global Options to Customize Messages and Tables when Printing}{ + +The \code{verbose} argument can be used to display or silence messages and +warnings for the different functions in the \strong{parameters} package. However, +some messages providing additional information can be displayed or suppressed +using \code{options()}: +\itemize{ +\item \code{parameters_summary}: \code{options(parameters_summary = TRUE)} will override the +\code{summary} argument in \code{model_parameters()} and always show the model summary +for non-mixed models. +\item \code{parameters_mixed_summary}: \code{options(parameters_mixed_summary = TRUE)} will +override the \code{summary} argument in \code{model_parameters()} for mixed models, and +will then always show the model summary. +\item \code{parameters_cimethod}: \code{options(parameters_cimethod = TRUE)} will show the +additional information about the approximation method used to calculate +confidence intervals and p-values. Set to \code{FALSE} to hide this message when +printing \code{model_parameters()} objects. +\item \code{parameters_exponentiate}: \code{options(parameters_exponentiate = TRUE)} will +show the additional information on how to interpret coefficients of models +with log-transformed response variables or with log-/logit-links when the +\code{exponentiate} argument in \code{model_parameters()} is not \code{TRUE}. Set this option +to \code{FALSE} to hide this message when printing \code{model_parameters()} objects. +} + +There are further options that can be used to modify the default behaviour +for printed outputs: +\itemize{ +\item \code{parameters_labels}: \code{options(parameters_labels = TRUE)} will use variable +and value labels for pretty names, if data is labelled. If no labels +available, default pretty names are used. +\item \code{parameters_interaction}: \verb{options(parameters_interaction = )} +will replace the interaction mark (by default, \code{*}) with the related character. +\item \code{parameters_select}: \verb{options(parameters_select = )} will set the +default for the \code{select} argument. See argument's documentation for available +options. +\item \code{easystats_html_engine}: \code{options(easystats_html_engine = "gt")} will set +the default HTML engine for tables to \code{gt}, i.e. the \emph{gt} package is used to +create HTML tables. If set to \code{tt}, the \emph{tinytable} package is used. +} +} + +\examples{ +\donttest{ +data(iris) +lm1 <- lm(Sepal.Length ~ Species, data = iris) +lm2 <- lm(Sepal.Length ~ Species + Petal.Length, data = iris) + +# custom style +result <- compare_parameters(lm1, lm2, select = "{estimate}{stars} ({se})") +print(result) + +# custom style, in HTML +result <- compare_parameters(lm1, lm2, select = "{estimate}
({se})|{p}") +print_html(result) +} +} From 7b961121682189501df845db63e6f2942e4de022 Mon Sep 17 00:00:00 2001 From: Daniel Date: Mon, 10 Jun 2024 21:51:37 +0200 Subject: [PATCH 3/8] docs --- R/display.R | 10 ++--- R/format.R | 2 +- R/print.parameters_model.R | 1 + man/display.parameters_model.Rd | 35 +++------------ man/print.compare_parameters.Rd | 8 ++++ man/print.parameters_model.Rd | 76 ++++++++++++++++++++++----------- 6 files changed, 70 insertions(+), 62 deletions(-) diff --git a/R/display.R b/R/display.R index 334854250..8b4238891 100644 --- a/R/display.R +++ b/R/display.R @@ -6,11 +6,9 @@ #' is a alias for `display(format = "html")`. `print_table()` is for specific #' use cases only, and currently only works for `compare_parameters()` objects. #' -#' @param x An object returned by [`model_parameters()`][model_parameters]. -#' @param object An object returned by [`model_parameters()`][model_parameters], -#' [`simulate_parameters()`][simulate_parameters], -#' [`equivalence_test()`][equivalence_test.lm] or -#' [`principal_components()`][principal_components]. +#' @param x An object returned by [`model_parameters()`]. +#' @param object An object returned by [`model_parameters()`],[`simulate_parameters()`], +#' [`equivalence_test()`] or [`principal_components()`]. #' @param format String, indicating the output format. Can be `"markdown"` #' or `"html"`. #' @param align Only applies to HTML tables. May be one of `"left"`, @@ -56,7 +54,7 @@ #' effects in the table. See 'Examples'. An alternative is to set `engine = "tt"` #' in `print_html()` to use the _tinytable_ package for creating HTML tables. #' -#' @seealso [print.parameters_model()] +#' @seealso [print.parameters_model()] and [print.compare_parameters()] #' #' @examplesIf require("gt", quietly = TRUE) #' model <- lm(mpg ~ wt + cyl, data = mtcars) diff --git a/R/format.R b/R/format.R index 9e589b9f4..5678eeb0c 100644 --- a/R/format.R +++ b/R/format.R @@ -1,7 +1,7 @@ # usual models --------------------------------- #' @inheritParams print.parameters_model -#' @rdname display.parameters_model +#' @rdname print.parameters_model #' @export format.parameters_model <- function(x, pretty_names = TRUE, diff --git a/R/print.parameters_model.R b/R/print.parameters_model.R index 422791258..cfc58660b 100644 --- a/R/print.parameters_model.R +++ b/R/print.parameters_model.R @@ -94,6 +94,7 @@ #' so this is just for completeness. #' @inheritParams insight::format_table #' @inheritParams compare_parameters +#' @inheritParams display.parameters_model #' #' @inheritSection format_parameters Interpretation of Interaction Terms #' @inheritSection model_parameters Labeling the Degrees of Freedom diff --git a/man/display.parameters_model.Rd b/man/display.parameters_model.Rd index f351e0c63..f35729439 100644 --- a/man/display.parameters_model.Rd +++ b/man/display.parameters_model.Rd @@ -1,13 +1,12 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/display.R, R/format.R, R/print_html.R, -% R/print_md.R, R/print_table.R +% Please edit documentation in R/display.R, R/print_html.R, R/print_md.R, +% R/print_table.R \name{display.parameters_model} \alias{display.parameters_model} \alias{display.parameters_sem} \alias{display.parameters_efa_summary} \alias{display.parameters_efa} \alias{display.equivalence_test_lm} -\alias{format.parameters_model} \alias{print_html.parameters_model} \alias{print_md.parameters_model} \alias{print_table} @@ -63,23 +62,6 @@ \method{display}{equivalence_test_lm}(object, format = "markdown", digits = 2, ...) -\method{format}{parameters_model}( - x, - pretty_names = TRUE, - split_components = TRUE, - select = NULL, - digits = 2, - ci_digits = digits, - p_digits = 3, - ci_width = NULL, - ci_brackets = NULL, - zap_small = FALSE, - format = NULL, - groups = NULL, - include_reference = FALSE, - ... -) - \method{print_html}{parameters_model}( x, pretty_names = TRUE, @@ -132,10 +114,8 @@ print_table(x, digits = 2, p_digits = 3, theme = "default", ...) } \arguments{ -\item{object}{An object returned by \code{\link[=model_parameters]{model_parameters()}}, -\code{\link[=simulate_parameters]{simulate_parameters()}}, -\code{\link[=equivalence_test.lm]{equivalence_test()}} or -\code{\link[=principal_components]{principal_components()}}.} +\item{object}{An object returned by \code{\link[=model_parameters]{model_parameters()}},\code{\link[=simulate_parameters]{simulate_parameters()}}, +\code{\link[=equivalence_test]{equivalence_test()}} or \code{\link[=principal_components]{principal_components()}}.} \item{format}{String, indicating the output format. Can be \code{"markdown"} or \code{"html"}.} @@ -262,11 +242,6 @@ loadings data. Usually, the question related to the item.} \item{x}{An object returned by \code{\link[=model_parameters]{model_parameters()}}.} -\item{ci_width}{Minimum width of the returned string for confidence -intervals. If not \code{NULL} and width is larger than the string's length, -leading whitespaces are added to the string. If \code{width="auto"}, width -will be set to the length of the longest string.} - \item{groups}{Named list, can be used to group parameters in the printed output. List elements may either be character vectors that match the name of those parameters that belong to one group, or list elements can be row numbers @@ -356,5 +331,5 @@ print_table(out) \dontshow{\}) # examplesIf} } \seealso{ -\code{\link[=print.parameters_model]{print.parameters_model()}} +\code{\link[=print.parameters_model]{print.parameters_model()}} and \code{\link[=print.compare_parameters]{print.compare_parameters()}} } diff --git a/man/print.compare_parameters.Rd b/man/print.compare_parameters.Rd index 05211d052..e05ba36ee 100644 --- a/man/print.compare_parameters.Rd +++ b/man/print.compare_parameters.Rd @@ -136,6 +136,11 @@ number of digits by adding the value as suffix, e.g. \code{digits = "scientific4 to have scientific notation with 4 decimal places, or \code{digits = "signif5"} for 5 significant figures (see also \code{\link[=signif]{signif()}}).} +\item{ci_width}{Minimum width of the returned string for confidence +intervals. If not \code{NULL} and width is larger than the string's length, +leading whitespaces are added to the string. If \code{width="auto"}, width +will be set to the length of the longest string.} + \item{ci_brackets}{Logical, if \code{TRUE} (default), CI-values are encompassed in square brackets (else in parentheses).} @@ -143,6 +148,9 @@ encompassed in square brackets (else in parentheses).} \code{digits} decimal places. If \code{FALSE}, values with more decimal places than \code{digits} are printed in scientific notation.} +\item{format}{String, indicating the output format. Can be \code{"markdown"} +or \code{"html"}.} + \item{groups}{Named list, can be used to group parameters in the printed output. List elements may either be character vectors that match the name of those parameters that belong to one group, or list elements can be row numbers diff --git a/man/print.parameters_model.Rd b/man/print.parameters_model.Rd index 18bec59c7..b12be286a 100644 --- a/man/print.parameters_model.Rd +++ b/man/print.parameters_model.Rd @@ -1,10 +1,28 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/print.parameters_model.R -\name{print.parameters_model} +% Please edit documentation in R/format.R, R/print.parameters_model.R +\name{format.parameters_model} +\alias{format.parameters_model} \alias{print.parameters_model} \alias{summary.parameters_model} \title{Print model parameters} \usage{ +\method{format}{parameters_model}( + x, + pretty_names = TRUE, + split_components = TRUE, + select = NULL, + digits = 2, + ci_digits = digits, + p_digits = 3, + ci_width = NULL, + ci_brackets = NULL, + zap_small = FALSE, + format = NULL, + groups = NULL, + include_reference = FALSE, + ... +) + \method{print}{parameters_model}( x, pretty_names = TRUE, @@ -86,14 +104,6 @@ For \code{model_parameters()}, glue-like syntax is still experimental in the case of more complex models (like mixed models) and may not return expected results.} -\item{caption}{Table caption as string. If \code{NULL}, depending on the model, -either a default caption or no table caption is printed. Use \code{caption = ""} -to suppress the table caption.} - -\item{footer}{Can either be \code{FALSE} or an empty string (i.e. \code{""}) to -suppress the footer, \code{NULL} to print the default footer, or a string. The -latter will combine the string value with the default footer.} - \item{digits, ci_digits, p_digits}{Number of digits for rounding or significant figures. May also be \code{"signif"} to return significant figures or \code{"scientific"} to return scientific notation. Control the @@ -101,17 +111,21 @@ number of digits by adding the value as suffix, e.g. \code{digits = "scientific4 to have scientific notation with 4 decimal places, or \code{digits = "signif5"} for 5 significant figures (see also \code{\link[=signif]{signif()}}).} -\item{footer_digits}{Number of decimal places for values in the footer summary.} +\item{ci_width}{Minimum width of the returned string for confidence +intervals. If not \code{NULL} and width is larger than the string's length, +leading whitespaces are added to the string. If \code{width="auto"}, width +will be set to the length of the longest string.} -\item{show_sigma}{Logical, if \code{TRUE}, adds information about the residual -standard deviation.} - -\item{show_formula}{Logical, if \code{TRUE}, adds the model formula to the output.} +\item{ci_brackets}{Logical, if \code{TRUE} (default), CI-values are +encompassed in square brackets (else in parentheses).} \item{zap_small}{Logical, if \code{TRUE}, small values are rounded after \code{digits} decimal places. If \code{FALSE}, values with more decimal places than \code{digits} are printed in scientific notation.} +\item{format}{String, indicating the output format. Can be \code{"markdown"} +or \code{"html"}.} + \item{groups}{Named list, can be used to group parameters in the printed output. List elements may either be character vectors that match the name of those parameters that belong to one group, or list elements can be row numbers @@ -122,16 +136,6 @@ variables, see 'Examples'. Parameters will be re-ordered according to the order used in \code{groups}, while all non-matching parameters will be added to the end.} -\item{column_width}{Width of table columns. Can be either \code{NULL}, a named -numeric vector, or \code{"fixed"}. If \code{NULL}, the width for each table column is -adjusted to the minimum required width. If a named numeric vector, value -names are matched against column names, and for each match, the specified -width is used. If \code{"fixed"}, and table is split into multiple components, -columns across all table components are adjusted to have the same width.} - -\item{ci_brackets}{Logical, if \code{TRUE} (default), CI-values are -encompassed in square brackets (else in parentheses).} - \item{include_reference}{Logical, if \code{TRUE}, the reference level of factors will be added to the parameters table. This is only relevant for models with categorical predictors. The coefficient for the reference level is always @@ -139,6 +143,28 @@ categorical predictors. The coefficient for the reference level is always so this is just for completeness.} \item{...}{Arguments passed to or from other methods.} + +\item{caption}{Table caption as string. If \code{NULL}, depending on the model, +either a default caption or no table caption is printed. Use \code{caption = ""} +to suppress the table caption.} + +\item{footer}{Can either be \code{FALSE} or an empty string (i.e. \code{""}) to +suppress the footer, \code{NULL} to print the default footer, or a string. The +latter will combine the string value with the default footer.} + +\item{footer_digits}{Number of decimal places for values in the footer summary.} + +\item{show_sigma}{Logical, if \code{TRUE}, adds information about the residual +standard deviation.} + +\item{show_formula}{Logical, if \code{TRUE}, adds the model formula to the output.} + +\item{column_width}{Width of table columns. Can be either \code{NULL}, a named +numeric vector, or \code{"fixed"}. If \code{NULL}, the width for each table column is +adjusted to the minimum required width. If a named numeric vector, value +names are matched against column names, and for each match, the specified +width is used. If \code{"fixed"}, and table is split into multiple components, +columns across all table components are adjusted to have the same width.} } \value{ Invisibly returns the original input object. From c0eceb3287c6d3afac7789d138308cd8213fe82c Mon Sep 17 00:00:00 2001 From: Daniel Date: Mon, 10 Jun 2024 21:58:17 +0200 Subject: [PATCH 4/8] docs --- R/print_html.R | 2 +- R/print_md.R | 2 +- man/display.parameters_model.Rd | 64 +---------------------------- man/print.compare_parameters.Rd | 12 ++++++ man/print.parameters_model.Rd | 71 ++++++++++++++++++++++++++++++++- 5 files changed, 85 insertions(+), 66 deletions(-) diff --git a/R/print_html.R b/R/print_html.R index d67fd51b5..5c37b831e 100644 --- a/R/print_html.R +++ b/R/print_html.R @@ -1,6 +1,6 @@ # normal print ---------------------------- -#' @rdname display.parameters_model +#' @rdname print.parameters_model #' @export print_html.parameters_model <- function(x, pretty_names = TRUE, diff --git a/R/print_md.R b/R/print_md.R index 0fbe401c6..cc997fe3a 100644 --- a/R/print_md.R +++ b/R/print_md.R @@ -1,6 +1,6 @@ # normal print ---------------------------- -#' @rdname display.parameters_model +#' @rdname print.parameters_model #' @export print_md.parameters_model <- function(x, pretty_names = TRUE, diff --git a/man/display.parameters_model.Rd b/man/display.parameters_model.Rd index f35729439..b9519864d 100644 --- a/man/display.parameters_model.Rd +++ b/man/display.parameters_model.Rd @@ -1,14 +1,11 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/display.R, R/print_html.R, R/print_md.R, -% R/print_table.R +% Please edit documentation in R/display.R, R/print_table.R \name{display.parameters_model} \alias{display.parameters_model} \alias{display.parameters_sem} \alias{display.parameters_efa_summary} \alias{display.parameters_efa} \alias{display.equivalence_test_lm} -\alias{print_html.parameters_model} -\alias{print_md.parameters_model} \alias{print_table} \title{Print tables in different output formats} \usage{ @@ -62,55 +59,6 @@ \method{display}{equivalence_test_lm}(object, format = "markdown", digits = 2, ...) -\method{print_html}{parameters_model}( - x, - pretty_names = TRUE, - split_components = TRUE, - select = NULL, - caption = NULL, - subtitle = NULL, - footer = NULL, - align = NULL, - digits = 2, - ci_digits = digits, - p_digits = 3, - footer_digits = 3, - ci_brackets = c("(", ")"), - show_sigma = FALSE, - show_formula = FALSE, - zap_small = FALSE, - groups = NULL, - font_size = "100\%", - line_padding = 4, - column_labels = NULL, - include_reference = FALSE, - verbose = TRUE, - ... -) - -\method{print_md}{parameters_model}( - x, - pretty_names = TRUE, - split_components = TRUE, - select = NULL, - caption = NULL, - subtitle = NULL, - footer = NULL, - align = NULL, - digits = 2, - ci_digits = digits, - p_digits = 3, - footer_digits = 3, - ci_brackets = c("(", ")"), - show_sigma = FALSE, - show_formula = FALSE, - zap_small = FALSE, - groups = NULL, - include_reference = FALSE, - verbose = TRUE, - ... -) - print_table(x, digits = 2, p_digits = 3, theme = "default", ...) } \arguments{ @@ -242,16 +190,6 @@ loadings data. Usually, the question related to the item.} \item{x}{An object returned by \code{\link[=model_parameters]{model_parameters()}}.} -\item{groups}{Named list, can be used to group parameters in the printed output. -List elements may either be character vectors that match the name of those -parameters that belong to one group, or list elements can be row numbers -of those parameter rows that should belong to one group. The names of the -list elements will be used as group names, which will be inserted as "header -row". A possible use case might be to emphasize focal predictors and control -variables, see 'Examples'. Parameters will be re-ordered according to the -order used in \code{groups}, while all non-matching parameters will be added -to the end.} - \item{theme}{String, indicating the table theme. Can be one of \code{"default"}, \code{"grid"}, \code{"striped"}, \code{"bootstrap"} or \code{"darklines"}.} } diff --git a/man/print.compare_parameters.Rd b/man/print.compare_parameters.Rd index e05ba36ee..f2d4e093d 100644 --- a/man/print.compare_parameters.Rd +++ b/man/print.compare_parameters.Rd @@ -167,6 +167,11 @@ to the end.} either a default caption or no table caption is printed. Use \code{caption = ""} to suppress the table caption.} +\item{subtitle}{Table title (same as caption) and subtitle, as strings. If \code{NULL}, +no title or subtitle is printed, unless it is stored as attributes (\code{table_title}, +or its alias \code{table_caption}, and \code{table_subtitle}). If \code{x} is a list of +data frames, \code{caption} may be a list of table captions, one for each table.} + \item{footer}{Can either be \code{FALSE} or an empty string (i.e. \code{""}) to suppress the footer, \code{NULL} to print the default footer, or a string. The latter will combine the string value with the default footer.} @@ -177,6 +182,13 @@ adjusted to the minimum required width. If a named numeric vector, value names are matched against column names, and for each match, the specified width is used. If \code{"fixed"}, and table is split into multiple components, columns across all table components are adjusted to have the same width.} + +\item{font_size}{For HTML tables, the font size.} + +\item{line_padding}{For HTML tables, the distance (in pixel) between lines.} + +\item{column_labels}{Labels of columns for HTML tables. If \code{NULL}, automatic +column names are generated. See 'Examples'.} } \value{ Invisibly returns the original input object. diff --git a/man/print.parameters_model.Rd b/man/print.parameters_model.Rd index b12be286a..f574b3360 100644 --- a/man/print.parameters_model.Rd +++ b/man/print.parameters_model.Rd @@ -1,9 +1,12 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/format.R, R/print.parameters_model.R +% Please edit documentation in R/format.R, R/print.parameters_model.R, +% R/print_html.R, R/print_md.R \name{format.parameters_model} \alias{format.parameters_model} \alias{print.parameters_model} \alias{summary.parameters_model} +\alias{print_html.parameters_model} +\alias{print_md.parameters_model} \title{Print model parameters} \usage{ \method{format}{parameters_model}( @@ -45,6 +48,55 @@ ) \method{summary}{parameters_model}(object, ...) + +\method{print_html}{parameters_model}( + x, + pretty_names = TRUE, + split_components = TRUE, + select = NULL, + caption = NULL, + subtitle = NULL, + footer = NULL, + align = NULL, + digits = 2, + ci_digits = digits, + p_digits = 3, + footer_digits = 3, + ci_brackets = c("(", ")"), + show_sigma = FALSE, + show_formula = FALSE, + zap_small = FALSE, + groups = NULL, + font_size = "100\%", + line_padding = 4, + column_labels = NULL, + include_reference = FALSE, + verbose = TRUE, + ... +) + +\method{print_md}{parameters_model}( + x, + pretty_names = TRUE, + split_components = TRUE, + select = NULL, + caption = NULL, + subtitle = NULL, + footer = NULL, + align = NULL, + digits = 2, + ci_digits = digits, + p_digits = 3, + footer_digits = 3, + ci_brackets = c("(", ")"), + show_sigma = FALSE, + show_formula = FALSE, + zap_small = FALSE, + groups = NULL, + include_reference = FALSE, + verbose = TRUE, + ... +) } \arguments{ \item{x, object}{An object returned by \code{\link[=model_parameters]{model_parameters()}}.} @@ -165,6 +217,23 @@ adjusted to the minimum required width. If a named numeric vector, value names are matched against column names, and for each match, the specified width is used. If \code{"fixed"}, and table is split into multiple components, columns across all table components are adjusted to have the same width.} + +\item{subtitle}{Table title (same as caption) and subtitle, as strings. If \code{NULL}, +no title or subtitle is printed, unless it is stored as attributes (\code{table_title}, +or its alias \code{table_caption}, and \code{table_subtitle}). If \code{x} is a list of +data frames, \code{caption} may be a list of table captions, one for each table.} + +\item{align}{Only applies to HTML tables. May be one of \code{"left"}, +\code{"right"} or \code{"center"}.} + +\item{font_size}{For HTML tables, the font size.} + +\item{line_padding}{For HTML tables, the distance (in pixel) between lines.} + +\item{column_labels}{Labels of columns for HTML tables. If \code{NULL}, automatic +column names are generated. See 'Examples'.} + +\item{verbose}{Toggle messages and warnings.} } \value{ Invisibly returns the original input object. From 597d0e5b37c43536b38e26885ae968c1c719d91a Mon Sep 17 00:00:00 2001 From: Daniel Date: Mon, 10 Jun 2024 22:16:18 +0200 Subject: [PATCH 5/8] dont use remotes --- DESCRIPTION | 1 - 1 file changed, 1 deletion(-) diff --git a/DESCRIPTION b/DESCRIPTION index 3bf54a23c..e0306819a 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -218,4 +218,3 @@ Config/Needs/website: r-lib/pkgdown, easystats/easystatstemplate Config/rcmdcheck/ignore-inconsequential-notes: true -Remotes: easystats/insight, easystats/datawizard, easystats/performance, easystats/bayestestR, easystats/effectsize From 58af1878f8456d20a3024d98c7adda0689a141a2 Mon Sep 17 00:00:00 2001 From: Daniel Date: Mon, 10 Jun 2024 22:22:44 +0200 Subject: [PATCH 6/8] lintr, docs --- R/format.R | 2 +- R/principal_components.R | 2 +- R/print.compare_parameters.R | 9 ++++++++- man/principal_components.Rd | 2 +- man/print.compare_parameters.Rd | 10 +++++++++- 5 files changed, 20 insertions(+), 5 deletions(-) diff --git a/R/format.R b/R/format.R index 5678eeb0c..86b8868cf 100644 --- a/R/format.R +++ b/R/format.R @@ -672,7 +672,7 @@ format.parameters_sem <- function(x, # footer: r-squared .add_footer_r2 <- function(footer = NULL, digits = 3, r2 = NULL, type = "text") { if (!is.null(r2)) { - rsq <- .safe(paste0(unlist(lapply(r2, function(i) { + rsq <- .safe(paste(unlist(lapply(r2, function(i) { paste0(attributes(i)$names, ": ", insight::format_value(i, digits = digits)) })), collapse = "; ")) diff --git a/R/principal_components.R b/R/principal_components.R index 9576d86a4..9f3e74f8e 100644 --- a/R/principal_components.R +++ b/R/principal_components.R @@ -45,7 +45,7 @@ #' @param digits Argument for `print()`, indicates the number of digits #' (rounding) to be used. #' @param labels Argument for `print()`, character vector of same length as -#' columns in `x`. If provided, adds an additonal column with the labels. +#' columns in `x`. If provided, adds an additional column with the labels. #' @param verbose Toggle warnings. #' @inheritParams n_factors #' diff --git a/R/print.compare_parameters.R b/R/print.compare_parameters.R index 40dd6d556..f4ef5a200 100644 --- a/R/print.compare_parameters.R +++ b/R/print.compare_parameters.R @@ -3,7 +3,14 @@ #' #' @description A `print()`-method for objects from [`compare_parameters()`]. #' -#' @param x,object An object returned by [`compare_parameters()`]. +#' @param x An object returned by [`compare_parameters()`]. +#' @param engine Character string, naming the package or engine to be used for +#' printing into HTML or markdown format. Currently supported `"gt"` (or +#' `"default"`) to use the *gt* package to print to HTML and the default easystats +#' engine to create markdown tables. If `engine = "tt"`, the *tinytable* package +#' is used for printing to HTML or markdown. Not all `print()` methods support +#' the `"tt"` engine yet. If a specific `print()` method has no `engine` argument, +#' `insight::export_table()` is used, which uses *gt* for HTML printing. #' @inheritParams print.parameters_model #' @inheritSection print.parameters_model Global Options to Customize Messages and Tables when Printing #' diff --git a/man/principal_components.Rd b/man/principal_components.Rd index 7772fda4e..d851baa0c 100644 --- a/man/principal_components.Rd +++ b/man/principal_components.Rd @@ -110,7 +110,7 @@ predicted data and original data is equal.} (rounding) to be used.} \item{labels}{Argument for \code{print()}, character vector of same length as -columns in \code{x}. If provided, adds an additonal column with the labels.} +columns in \code{x}. If provided, adds an additional column with the labels.} } \value{ A data frame of loadings. diff --git a/man/print.compare_parameters.Rd b/man/print.compare_parameters.Rd index f2d4e093d..3dc6cdb69 100644 --- a/man/print.compare_parameters.Rd +++ b/man/print.compare_parameters.Rd @@ -78,7 +78,7 @@ ) } \arguments{ -\item{x, object}{An object returned by \code{\link[=compare_parameters]{compare_parameters()}}.} +\item{x}{An object returned by \code{\link[=compare_parameters]{compare_parameters()}}.} \item{split_components}{Logical, if \code{TRUE} (default), For models with multiple components (zero-inflation, smooth terms, ...), each component is @@ -161,6 +161,14 @@ variables, see 'Examples'. Parameters will be re-ordered according to the order used in \code{groups}, while all non-matching parameters will be added to the end.} +\item{engine}{Character string, naming the package or engine to be used for +printing into HTML or markdown format. Currently supported \code{"gt"} (or +\code{"default"}) to use the \emph{gt} package to print to HTML and the default easystats +engine to create markdown tables. If \code{engine = "tt"}, the \emph{tinytable} package +is used for printing to HTML or markdown. Not all \code{print()} methods support +the \code{"tt"} engine yet. If a specific \code{print()} method has no \code{engine} argument, +\code{insight::export_table()} is used, which uses \emph{gt} for HTML printing.} + \item{...}{Arguments passed to or from other methods.} \item{caption}{Table caption as string. If \code{NULL}, depending on the model, From 43f8f298010587c9f5b0bca47524582b6c018e33 Mon Sep 17 00:00:00 2001 From: Daniel Date: Mon, 10 Jun 2024 22:27:25 +0200 Subject: [PATCH 7/8] docs --- R/display.R | 4 ++-- R/print.parameters_model.R | 6 ++---- man/display.parameters_model.Rd | 4 ++-- man/print.parameters_model.Rd | 4 +--- 4 files changed, 7 insertions(+), 11 deletions(-) diff --git a/R/display.R b/R/display.R index 8b4238891..6b348bc9e 100644 --- a/R/display.R +++ b/R/display.R @@ -2,8 +2,8 @@ #' @name display.parameters_model #' #' @description Prints tables (i.e. data frame) in different output formats. -#' `print_md()` is a alias for `display(format = "markdown")`, `print_html()` -#' is a alias for `display(format = "html")`. `print_table()` is for specific +#' `print_md()` is an alias for `display(format = "markdown")`, `print_html()` +#' is an alias for `display(format = "html")`. `print_table()` is for specific #' use cases only, and currently only works for `compare_parameters()` objects. #' #' @param x An object returned by [`model_parameters()`]. diff --git a/R/print.parameters_model.R b/R/print.parameters_model.R index cfc58660b..35876aff2 100644 --- a/R/print.parameters_model.R +++ b/R/print.parameters_model.R @@ -143,13 +143,11 @@ #' create HTML tables. If set to `tt`, the _tinytable_ package is used. #' #' @details `summary()` is a convenient shortcut for -#' `print(object, select = "minimal", show_sigma = TRUE, show_formula = TRUE)`. +#' `print(object, select = "minimal", show_sigma = TRUE, show_formula = TRUE)`. #' #' @return Invisibly returns the original input object. #' -#' @seealso There is a dedicated method to use inside rmarkdown files, -#' [`print_md()`][print_md.parameters_model]. See also -#' [`display()`][display.parameters_model]. +#' @seealso See also [`display()`][display.parameters_model]. #' #' @examplesIf require("gt", quietly = TRUE) && require("glmmTMB", quietly = TRUE) #' \donttest{ diff --git a/man/display.parameters_model.Rd b/man/display.parameters_model.Rd index b9519864d..0ae40397a 100644 --- a/man/display.parameters_model.Rd +++ b/man/display.parameters_model.Rd @@ -201,8 +201,8 @@ returned. } \description{ Prints tables (i.e. data frame) in different output formats. -\code{print_md()} is a alias for \code{display(format = "markdown")}, \code{print_html()} -is a alias for \code{display(format = "html")}. \code{print_table()} is for specific +\code{print_md()} is an alias for \code{display(format = "markdown")}, \code{print_html()} +is an alias for \code{display(format = "html")}. \code{print_table()} is for specific use cases only, and currently only works for \code{compare_parameters()} objects. } \details{ diff --git a/man/print.parameters_model.Rd b/man/print.parameters_model.Rd index f574b3360..1b813fb66 100644 --- a/man/print.parameters_model.Rd +++ b/man/print.parameters_model.Rd @@ -392,7 +392,5 @@ print_html(result) \dontshow{\}) # examplesIf} } \seealso{ -There is a dedicated method to use inside rmarkdown files, -\code{\link[=print_md.parameters_model]{print_md()}}. See also -\code{\link[=display.parameters_model]{display()}}. +See also \code{\link[=display.parameters_model]{display()}}. } From a88bef1ac84f2247a8fad524da866cdf280d2fa7 Mon Sep 17 00:00:00 2001 From: Daniel Date: Mon, 10 Jun 2024 22:54:53 +0200 Subject: [PATCH 8/8] fix --- R/print.compare_parameters.R | 2 +- man/print.compare_parameters.Rd | 2 ++ pkgdown/_pkgdown.yml | 1 + 3 files changed, 4 insertions(+), 1 deletion(-) diff --git a/R/print.compare_parameters.R b/R/print.compare_parameters.R index f4ef5a200..61cf91560 100644 --- a/R/print.compare_parameters.R +++ b/R/print.compare_parameters.R @@ -16,7 +16,7 @@ #' #' @return Invisibly returns the original input object. #' -#' @examples +#' @examplesIf require("gt", quietly = TRUE) #' \donttest{ #' data(iris) #' lm1 <- lm(Sepal.Length ~ Species, data = iris) diff --git a/man/print.compare_parameters.Rd b/man/print.compare_parameters.Rd index 3dc6cdb69..c09b5a9b4 100644 --- a/man/print.compare_parameters.Rd +++ b/man/print.compare_parameters.Rd @@ -246,6 +246,7 @@ create HTML tables. If set to \code{tt}, the \emph{tinytable} package is used. } \examples{ +\dontshow{if (require("gt", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} \donttest{ data(iris) lm1 <- lm(Sepal.Length ~ Species, data = iris) @@ -259,4 +260,5 @@ print(result) result <- compare_parameters(lm1, lm2, select = "{estimate}
({se})|{p}") print_html(result) } +\dontshow{\}) # examplesIf} } diff --git a/pkgdown/_pkgdown.yml b/pkgdown/_pkgdown.yml index a6fef29f8..2a2543b5b 100644 --- a/pkgdown/_pkgdown.yml +++ b/pkgdown/_pkgdown.yml @@ -102,6 +102,7 @@ reference: - format_parameters - format_p_adjust - format_df_adjust + - format.compare_parameters - parameters_type - print_md