eval_tkstats.pk {invivoPKfit}R Documentation

Evaluate TK statistics

Description

Evaluate TK statistics from a fitted model by comparing to NCA results

Usage

## S3 method for class 'pk'
eval_tkstats(
  obj,
  newdata = NULL,
  model = "winning",
  method = NULL,
  tk_group = NULL,
  exclude = TRUE,
  dose_norm = FALSE,
  finite_only = TRUE,
  suppress.messages = NULL,
  ...
)

Arguments

obj

A [pk()] model object. Must be fitted, or the function will exit with an error.

newdata

Optional: A 'data.frame' containing new data for which to compute the TK stats. Must contain at least variables 'Chemical', 'Species', 'Route', 'Media', 'Dose', 'Dose.Units', 'Conc.Units', either 'Time_trans.Units' or 'Time.Units', and any other variables named in 'tk_grouping'. Default 'NULL', to use the data in 'obj$data'.

model

Character: One or more of the models fitted. Default '"winning"' to return results for only the winning model(s). Supply 'NULL' to return TK stats for all models.

method

Character: One or more of the [optimx::optimx()] methods used. Default 'NULL' to return TK stats for all methods.

tk_group

A list of variables provided using a 'dplyr::vars()' call. The data (either 'newdata' or 'obj$data') will be grouped according to the unique combinations of these variables. For each unique combination of these variables in the data, a set of TK statistics will be computed. The default is 'obj$settings_data_info$summary_group', to derive TK statistics for the same groups of data as non-compartmental analysis statistics. With the default, you can directly compare e.g. a model-predicted AUC_inf to the corresponding NCA-estimated AUC_inf. However, you may specify a different data grouping if you wish. Each group should have a unique combination of 'Chemical', 'Species', 'Route', 'Media', and 'Dose', because the TK stats depend on these values, and it is required to have one unique set of TK stats per group.

exclude

Logical: 'TRUE' to get the TK groupings after removing any observations in the data marked for exclusion (if there is a variable 'exclude' in the data, an observation is marked for exclusion when 'TRUE'). 'FALSE' to include all observations when getting the TK groupings, regardless of exclusion status. Default 'TRUE'.

dose_norm

Logical: 'TRUE' (default) to dose-normalize before calculating both the NCA statistics and the fitted TK statistics (i.e. all dose-dependent statistics will be for a unit dose of 1 mg/kg, including Cmax, AUC, Css). 'FALSE' to calculate NCA and fitted TK stats separately for each dose group (you must specify 'Dose' as one of the variables in 'tk_group' for this to work). If 'dose_norm' is 'TRUE' and you also specify 'Dose' as one of the 'tk_group' variables, then the dose part of the grouping will be ignored in the output. (If 'TRUE', under the hood, this function will temporarily overwrite the 'Dose' column in its local copy of ‘newdata' with 1’s. This doesn't affect the data outside of this function. But it means that any values in the 'Dose' variable of 'newdata' will be ignored if 'TRUE'.)

finite_only

Logical: 'TRUE' (default) returns only rows (observations) for which AUC is finite in both 'nca' and 'tkstats'. This also means it will by default never return instances where winning model == 'model_flat'.

suppress.messages

Logical: whether to suppress message printing. If NULL (default), uses the setting in 'obj$settings_preprocess$suppress.messages'

...

Additional arguments. Currently not in use.

Value

A 'data.frame' with one row for each "winning" model in 'model' from [get_winning_model()]. The 'data.frame' will have the variables returned by the 'tkstats_fun' for its corresponding model. (For the built-in models 'model_flat', 'model_1comp', and 'model_2comp', these variables are 'param_name' and 'param_value'.) Additionally, there will be a variable 'method' denoting the [optimx::optimx()] method used to optimize the set of model parameters used to derive each set of TK statistics.

Author(s)

Caroline Ring, Gilberto Padilla Mercado, John Wambaugh

See Also

Other methods for fitted pk objects: AAFE.pk(), AFE.pk(), AIC.pk(), BIC.pk(), coef.pk(), coef_sd.pk(), get_fit.pk(), get_hessian.pk(), get_tkstats.pk(), logLik.pk(), predict.pk(), residuals.pk(), rmse.pk(), rsq.pk()


[Package invivoPKfit version 2.0.1 Index]