Draft option to enable glue-styled pattern in format_table()

DESCRIPTION

@@ -1,7 +1,7 @@
 Type: Package
 Package: insight
 Title: Easy Access to Model Information for Various Model Objects
-Version: 1.0.2.3
+Version: 1.0.2.4
 Authors@R:
     c(person(given = "Daniel",
              family = "Lüdecke",

NAMESPACE

@@ -1671,6 +1671,7 @@ S3method(trim_ws,list)
 export(all_models_equal)
 export(all_models_same_class)
 export(apply_table_theme)
+export(broom_columns)
 export(check_if_installed)
 export(clean_names)
 export(clean_parameters)
@@ -1683,6 +1684,7 @@ export(compact_character)
 export(compact_list)
 export(display)
 export(download_model)
+export(easystats_columns)
 export(ellipsis_info)
 export(export_table)
 export(find_algorithm)

NEWS.md

@@ -7,6 +7,9 @@
 
 * Argument `ci_digits` defaults to `digits` in `format_table()`.
 
+* `format_table()` gets a `select` argument, which can be used to select columns
+  and column layout in a glue-like style.
+
 # insight 1.0.2
 
 ## Changes

R/format_table.R

@@ -45,6 +45,51 @@
 #'   `stars = "BF"` to only add stars to the Bayes factor and exclude the `pd`
 #'   column. Currently, following columns are recognized: `"BF"`, `"pd"` and `"p"`.
 #' @param stars_only If `TRUE`, return significant stars only (and no p-values).
+#' @param select Determines which columns are printed and the table layout.
+#' There are two options for this argument:
+#'
+#' * **A string expression with layout pattern**
+#'
+#'   `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. Following tokens are replaced by the related
+#'   coefficients or statistics: `{estimate}`, `{se}`, `{ci}` (or `{ci_low}` and
+#'   `{ci_high}`), `{p}`, `{pd}` and `{stars}`. The token `{ci}` will be replaced
+#'   by `{ci_low}, {ci_high}`. Example: `select = "{estimate}{stars} ({ci})"`
+#'
+#'   It is possible to create multiple columns as well. A `|` separates values
+#'   into new cells/columns. Example: `select = "{estimate} ({ci})|{p}"`.
+#'
+#' * **A string indicating a pre-defined layout**
+#'
+#'   `select` can be one of the following string values, to create one of the
+#'   following pre-defined column layouts:
+#'
+#'   - `"minimal"`: Estimates, confidence intervals and numeric p-values, in two
+#'     columns. This is equivalent to `select = "{estimate} ({ci})|{p}"`.
+#'   - `"short"`: Estimate, standard errors and numeric p-values, in two columns.
+#'     This is equivalent to `select = "{estimate} ({se})|{p}"`.
+#'   - `"ci"`: Estimates and confidence intervals, no asterisks for p-values.
+#'     This is equivalent to `select = "{estimate} ({ci})"`.
+#'   - `"se"`: Estimates and standard errors, no asterisks for p-values. This is
+#'     equivalent to `select = "{estimate} ({se})"`.
+#'   - `"ci_p"`: Estimates, confidence intervals and asterisks for p-values. This
+#'     is equivalent to `select = "{estimate}{stars} ({ci})"`.
+#'   - `"se_p"`: Estimates, standard errors and asterisks for p-values. This is
+#'     equivalent to `select = "{estimate}{stars} ({se})"`..
+#'
+#' Using `select` to define columns will re-order columns and remove all columns
+#' related to uncertainty (standard errors, confidence intervals), test statistics,
+#' and p-values (and similar, like `pd` or `BF` for Bayesian models), because
+#' these are assumed to be included or intentionally excluded when using `select`.
+#' The new column order will be: Parameter columns first, followed by the "glue"
+#' columns, followed by all remaining columns. If further columns should also be
+#' placed first, add those as `focal_terms` attributes to `x`. I.e., following
+#' columns are considers as "parameter columns" and placed first:
+#' `c(easystats_columns("parameter"), attributes(x)$focal_terms)`.
+#'
+#' **Note:** glue-like syntax is still experimental in the case of more complex models
+#' (like mixed models) and may not return expected results.
 #' @param ... Arguments passed to or from other methods.
 #' @inheritParams format_p
 #' @inheritParams format_value
@@ -56,13 +101,16 @@
 #'
 #' @note `options(insight_use_symbols = TRUE)` overrides the `use_symbols` argument
 #'   and always displays symbols, if possible.
 #' @examplesIf require("rstanarm", warn.conflicts = FALSE) && require("parameters", warn.conflicts = FALSE) && packageVersion("parameters") > "0.22.2"
 #' format_table(head(iris), digits = 1)
 #'
 #' m <- lm(Sepal.Length ~ Species * Sepal.Width, data = iris)
 #' x <- parameters::model_parameters(m)
 #' as.data.frame(format_table(x))
 #' as.data.frame(format_table(x, p_digits = "scientific"))
+#' # "glue" columns
+#' as.data.frame(format_table(x, select = "minimal"))
+#' as.data.frame(format_table(x, select = "{estimate}{stars}|{p}"))
 #'
 #' \donttest{
 #' model <- rstanarm::stan_glm(
@@ -92,6 +140,7 @@
                          preserve_attributes = FALSE,
                          exact = TRUE,
                          use_symbols = getOption("insight_use_symbols", FALSE),
+                         select = NULL,
                          verbose = TRUE,
                          ...) {
   # validation check
@@ -109,6 +158,15 @@
   if (missing(rope_digits)) rope_digits <- .additional_arguments(x, "rope_digits", digits)
   if (missing(ic_digits)) ic_digits <- .additional_arguments(x, "ic_digits", 1)
 
+  # find name of coefficient, if present
+  coef_column_name <- attributes(x)$coef_name
+  # create p_stars, needed for glue
+  if ("p" %in% colnames(x)) {
+    p_stars <- format_p(x[["p"]], stars = TRUE, stars_only = TRUE)
+  } else {
+    p_stars <- NULL
+  }
+
   att <- attributes(x)
   x <- as.data.frame(x, stringsAsFactors = FALSE)
 
@@ -215,6 +273,17 @@
 
   x[] <- lapply(x, as.character)
 
+  # apply glue-styled formatting
+  if (!is.null(select)) {
+    x <- .format_glue_table(
+      x,
+      style = select,
+      coef_column = coef_column_name,
+      p_stars = p_stars,
+      ...
+    )
+  }
+
   # restore attributes
   if (isTRUE(preserve_attributes)) {
     attributes(x) <- utils::modifyList(att, attributes(x))