Prepare summary statistics of model parameters for printing

This function takes a data frame, typically a data frame with information on summaries of model parameters like bayestestR::describe_posterior(), bayestestR::hdi() or parameters::model_parameters(), as input and splits this information into several parts, depending on the model. See details below.

Usage

print_parameters(
  x,
  ...,
  by = c("Effects", "Component", "Group", "Response"),
  format = "text",
  parameter_column = "Parameter",
  keep_parameter_column = TRUE,
  remove_empty_column = FALSE,
  titles = NULL,
  subtitles = NULL
)

Arguments

x: A fitted model, or a data frame returned by clean_parameters().
...: One or more objects (data frames), which contain information about the model parameters and related statistics (like confidence intervals, HDI, ROPE, ...).
by: by should be a character vector with one or more of the following elements: "Effects", "Component", "Response" and "Group". These are the column names returned by clean_parameters(), which is used to extract the information from which the group or component model parameters belong. If NULL, the merged data frame is returned. Else, the data frame is split into a list, split by the values from those columns defined in by.
format: Name of output-format, as string. If NULL (or "text"), assumed use for output is basic printing. If "markdown", markdown-format is assumed. This only affects the style of title- and table-caption attributes, which are used in export_table().
parameter_column: String, name of the column that contains the parameter names. Usually, for data frames returned by functions the easystats-packages, this will be "Parameter".
keep_parameter_column: Logical, if TRUE, the data frames in the returned list have both a "Cleaned_Parameter" and "Parameter" column. If FALSE, the (unformatted) "Parameter" is removed, and the column with cleaned parameter names ("Cleaned_Parameter") is renamed into "Parameter".
remove_empty_column: Logical, if TRUE, columns with completely empty character values will be removed.
titles, subtitles: By default, the names of the model components (like fixed or random effects, count or zero-inflated model part) are added as attributes "table_title" and "table_subtitle" to each list element returned by print_parameters(). These attributes are then extracted and used as table (sub) titles in export_table(). Use titles and subtitles to override the default attribute values for "table_title" and "table_subtitle". titles and subtitles may be any length from 1 to same length as returned list elements. If titles and subtitles are shorter than existing elements, only the first default attributes are overwritten.

Value

A data frame or a list of data frames (if by is not NULL). If a list is returned, the element names reflect the model components where the extracted information in the data frames belong to, e.g. random.zero_inflated.Intercept: persons. This is the data frame that contains the parameters for the random effects from group-level "persons" from the zero-inflated model component.

Details

This function prepares data frames that contain information about model parameters for clear printing.

First, x is required, which should either be a model object or a prepared data frame as returned by clean_parameters(). If x is a model, clean_parameters() is called on that model object to get information with which model components the parameters are associated.

Then, ... take one or more data frames that also contain information about parameters from the same model, but also have additional information provided by other methods. For instance, a data frame in ... might be the result of, for instance, bayestestR::describe_posterior(), or parameters::model_parameters(), where we have a) a Parameter column and b) columns with other parameter values (like CI, HDI, test statistic, etc.).

Now we have a data frame with model parameters and information about the association to the different model components, a data frame with model parameters, and some summary statistics. print_parameters() then merges these data frames, so the parameters or statistics of interest are also associated with the different model components. The data frame is split into a list, so for a clear printing. Users can loop over this list and print each component for a better overview. Further, parameter names are "cleaned", if necessary, also for a cleaner print. See also 'Examples'.

Examples

# \donttest{
library(bayestestR)
model <- download_model("brms_zi_2")
x <- hdi(model, effects = "all", component = "all")

# hdi() returns a data frame; here we use only the
# information on parameter names and HDI values
tmp <- as.data.frame(x)[, 1:4]
tmp
#>                     Parameter   CI        CI_low     CI_high
#> 1                 b_Intercept 0.95 -1.5750655217 -0.19121613
#> 4                   b_persons 0.95  0.6184455532  1.06881424
#> 3                     b_child 0.95 -1.3162422984 -0.95758109
#> 2                    b_camper 0.95  0.5461831894  0.92611577
#> 8      r_persons[1,Intercept] 0.95 -0.5330733515  0.35294394
#> 9      r_persons[2,Intercept] 0.95 -0.2223371232  0.38996718
#> 10     r_persons[3,Intercept] 0.95 -0.3042515304  0.23075738
#> 11     r_persons[4,Intercept] 0.95 -0.3385211340  0.42306128
#> 16      sd_persons__Intercept 0.95  0.0001646025  0.53508587
#> 5              b_zi_Intercept 0.95 -2.1380522885  0.81535164
#> 7                  b_zi_child 0.95  1.2372839351  2.55611481
#> 6                 b_zi_camper 0.95 -1.5578690989 -0.13785783
#> 12 r_persons__zi[1,Intercept] 0.95 -0.2851875068  2.79744522
#> 13 r_persons__zi[2,Intercept] 0.95 -1.2294623420  1.76053356
#> 14 r_persons__zi[3,Intercept] 0.95 -1.6701942638  1.34558714
#> 15 r_persons__zi[4,Intercept] 0.95 -2.9688353496  0.08844285
#> 17   sd_persons__zi_Intercept 0.95  0.3711927016  3.06955610

