Create a tree diagram of a modeling directory

Create a tree diagram of a modeling directory

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

# S3 method for character
model_tree(
  .log_df,
  include_info = c("description", "star", "tags"),
  color_by = "run",
  add_summary = TRUE,
  digits = 3,
  zoomable = FALSE,
  static = FALSE,
  width = NULL,
  height = NULL,
  ...
)

# S3 method for bbi_log_df
model_tree(
  .log_df,
  include_info = c("description", "star", "tags"),
  color_by = "run",
  add_summary = TRUE,
  digits = 3,
  zoomable = FALSE,
  static = FALSE,
  width = NULL,
  height = NULL,
  ...
)

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

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.

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)

...

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 and coloring

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 be formatted as any other additional column.

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

if (FALSE) {

# 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
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"
  )

run_log(MODEL_DIR) %>%
  add_summary() %>%
  model_tree(
    include_info = c("tags", "param_count", "eta_pval_significant"),
    color_by = "any_heuristics"
  )

}