model_tree: Create a tree diagram of a modeling directory

In metrumresearchgroup/bbr: R package for bbi

Create a tree diagram of a modeling directory

Description

Create a tree diagram of a modeling directory

Usage

model_tree(
  .log_df,
  include_info = c("description", "star", "tags"),
  color_by = "run",
  size_by = NULL,
  add_summary = TRUE,
  digits = 3,
  zoomable = FALSE,
  static = FALSE,
  width = NULL,
  height = NULL,
  font_size = 10,
  ...
)

Arguments

.log_df	A bbi_run_log_df tibble (the output of run_log()) or a base directory to look in for models. See details for more options.
include_info	A vector of columns present in .log_df to include in the tooltip.
color_by	A run log column to color the nodes by. Can be helpful for identifying which models are starred, have heuristics, etc. See details for more information.
size_by	A numeric (or integer) run log column to size the nodes by. If not specified, the default is to size the nodes based on how many models are based on it.
add_summary	Logical (TRUE/FALSE). If TRUE, include key columns from model_summary() output.
digits	Number of digits to round decimal places to for display in the tooltip.
zoomable	Logical (TRUE/FALSE). If TRUE, allow pan and zoom by dragging and scrolling.
static	Logical (TRUE/FALSE). If TRUE, render the plot as a static image. This takes a little longer, as the interactive plot must be saved as a PNG and loaded into the viewer.
width	Width in pixels (optional, defaults to automatic sizing)
height	Height in pixels (optional, defaults to automatic sizing)
font_size	Font size of the label text in pixels
...	Additional arguments passed to run_log(). Only used if .log_df is a modeling directory.

Required Columns

.log_df must contain absolute_model_path, run, and based_on columns in order to properly link and label each of the models, where the based_on attribute is used to determine the tree network.

• Additional based_on flags will be shown in the tooltip, using the first one to create the tree network

Any dataframe with the bbi_run_log_df class and required columns can be used. In other words, users can add/modify columns of their run_log(), and pass these additional columns as tooltips. This is illustrated in the examples via add_summary() and add_config().

Tooltip formatting, coloring, and sizing

Tooltip formatting

Any column in .log_df can be chosen to include in the tooltip. However, certain columns will be formatted specially if specified via include_info. Any other column will be displayed as verbatim text (no special handling), though column names will be formatted slightly.

Specially formatted columns (if specified via include_info):

• 'description', 'tags', and 'star'

• When add_summary = TRUE these specific summary columns are also formatted specially:

  • 'number_of_subjects', 'number_of_obs', 'ofv', and 'any_heuristics'.

  • Note that the above summary columns will only receive the special formatting if added via add_summary = TRUE.

  • i.e. if .log_df = run_log() %>% add_summary() and include_info = 'ofv', the 'OFV' parameter will display the same as if it was not passed to include_info.

Coloring

Logical columns are handled differently from numeric or character columns. Nodes will be colored 'white' for FALSE and 'red' for TRUE. All other column types will be colored via a gradient between 'white' and 'red', where earlier runs are whiter, and later runs appear to be more red. You can pass color_by = NULL to make all model nodes 'red'.

Examples

## Not run: 

# Basic
MODEL_DIR %>% model_tree()
run_log(MODEL_DIR) %>% model_tree()

# Color by a column
model_tree(MODEL_DIR, color_by = "star")


## Run `add_config()`, `add_summary()`, and/or `mutate()` calls beforehand


# Size nodes by objective function value
run_log(MODEL_DIR) %>% add_summary() %>%
  model_tree(size_by = "ofv", color_by = "ofv")

# Determine if certain models need to be re-run
run_log(MODEL_DIR) %>% add_config() %>%
  dplyr::mutate(
    out_of_date = model_has_changed | data_has_changed
  ) %>%
  model_tree(
    include_info = c("model_has_changed", "data_has_changed", "nm_version"),
    color_by = "out_of_date"
  )

# Highlight models with any heuristics
run_log(MODEL_DIR) %>% add_summary() %>%
  model_tree(
    include_info = c("param_count", "eta_pval_significant"),
    color_by = "any_heuristics"
  )


## End(Not run)

metrumresearchgroup/bbr documentation built on March 29, 2025, 1:08 p.m.