# Based on the "by" argument, we get a list of data frames that
# is split into several parts that reflect the model components.
print_parameters(model, tmp)
#> $fixed.conditional
#>   Cleaned_Parameter   Parameter   CI     CI_low    CI_high
#> 1       (Intercept) b_Intercept 0.95 -1.5750655 -0.1912161
#> 2           persons   b_persons 0.95  0.6184456  1.0688142
#> 3             child     b_child 0.95 -1.3162423 -0.9575811
#> 4            camper    b_camper 0.95  0.5461832  0.9261158
#> 
#> $fixed.zero_inflated
#>    Cleaned_Parameter      Parameter   CI    CI_low    CI_high
#> 10       (Intercept) b_zi_Intercept 0.95 -2.138052  0.8153516
#> 11             child     b_zi_child 0.95  1.237284  2.5561148
#> 12            camper    b_zi_camper 0.95 -1.557869 -0.1378578
#> 
#> $`random.conditional.Intercept: persons`
#>   Cleaned_Parameter              Parameter   CI     CI_low   CI_high
#> 5         persons.1 r_persons[1,Intercept] 0.95 -0.5330734 0.3529439
#> 6         persons.2 r_persons[2,Intercept] 0.95 -0.2223371 0.3899672
#> 7         persons.3 r_persons[3,Intercept] 0.95 -0.3042515 0.2307574
#> 8         persons.4 r_persons[4,Intercept] 0.95 -0.3385211 0.4230613
#> 
#> $`random.zero_inflated.Intercept: persons`
#>    Cleaned_Parameter                  Parameter   CI     CI_low    CI_high
#> 13         persons.1 r_persons__zi[1,Intercept] 0.95 -0.2851875 2.79744522
#> 14         persons.2 r_persons__zi[2,Intercept] 0.95 -1.2294623 1.76053356
#> 15         persons.3 r_persons__zi[3,Intercept] 0.95 -1.6701943 1.34558714
#> 16         persons.4 r_persons__zi[4,Intercept] 0.95 -2.9688353 0.08844285
#> 
#> $`random.conditional.SD/Cor: persons`
#>   Cleaned_Parameter             Parameter   CI       CI_low   CI_high
#> 9       (Intercept) sd_persons__Intercept 0.95 0.0001646025 0.5350859
#> 
#> $`random.zero_inflated.SD/Cor: persons`
#>    Cleaned_Parameter                Parameter   CI    CI_low  CI_high
#> 17       (Intercept) sd_persons__zi_Intercept 0.95 0.3711927 3.069556
#> 

# This is the standard print()-method for "bayestestR::hdi"-objects.
# For printing methods, it is easy to print complex summary statistics
# in a clean way to the console by splitting the information into
# different model components.
x
#> Highest Density Interval 
#> 
#> Parameter   |        95% HDI
#> ----------------------------
#> (Intercept) | [-1.58, -0.19]
#> persons     | [ 0.62,  1.07]
#> child       | [-1.32, -0.96]
#> camper      | [ 0.55,  0.93]
#> 
#> # Fixed effects (zero-inflated) 
#> 
#> Parameter   |        95% HDI
#> ----------------------------
#> (Intercept) | [-2.14,  0.82]
#> child       | [ 1.24,  2.56]
#> camper      | [-1.56, -0.14]
#> 
#> # Random effects (conditional) Intercept: persons
#> 
#> Parameter |        95% HDI
#> --------------------------
#> persons.1 | [-0.53,  0.35]
#> persons.2 | [-0.22,  0.39]
#> persons.3 | [-0.30,  0.23]
#> persons.4 | [-0.34,  0.42]
#> 
#> # Random effects (zero-inflated) Intercept: persons
#> 
#> Parameter |        95% HDI
#> --------------------------
#> persons.1 | [-0.29,  2.80]
#> persons.2 | [-1.23,  1.76]
#> persons.3 | [-1.67,  1.35]
#> persons.4 | [-2.97,  0.09]
#> 
#> # Random effects (conditional) SD/Cor: persons
#> 
#> Parameter   |        95% HDI
#> ----------------------------
#> (Intercept) | [ 0.00,  0.54]
#> 
#> # Random effects (zero-inflated) SD/Cor: persons
#> 
#> Parameter   |        95% HDI
#> ----------------------------
#> (Intercept) | [ 0.37,  3.07]
# }