1.12.0

Release Notes

New features and changes

• New model tree feature: bbr now allows you to visualize any run_log() as
  an interactive model tree diagram via model_tree(). This function allows
  users to easily visualize and track the modeling process for a given project
  and display any information available in a run_log(), such as model summary
  information, configuration options, and more. See the vignette here (#673).

• New run_nmtran() function for running NM-TRAN on a model object to validate
  its control stream for correct coding before submission. The NM-TRAN dataset
  (FDATA) and other NONMEM artifacts can be further inspected by keeping the
  run directory around (#705).

• nm_data() now has a filter argument, allowing the user to filter data based
  on IGNORE LIST or ACCEPT LIST options defined in the $DATA record of a
  NONMEM control stream file (#711).

• setup_bootstrap_run() now has a data argument, allowing users to provide
  their own starting dataset to resample from. This defaults to NULL, which
  will use the output from nm_data(.boot_run, filter = TRUE) (#707, #711).

Bugs addressed

• Bootstrap adjustment: previously setup_bootstrap_run() assumed a NUM column
  was present in the input dataset (the default .join_col in nm_join()).
  nm_join() was being used in the back-end to create the starting dataset to
  resample from; the intention being to only include subjects that entered the
  original problem. Given the nm_join() use, this also required that the original
  model had finished executing before bootstrapping. Rather than using nm_join()
  by default, we now use nm_data(.boot_run, filter = TRUE). This both fixes the
  aforementioned bug and removes the requirement that the base model (model being
  bootstrapped) has been executed. If the model has been executed, however, we will
  check the number of records to ensure the filtering was done correctly (#707, #711).

1.11.0

Release notes

New features and changes

• New bootstrap feature: bbr now supports the creation, management, and summary
  of bootstrap runs. Runs are initialized and set up using new_bootstrap_run()
  and setup_bootstrap_run(), respectively, and are tracked via the new
  bbi_nmboot_model type object. They can be submitted the same as any other
  model, after which they can be summarized via summarize_bootstrap_run() and
  "cleaned up" via cleanup_bootstrap_run(). (#671, #687, #701)

• New simulation feature: bbr now supports simple simulations. add_simuation()
  will create and submit a new bbi_nmsim_model object, which is then attached
  to the existing bbi_nonmem_model object. Additional new functions are also
  exported, including nm_join_sim(), which serves to join the simulation table
  to the input data. (#687)

• check_nonmem_finished() now returns FALSE if an output directory does not
  exist. (#693)

• New get_model_status() helper for returning messages that indicate which
  model(s) have finished executing and which are incomplete. (#671, #693)

• Add .delay argument to wait_for_nonmem() to account for variability in the
  amount of time required to wait before checking for the presence of an output
  directory (e.g., batch submissions). (#693)

• Removed parenthesis from THETA names in initial_estimates(). The intent
  was to match the output from param_estimates() so initial and final estimates
  could be joined more easily. (#674)

• Notable documentation improvements. (#671, #687)

1.10.0

Release notes

New features and changes

• When passed an nmbayes model (defined by the bbr.bayes package),
  nm_join() now gives a more informative error that points to
  bbr.bayes::nm_join_bayes(). (#662)

• check_nonmem_finished() has been converted to a method so that tailored
  logic can be implemented for derived model types, such as the nmbayes model
  type in bbr.bayes. (#663)

• The character methods for tail_lst() and tail_output() have been adjusted
  to work with custom model types where *.lst and OUTPUT files do not reside
  in the top-level output directory. (#661)

• get_data_path() can now pull from the control stream file if the model
  has not yet been submitted. This allows functions like nm_data() to be used
  pre-model submission. Support for bbi_log_df methods and a new
  .check_exists argument (defaults to TRUE) have also been added. (#664)

1.9.0

Release notes

New features and changes

• New initial_estimates() function for extracting and formatting initial
  parameter estimates from a NONMEM control stream file. (#646)

• New tweak_initial_estimates() function for tweaking or 'jittering' initial
  parameter estimates. Only $THETA records are supported for now. (#646)

Bugs addressed

• With the latest data.table release (1.15.0), param_estimates_batch()
  failed for an edge case due to a change in the header detection heuristics.
  param_estimates_batch() now tells data.table::fread() to expect a header.
  (#648)

• When passed .recurse = TRUE, run_log(), config_log(), and
  summary_log() included nested models, which was not by design. Any models
  under another model's output directory are considered an implementation
  detail. (#643, #644, #645)

1.8.1

Release notes

Bugs addressed

• inherit_param_estimates() calls model_summary() underneath and that failed
  when the parent model did not have .grd or .shk files. inherit_param_estimates()
  now has a .bbi_args argument (similar to nm_join()) that defaults to not
  looking for .shk and .grd files. (#638)

1.8.0

Release Notes

New features and changes

• New inherit_param_estimates() function for setting the initial parameter
  estimates of a model using the final estimates of a previously executed model.
  (#623)
• Improved documentation and vignettes. (#622, #627, #631)
• Some functions now rely on nmrec for parsing control stream files, rather
  than regex/string manipulation. (#600, #603, #604, #606, #612)
• nm_join now tracks the origin of each column and stores it as an attribute
  of the return value (mostly important for bbr.bayes). (#617)

Bugs addressed

• update_model_id would replace the id with the based_on field, which was a
  relative file path rather than a model id. In other words, this function did
  not support child models created in sub-directories (or otherwise a different
  directory than the parent model). (#614)
• delete_models() previously ran into issues when using R 4.0 and an older
  version of tibble. (#625)

1.7.0

Release Notes

Changes

All of the code changes in this release focus on enabling third-party packages to introduce new model types and were motivated by the soon-to-be-released bbr.bayes package. Aside from three new generics, these changes are internal and should not affect any user-facing behavior on the bbr side. (#543)

1.6.0

Release Notes

New features and changes

• New open_model_file() function opens the model definition file (the control stream for NONMEM models) in RStudio or any other editor supported by utils::file.edit(). (#570)

• The vignettes now include examples of calling run_log() with the .include argument (added in bbr 1.4.0). (#575)

• delete_models() messages have been improved. (#577)

• use_bbi() now allows a relative path and, on Windows, aborts if the path doesn't end with ".exe". (#579)

• bbr.bbi_exe_mode now defaults to "local" when not on Linux (where the default remains "sge"). (#580)

• Display a warning on Windows users if bbi version is below 3.2.2. (#581)

Bugs addressed

• Various updates for compatibility with tidyr 1.3.0 and dplyr 1.1.0 (#572, #578).

• model_summaries(), build_path_from_model(), and get_config_path() unintentionally signaled an error when the output directory of a model didn't exist. (#573)

• use_bbi() now does a better job of deciding when to message the user about further setup that's needed. (#579)

1.5.0

Release Notes

New features and changes

• submit_model() now has an .overwrite argument (similar to how new_model() and copy_model_from() have one). Previously, the user had to pass this through as .bbi_args = list(overwrite = TRUE) in order to overwrite output from a previous model execution. (#547)

• Functions run_log(), summary_log(), and config_log() all previously defaulted to searching for models recursively in sub-directories. This has been changed so that now users will need to pass .recurse = TRUE to search recursively. The primary reason for the change is user feedback indicating that, more often than not, sub-directories under a model directory contain something like a bootstrap, which would consist of a large number of models that shouldn't be included in the log table. Additionally, these sub-directories sometimes contain enough models (5000+) to make the *_log() call take quite some time to complete. (#492)

Bugs addressed

• Previously, nm_file() (and, as a result, functions like nm_join() and nm_tables() that use nm_file()) was upper-casing all columns in the table that was loaded. This was not part of the original specification and ended up causing problems with some users' downstream code, which expected the column names to remain intact. Going forward nm_file() does not modify any column names. (#564)

• Previously, a user could pass a directory path to use_bbi() and have the executable installed inside that directory. That behavior was undocumented and, more importantly, led to problems when the same directory path was set as options("bbr.bbi_exe_path"), because that option needs to contain a path to the actual executable. This was fixed so that now use_bbi() explicitly accepts only a path to the desired location of the executable, erroring if it receives a path to an existing directory instead. (#552)

• bbi 1.4.0 (specifically #514) made the change that users no longer have to specify parallel = TRUE to have submit_model() respect the number passed to threads. Unfortunately, it also introduced a bug where passing parallel = FALSE without passing threads causes an error. This has been corrected so that passing parallel = FALSE without passing threads will disable parallelization for that run. (#554)

1.4.0

Release Notes

New features and changes

• The new .include argument of config_log(), run_log(), and summary_log() limits the result to the specified run names or tags. (#484, #526)

• Models can now be starred. See add_star() and remove_star(). (#487)

• New convenience functions get_omega(), get_sigma(), and get_theta() return labeled values, with the OMEGA and SIGMA values expanded to a full matrix. (#515)

• param_estimates gained an .alpha argument that's useful for identifying the ETAs flagged by the eta_pval_significant heuristic. (#497)

• nm_join() now aborts if the join column has duplicate values, suggesting to the caller that the table format probably needs to be widened to prevent NONMEM from truncating the values. (#533)

• If the caller specifies a threads value above one in .bbi_args but does not specify parallel, parallel = TRUE is added so that the threads value is in effect. (#514)

• New functions check_nonmem_finished() and wait_for_nonmem() enable checking and waiting on models submitted to the grid. (#480)

• Added test_threads() for benchmarking simulation run times with various threads values. (#473, #489, #519, #542)

• Added check_run_times() for checking the estimation times of model runs. (#473, #489, #511)

• Added delete_models() for removing all model files associated with specified model tags. (#473)

• Updated parallel tips and tricks vignette to reference new test_threads() function and related helpers. (#503)

• bbi encodes "unspecified" and NA values as -999999999. bbr now maps all occurrences of this value to NA when creating a model summary object. (#524)

• When bbi v3.2.0 or later is available, model_summaries() now uses bbi's concurrency rather than calling model_summary() on each model, leading to a speed up when many models are passed. (#527)

• model_diff() learned to print a message rather than call diffobj::diffFile() when there are no changes to avoid confusingly displaying the entire file. (#522)

• use_bbi now creates leading directories if needed. (#499)

• new_model now ignores the extension of the supplied path. (#510)

• The output of print_bbi_args has been reworked to make it easier to digest. (#537)

Bug fixes

• nm_join() did not reliably sort the resulting data frame when passed .superset = TRUE. (#508)

• nm_file() and friends now detect duplicate column names and make them unique. (#530, #539)

• Unlike submit_model(), submit_models() didn't abort when bbi.yaml was missing. (#496)

• In combination with a change in bbi v3.2.0, model_summary() can now handle .lst files that have NaN objective function values. (#506)