nm_join_impl: Implementation function for 'nm_join()'

In metrumresearchgroup/bbr: R package for bbi

Implementation function for nm_join()

Description

Implementation function for nm_join()

Usage

nm_join_impl(
  .mod,
  .join_col = "NUM",
  .files = nm_table_files(.mod),
  .superset = FALSE,
  .bbi_args = list(no_grd_file = TRUE, no_shk_file = TRUE)
)

Arguments

.mod	A bbi_nonmem_model or bbi_nonmem_summary object, or a path to a NONMEM run.
.join_col	Character column name to use to join table files. Defaults to NUM. See Details.
.files	Character vector of file paths to table files to read in. Defaults to calling nm_table_files() on .mod, which will parse all file names from ⁠$TABLE⁠ blocks in the control stream. If passing manually, paths should be either absolute, or relative to get_output_dir(.mod).
.superset	If FALSE, the default, the data will be joined to the NONMEM output and if TRUE, the NONMEM output will be joined to the data; that is, if you use .superset, you will get the same number of rows as you have in the input data and NONMEM output columns like PRED and CWRES will be filled with NA.
.bbi_args	Named list passed to model_summary(.bbi_args). See print_bbi_args() for valid options. Defaults to list(no_grd_file = TRUE, no_shk_file = TRUE) because model_summary() is only called internally to extract the number of records and individuals, so those files are irrelevant.

Join column

The .join_col is the name of a single column that should appear in both the input data set and any tables you want to join. We recommend you make this column a simple integer numbering the rows in the input data set (for example NUM). When this column is carried into the output table files, there will be unambiguous matching from the table file back to the input data set.

• The one exception to this are FIRSTONLY tables. If a table file has the same number of rows as the there are individuals in the input data set (accounting for any filtering of data in the NONMEM control stream), it will assumed to be a FIRSTONLY table. In this case, the table will be joined to the input data by the ID column. If ID is not present in the table, it will be using .join_col. Note that if neither ID or the column passed to .join_col are present in the table, the join will fail.

Note also that, when .join_col is carried into table outputs, there is no need to table any other columns from the input data as long as the nm_join() approach is used; any column in the input data set, regardless of whether it is listed in ⁠$INPUT⁠ or not, will be carried through from the input data and therefore available in the joined result.

Duplicate Rows Warning for Join Column

If there are duplicate rows found in the specified .join_col, a warning will be raised specifying a subset of the repeated rows. Duplicates may be caused by lack of output width. FORMAT may be need to be stated in control stream to have sufficient width to avoid truncating .join_col.

Example: creating a row number .join_col

Take the following ⁠$INPUT⁠ and ⁠$DATA⁠ records:

$INPUT ID TIME MDV EVID DV AMT SEX WT ETN
$DATA ../../../../extdata/acop.csv

Before submitting a model, read in the data and add a row number column;

library(dplyr)
data <- nm_data(.mod) %>% mutate(NUM = 1:n())
readr::write_csv(data, get_data_path(.mod))

Then add 'NUM' to the list of input columns:

$INPUT ID TIME MDV EVID DV AMT SEX WT ETN *NUM*

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