Extract derived TK statistics from a fitted [pk()] model object.
# S3 method for pk
get_tkstats(
obj,
newdata = NULL,
tk_group = NULL,
model = NULL,
method = NULL,
exclude = TRUE,
vol_unit = "L",
dose_norm = TRUE,
suppress.messages = NULL,
...
)A data.frame with one row for each `data_group`, `model` and `method` with the variables in the `data.frame` 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`.)
A [pk()] model object. Must be fitted, or the function will exit with an error.
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`.
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.
Character: One or more of the models fitted. Default `NULL` to return TK stats for all models.
Character: One or more of the [optimx::optimx()] methods used. Default `NULL` to return TK stats for all methods.
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`.
Character: Specifies the unit of volume. Defaults to "L" for liters.
Logical: `TRUE` (default) specifies whether the concentrations are dose-normalized.
Logical: whether to suppress message printing. If NULL (default), uses the setting in `obj$settings_preprocess$suppress.messages`
Additional arguments not currently in use.
Caroline Ring, Gilberto Padilla Mercado
After fitting model parameters (e.g. elimination rate, volume of distribution, absorption rate, bioavailability), it can be useful to derive summary toxicokinetic statistics such as total clearance rate, half-life, peak concentration, AUC_inf (the area under the concentration-time curve when time goes to infinity), etc.
Many of these TK statistics depend not only on chemical and species, but also on route, media (tissue), and dose. Therefore, TK stats need to be computed for a specific set of Chemical, Species, Route, Media, and Dose.
TK statistics for a defined [pk_model()] object are computed using the function named in the model's `tkstats_fun`. For the built-in models, the `tkstats_fun` functions are the following. See the documentation for the individual functions for details on what TK stats are calculated for each model, and how they are calculated. -`model_1comp`: [tkstats_1comp()] -`model_2comp`: [tkstats_2comp()] -`model_flat`: [tkstats_flat()]
Other methods for fitted pk objects:
AAFE.pk(),
AFE.pk(),
AIC.pk(),
BIC.pk(),
coef.pk(),
coef_sd.pk(),
eval_tkstats.pk(),
get_fit.pk(),
get_hessian.pk(),
logLik.pk(),
predict.pk(),
residuals.pk(),
rmse.pk(),
rsq.pk()