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) +} +}