Creating a model tree diagram

library(glue)
library(bbr)
library(dplyr)
library(purrr)

Create a model tree diagram

While the run_log(), summary_log(), and config_log() are helpful for summarizing the model development process, model_tree() provides a convenient way to visualize and track any of these tabulated parameters. You can create a tree diagram using a modeling directory or run log.

MODEL_DIR <- "../nonmem"

By default, models will be colored by their run number, and basic summary statistics will display as a tooltip when hovered over.

model_tree(MODEL_DIR)

If coloring by a logical column, FALSE and TRUE values will correspond to white and red coloring respectively. Numeric or character columns will be colored as a gradient. NA values will appear grey regardless of the column type.

model_tree(MODEL_DIR, color_by = "star")

Specific columns can be added to the tooltip via the include_info argument. Though you are limited to the default run_log() columns when passing a model directory, you can pass any available columns when passing a run log dataframe (must inherit the class bbi_log_df). The examples below to illustrate cases where you may want to do that.

log_df <- run_log(MODEL_DIR)
log_df
#> # A tibble: 9 × 10
#>   absolute_model_path         run   yaml_md5 model_type description bbi_args    
#>   <chr>                       <chr> <chr>    <chr>      <chr>       <list>      
#> 1 /data/home/barrettk/.cache… 1     6ccf206… nonmem     original a… <named list>
#> 2 /data/home/barrettk/.cache… 2     b5f8010… nonmem     NA          <named list>
#> 3 /data/home/barrettk/.cache… 3     99d902b… nonmem     NA          <named list>
#> 4 /data/home/barrettk/.cache… 4     5161777… nonmem     NA          <named list>
#> 5 /data/home/barrettk/.cache… 5     690952d… nonmem     NA          <named list>
#> 6 /data/home/barrettk/.cache… 6-bo… 9d66680… nmboot     NA          <named list>
#> 7 /data/home/barrettk/.cache… 6     324dd95… nonmem     final model <named list>
#> 8 /data/home/barrettk/.cache… 7     661f9f1… nonmem     NA          <named list>
#> 9 /data/home/barrettk/.cache… 8     994cb9f… nonmem     NA          <named list>
#> # ℹ 4 more variables: based_on <list>, tags <list>, notes <list>, star <lgl>

In this example we define a new column, out_of_date, to denote whether the model or data has changed since the last run. We can color by this new column to determine if any of the models need to be re-run:

log_df %>% add_config() %>%
  dplyr::mutate(out_of_date = model_has_changed | data_has_changed) %>%
  model_tree(
    include_info = c("model_has_changed", "data_has_changed"),
    color_by = "out_of_date"
  )

The model tree can also be helpful for quickly determine if any heuristics were found during any model submissions, as well as displaying specific model summary output in the tooltip.

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

Size the nodes by a particular column

Controlling the node size can be helpful for quickly determining the trend of a particular numeric column. Here, we use color_by and size_by to show the objective function value decreasing with each new model.

Note: Like the color_by argument, only columns included in log_df can be passed. We have to call add_summary() to use "ofv" even though this is included in the tooltip when add_summary = TRUE.
If size_by is not specified, the nodes are sized based on how many other models/nodes stem from it (i.e. the “final model” will be smaller than the “base model”).

log_df %>% add_summary() %>%
  model_tree(color_by = "ofv", size_by = "ofv")

Kyle Barrett

Create a model tree diagram

Adjust the coloring and tooltip

Size the nodes by a particular column