Type:	Package
Title:	Fits Toxicokinetic Models to In Vivo PK Data Sets
Version:	2.0.1
Date:	2025-3-24
Author:	John Wambaugh [aut, cre], Caroline Ring [aut], Gilberto Padilla Mercado [aut], Chris Cook [aut]
Maintainer:	John Wambaugh <wambaugh.john@epa.gov>
Description:	Takes in vivo toxicokinetic concentration-time data and fits parameters of 1-compartment and 2-compartment models for each chemical. These methods are described in detail in "Informatics for Toxicokinetics" (submitted).
License:	GPL-3
Depends:	R (≥ 4.1.0)
Imports:	cli, devtools, dplyr, ggplot2, glue, httk, magrittr, MASS, Matrix, multidplyr (≥ 0.1.3), numDeriv, optimx, PK, pracma, purrr, rlang, scales, tibble, tidyr, tidyselect
Suggests:	cowplot, knitr, RColorBrewer, rmarkdown, stringr, testthat (≥ 3.0.0), tidyverse
VignetteBuilder:	knitr
Config/testthat/edition:	3
Encoding:	UTF-8
LazyData:	TRUE
NeedsCompilation:	no
Packaged:	2025-03-24 14:45:51 UTC; GPADILLA
RoxygenNote:	7.3.2
Repository:	CRAN
Date/Publication:	2025-03-24 16:00:02 UTC

invivoPKfit: A package to fit model parameters to in vivo data

Description

The invivoPKfit package takes in vivo concentration-time data from TNO, RTI, and NHEERL, and fits parameters of 1-compartment and 2-compartment models for each chemical.

Author(s)

Maintainer: John Wambaugh wambaugh.john@epa.gov (ORCID)

Authors:

• Caroline Ring Ring.Caroline@epa.gov (ORCID)

• Gilberto Padilla Mercado (ORCID)

• Chris Cook

Add a 'pkproto' object to a 'pk' object

Description

Add a 'pkproto' object to a 'pk' object

Usage

## S3 method for class 'pk'
e1 + e2

Arguments

Details

Note that 'e1 + e2' is equivalent to

“' '+'(e1, e2) “'

Value

The 'pk' object, modified by adding the 'pkproto' object

Author(s)

Caroline Ring

Subtract a pkproto object from a pk object

Description

Subtract a pkproto object from a pk object

Usage

## S3 method for class 'pk'
e1 - e2

Arguments

Value

The pk object, modified by adding the pkproto object

Author(s)

Caroline Ring

AAFE()

Description

This is the S3 method generic for AAFE()

Usage

AAFE(obj, ...)

Arguments

Value

A dataframe with one row for each 'data_group', 'model' and 'method'. The final column contains the AAFE of the model fitted by the corresponding method, using the data in 'newdata'.

See Also

[AAFE.pk()] for the method for class [pk()]

Default method for AAFE()

Description

Default method for AAFE()

Usage

## Default S3 method:
AAFE(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Calculate absolute average fold error (AAFE)

Description

Calculate aboslute average fold error (AAFE)

Usage

## S3 method for class 'pk'
AAFE(
  obj,
  newdata = NULL,
  model = NULL,
  method = NULL,
  exclude = TRUE,
  use_scale_conc = FALSE,
  AAFE_group = NULL,
  sub_pLOQ = TRUE,
  ...
)

Arguments

Details

Absolute average fold error (AAFE) is calculated as

10^{\frac{1}{N}\sum{ \textrm{abs} \left[ log_{10} \left( \frac{\textrm{predicted}}{\textrm{observed}} \right) \right] } }

# Left-censored data

If the observed value is censored, and the predicted value is less than the reported LOQ, then the observed value is (temporarily) set equal to the predicted value, for an effective error of zero.

If the predicted value is less than the reported LOQ, then the user may choose whether to (temporarily) set the predicted value equal to LOQ, using argument 'sub_pLOQ').

Value

A dataframe with one row for each 'data_group', 'model' and 'method'. The final column contains the AAFE of the model fitted by the corresponding method, using the data in 'newdata'.

Author(s)

Caroline Ring

See Also

Other fit evaluation metrics: AFE.pk(), AIC.pk(), BIC.pk(), logLik.pk(), rmse.pk(), rsq.pk()

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

AFE()

Description

This is the S3 method generic for AFE()

Usage

AFE(obj, ...)

Arguments

Value

A dataframe with one row for each 'data_group', 'model' and 'method'. The final column contains the AFE of the model fitted by the corresponding method, using the data in 'newdata'.

See Also

[AFE.pk()] for the method for class [pk()]

Default method for AFE()

Description

Default method for AFE()

Usage

## Default S3 method:
AFE(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Calculate average fold error

Description

Calculate average fold error

Usage

## S3 method for class 'pk'
AFE(
  obj,
  newdata = NULL,
  model = NULL,
  method = NULL,
  exclude = TRUE,
  use_scale_conc = FALSE,
  AFE_group = NULL,
  sub_pLOQ = TRUE,
  ...
)

Arguments

Details

Average fold error is calculated as

10^{\frac{1}{N}\sum{log_{10} \left( \frac{\textrm{predicted}}{\textrm{observed}} \right)}}

# Left-censored data

If the observed value is censored, and the predicted value is less than the reported LOQ, then the observed value is (temporarily) set equal to the predicted value, for an effective error of zero.

If the predicted value is less than the reported LOQ, then the user may choose whether to (temporarily) set the predicted value equal to LOQ, using argument 'sub_pLOQ').

Value

A dataframe with one row for each 'data_group', 'model' and 'method'. The final column contains the AFE of the model fitted by the corresponding method, using the data in 'newdata'.

Author(s)

Caroline Ring

See Also

Other fit evaluation metrics: AAFE.pk(), AIC.pk(), BIC.pk(), logLik.pk(), rmse.pk(), rsq.pk()

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

Akaike information criterion

Description

Get the Akaike information criterion (AIC) for a fitted 'pk' object

Usage

## S3 method for class 'pk'
AIC(
  object,
  newdata = NULL,
  model = NULL,
  method = NULL,
  exclude = TRUE,
  drop_obs = TRUE,
  ...,
  k = 2
)

Arguments

Details

The AIC is calculated from the log-likelihood (LL) as follows:

\textrm{AIC} = -2\textrm{LL} + k n_{par}

where n_{par} is the number of parameters in the fitted model, and k = 2 for the standard AIC.

Value

A data.frame with log-likelihood values and calculated AIC using 'newdata'. There is one row for each model in ‘obj'’s [stat_model()] element and each [optimx::optimx()] method (specified in [settings_optimx()]).

Author(s)

Caroline Ring, Gilberto Padilla Mercado

See Also

Other fit evaluation metrics: AAFE.pk(), AFE.pk(), BIC.pk(), logLik.pk(), rmse.pk(), rsq.pk()

Other log likelihood functions: BIC.pk(), logLik.pk()

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

Bayesian information criterion

Description

Get the Bayesian information criterion (BIC) for a fitted 'pk' object

Usage

## S3 method for class 'pk'
BIC(object, newdata = NULL, model = NULL, method = NULL, exclude = TRUE, ...)

Arguments

Details

The BIC is calculated from the log-likelihood (LL) as follows:

\textrm{BIC} = -2\textrm{LL} + \log(n_{obs}) n_{par}

where n_{par} is the number of parameters in the fitted model.

Note that the BIC is just the AIC with k = \log(n_{obs}).

Value

A data.frame with log-likelihood values and calculated BIC using 'newdata'. There is one row for each model in ‘obj'’s [stat_model()] element and each [optimx::optimx()] method (specified in [settings_optimx()]).

Author(s)

Caroline Ring, Gilberto Padilla Mercado

See Also

Other fit evaluation metrics: AAFE.pk(), AFE.pk(), AIC.pk(), logLik.pk(), rmse.pk(), rsq.pk()

Other log likelihood functions: AIC.pk(), logLik.pk()

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

Add various 'pkproto' objects to a 'pk' object

Description

Add various 'pkproto' objects to a 'pk' object

Usage

add_pk(pk_obj, pkproto_obj, objectname)

Arguments

Value

The 'pk' object modified by the addition.

Analytic AUC for 1-compartment model

Description

Calculate area under the plasma concentration vs. time curve for the 1-compartment model, using an analytical equation (the integral of the 1-compartment model equation with respect to time).

Usage

auc_1comp(params, time, dose, route, medium)

Arguments

Details

# Required parameters

'params' must include the following named items:

kelim

Elimination rate, 1/time.

Vdist

Apparent volume of central compartment, volume/unit BW. Or see below for 'Fgutabs_Vdist'

For oral administration (if any 'route include:

Fgutabs

Oral bioavailability, unitless fraction. Or see below for 'Fgutabs_Vdist'

kgutabs

Rate of absorption from gut, 1/time.

For oral administration, in lieu of 'Vdist' and 'Fgutabs', you may instead provide 'Fgutabs_Vdist', the ratio of Fgutabs to Vdist (1/volume). This is an alternate parameterization for situations where 'Fgutabs' and 'Vdist' are not identifiable separately (i.e., when oral TK data are available, but IV data are not). If 'Fgutabs' and 'Vdist' are provided, they will override any value provided for 'Fgutabs_Vdist'.

If both oral and IV administration are specified (i.e., some 'route and some 'route 'Fgutabs' or 'Fgutabs_Vdist'. (If 'Vdist' and 'Fgutabs_Vdist' are provided, but 'Fgutabs' is not provided, then 'Fgutabs' will be calculated from 'Vdist' and 'Fgutabs_Vdist'.)

If 'any(medium 'Rblood2plasma', the ratio of chemical concentration in whole blood to the chemical concentration in blood plasma.

Value

A vector of plasma AUC values (concentration*time) corresponding to 'time'.

Author(s)

Caroline Ring, John Wambaugh

See Also

Other built-in model functions: auc_1comp_cl(), auc_2comp(), auc_flat(), cp_1comp(), cp_1comp_cl(), cp_2comp(), cp_2comp_dt(), cp_flat(), get_params_1comp(), get_params_1comp_cl(), get_params_1comp_fup(), get_params_2comp(), get_params_flat(), get_starts_1comp(), get_starts_1comp_cl(), get_starts_1comp_fup(), get_starts_2comp(), get_starts_flat(), tkstats_2comp(), transformed_params_2comp()

Other 1-compartment model functions: auc_1comp_cl(), cp_1comp(), cp_1comp_cl(), get_params_1comp(), get_params_1comp_cl(), get_params_1comp_fup(), get_starts_1comp(), get_starts_1comp_cl(), get_starts_1comp_fup()

Other model AUC functions: auc_1comp_cl(), auc_2comp(), auc_flat()

Analytic AUC for 1-compartment model with specific clearance

Description

Calculate area under the plasma concentration vs. time curve for the 1-compartment model, using an analytical equation (the integral of the 1-compartment model equation with respect to time).

Usage

auc_1comp_cl(params, time, dose, route, medium)

Arguments

Details

# Required parameters

'params' must include the following named items:

Fup

Fraction of compound unbound in plasma. Unitless.

Clint

Intrinsic clearance by hepatocytes. Units: 1/hr

Q_totli

Total blood flow through the liver. Units: L/h/kg body weight ^ (3/4)

Q_gfr

Glomerular filtration rate, how quickly do kidneys filter. Units: L/h/kg body weight ^ (3/4)

Vdist

Apparent volume of central compartment, volume/unit BW. Or see below for 'Fgutabs_Vdist'

For oral administration (if any 'route include:

Fgutabs

Oral bioavailability, unitless fraction. Or see below for 'Fgutabs_Vdist'

kgutabs

Rate of absorption from gut, 1/time.

For oral administration, in lieu of 'Vdist' and 'Fgutabs', you may instead provide 'Fgutabs_Vdist', the ratio of Fgutabs to Vdist (1/volume). This is an alternate parameterization for situations where 'Fgutabs' and 'Vdist' are not identifiable separately (i.e., when oral TK data are available, but IV data are not). If 'Fgutabs' and 'Vdist' are provided, they will override any value provided for 'Fgutabs_Vdist'.

If both oral and IV administration are specified (i.e., some 'route and some 'route 'Fgutabs' or 'Fgutabs_Vdist'. (If 'Vdist' and 'Fgutabs_Vdist' are provided, but 'Fgutabs' is not provided, then 'Fgutabs' will be calculated from 'Vdist' and 'Fgutabs_Vdist'.)

If 'any(medium 'Rblood2plasma', the ratio of chemical concentration in whole blood to the chemical concentration in blood plasma.

Value

A vector of plasma AUC values (concentration*time) corresponding to 'time'.

Author(s)

Caroline Ring, John Wambaugh

See Also

Other built-in model functions: auc_1comp(), auc_2comp(), auc_flat(), cp_1comp(), cp_1comp_cl(), cp_2comp(), cp_2comp_dt(), cp_flat(), get_params_1comp(), get_params_1comp_cl(), get_params_1comp_fup(), get_params_2comp(), get_params_flat(), get_starts_1comp(), get_starts_1comp_cl(), get_starts_1comp_fup(), get_starts_2comp(), get_starts_flat(), tkstats_2comp(), transformed_params_2comp()

Other 1-compartment model functions: auc_1comp(), cp_1comp(), cp_1comp_cl(), get_params_1comp(), get_params_1comp_cl(), get_params_1comp_fup(), get_starts_1comp(), get_starts_1comp_cl(), get_starts_1comp_fup()

Other model AUC functions: auc_1comp(), auc_2comp(), auc_flat()

Analytical AUC for the 2-compartment model

Description

Calculate area under the plasma concentration vs. time curve for the 1-compartment model, using an analytical equation (the integral of the 1-compartment model equation with respect to time).

Usage

auc_2comp(params, time, dose, route, medium = "plasma")

Arguments

Value

A vector of plasma AUC values, evaluated at each time point in time.

Author(s)

Caroline Ring, John Wambaugh

See Also

Other built-in model functions: auc_1comp(), auc_1comp_cl(), auc_flat(), cp_1comp(), cp_1comp_cl(), cp_2comp(), cp_2comp_dt(), cp_flat(), get_params_1comp(), get_params_1comp_cl(), get_params_1comp_fup(), get_params_2comp(), get_params_flat(), get_starts_1comp(), get_starts_1comp_cl(), get_starts_1comp_fup(), get_starts_2comp(), get_starts_flat(), tkstats_2comp(), transformed_params_2comp()

Other 2-compartment model functions: cp_2comp(), cp_2comp_dt(), get_params_2comp(), get_starts_2comp(), tkstats_2comp(), transformed_params_2comp()

Other model AUC functions: auc_1comp(), auc_1comp_cl(), auc_flat()

AUC for flat model

Description

Evaluates the area under the concentration-time curve for a "flat" model

Usage

auc_flat(time, params, dose, route, medium)

Arguments

Details

# Required parameters

'params' must include the following named items:

Vdist

Apparent volume of central compartment, L/kg BW. Or see below for 'Fgutabs_Vdist'

For oral administration (if any 'route include:

Fgutabs

Oral bioavailability, unitless fraction. Or see below for 'Fgutabs_Vdist'

For oral administration, in lieu of 'Vdist' and 'Fgutabs', you may instead provide 'Fgutabs_Vdist', the ratio of Fgutabs to Vdist (1/L). This is an alternate parameterization for situations where 'Fgutabs' and 'Vdist' are not identifiable separately (i.e., when oral TK data are available, but IV data are not). If 'Fgutabs' and 'Vdist' are provided, they will override any value provided for 'Fgutabs_Vdist'.

If both oral and IV administration are specified (i.e., some 'route and some 'route 'Fgutabs' or 'Fgutabs_Vdist'. (If 'Vdist' and 'Fgutabs_Vdist' are provided, but 'Fgutabs' is not provided, then 'Fgutabs' will be calculated from 'Vdist' and 'Fgutabs_Vdist'.)

If 'any(medium 'Rblood2plasma', the ratio of chemical concentration in whole blood to the chemical concentration in blood plasma.

Value

A vector of plasma concentration values (mg/L) corresponding to time.

Author(s)

Caroline Ring, John Wambaugh, Chris Cook

See Also

Other built-in model functions: auc_1comp(), auc_1comp_cl(), auc_2comp(), cp_1comp(), cp_1comp_cl(), cp_2comp(), cp_2comp_dt(), cp_flat(), get_params_1comp(), get_params_1comp_cl(), get_params_1comp_fup(), get_params_2comp(), get_params_flat(), get_starts_1comp(), get_starts_1comp_cl(), get_starts_1comp_fup(), get_starts_2comp(), get_starts_flat(), tkstats_2comp(), transformed_params_2comp()

Other flat model functions: cp_flat(), get_params_flat(), get_starts_flat()

Other model AUC functions: auc_1comp(), auc_1comp_cl(), auc_2comp()

Automatically select new time units

Description

Given a vector of time values in original units, this function selects new time units such that, when time is rescaled to the new units, the midpoint of the time vector is as close to 10 as possible.

Usage

auto_units(y, from, target = 10, period_units = time_units)

Arguments

Details

# Acceptable/understood time units in 'period_units'

“' c("picoseconds", "nanoseconds", "microseconds", "milliseconds", "seconds", "minutes", "hours", "days", "weeks", "months", "years") “'

Value

Character: Automatically-selected new time units, which will be one of 'period_units'.

Author(s)

Caroline Ring

Calculate Hessian

Description

Calculate Hessian matrix given parameter values and data

Usage

calc_hessian(
  pars_opt,
  pars_const,
  observations,
  modelfun,
  dose_norm,
  log10_trans
)

Arguments

Details

Calculate the Hessian matrix: the matrix of second derivatives of the objective function with respect to parameters, evaluated for a single set of parameter values for a single model and a single data set. Here, the objective function is the negative log-likelihood implemented in [log_likelihood()], evaluated jointly across the data that was used to fit the model. This is a workhorse function called by [get_hessian.pk()] and, indirectly, by [coef_sd.pk()]. When the number of optimized parameters is n, the respective Hessian matrix will be n \times n.

Value

A square numeric matrix, both dimensions the same as the length of 'pars_opt'. It will have rownames and column names that are the same as the names of 'pars_opt'.

Author(s)

Caroline Ring

Non-compartmental analysis

Description

Do non-compartmental analysis on a single-dose set of concentration vs. time data

Usage

calc_nca(time, conc, detect, series_id = NULL, dose, route, method = "z", ...)

Arguments

Details

This function is a wrapper around [PK::nca()] to do non-compartmental analysis, after automatically detecting the study design. It additionally calls [get_peak()] to calculate the peak concentration and time of peak concentration.

# Automatic detection of study design

[PK::nca()] understands three different study designs, and requires the user to specify which one is being used.

- 'ssd': Serial sampling design. Each observation is from a different subject. - 'complete': Every subject was observed at every time point. - 'batch': Each subject was observed at multiple time points, but not at every time point.

To automatically detect which study design is applicable, this function first sorts the data by increasing time. Then, a table of time vs. series ID is created, with 1 indicating that a measurement exists for the corresponding time point/series ID combination, and 0 indicating that a measurement does not exist. If the column sums of this table are all 1, then it is a serial sampling design, except if there is only one observation per time point, it is a complete sampling design, and if there are multiple observations for some time points and only one observation for other time points, it is a batch design. If the column sums are all equal to the number of rows of the table, then it is a complete sampling design. Otherwise, it is a batch sampling design.

# Parameters estimated by NCA

- 'AUC_infinity': The area under the concentration-time curve, extrapolated out to infinite time. Estimated using the trapezoidal rule, with a tail area correction calculated using the slope of the last 3 data points (by default). - 'AUC_tlast': The area under the concentration-time curve, calculated at the last observed time point. Estimated using the trapezoidal rule. - 'AUMC_infinity': The area under the concentration-time first moment curve (the area under the AUC vs. time), extrapolated out to infinite time. Estimated using the trapezoidal rule, with a tail area correction calculated using the slope of the last 3 data points (by default). - ‘CLtot': The total clearance rate. Only calculated for 'route == ’iv'‘. If 'route == ’oral'', this is 'NA_real_', and only 'CLtot/Fgutabs' is calculated. - ‘CLtot/Fgutabs': The total clearance rate, normalized by the oral bioavailability. Only calculated for 'route == ’oral'‘. If 'route == ’iv'', this is 'NA_real_', and only 'CLtot/' is calculated. - ‘Cmax': The peak concentration. For 'route == ’iv'‘, this is expected to be the concentration at the earliest time; for 'route == ’oral'', it is not. This and 'tmax' are calculated using [get_peak()], not by [PK::nca()]. - ‘halflife': The half-life of elimination. Only calculated for 'route == ’iv'‘. If 'route == ’oral'', this is 'NA_real_', because half-life estimates are not valid for oral data. - ‘MRT': The mean residence time. Only calculated for 'route == ’iv'‘. If 'route == ’oral'', this is 'NA_real_', and only 'MTT' is calculated. - ‘MTT': The mean transit time (the sum of MRT and mean absorption time). Only calculated for 'route == ’oral'‘. If 'route == ’iv'', this is 'NA_real_', and only 'MRT' is calculated. -‘tmax': The time of peak concentration. For 'route == ’iv'‘, this is expected to be the earliest time; for 'route == ’oral'', it is not. This and 'Cmax' are calculated using [get_peak()], not by [PK::nca()]. - ‘Vss': The volume of distribution at steady state ('AUMC_infinity/AUC_infinity^2'). If 'route == ’oral'', this is 'NA_real_', because 'Vss' estimates are not valid for oral data.

# Output

The output is a data.frame with 9 rows (one for each NCA parameter) and a number of variables equal to 'length(method) + 3'.

The variables are

- 'design': The automatically-detected design. One of 'ssd', 'complete', or 'batch' (or 'NA_character_' if no analysis could be done). - 'param_name': The name of each NCA parameter. - 'param_value': The value of each NCA parameter. - 'param_sd_[method]': The parameter standard error estimated by the corresponding method.

Value

A 'data.frame' with 9 rows and 'length(method) + 3' variables. See Details.

Author(s)

Caroline Ring

Calculate RMSE (root mean squared error)

Description

Calculate RMSE when observed data may be left-censored (non-detect) or may be reported in summary form (as sample mean, sample standard deviation, and sample number of subjects). Additionally, handle the situation when observed data and predictions need to be log10-transformed before RMSE is calculated.

Usage

calc_rmse(pred, obs, obs_sd, n_subj, detect, log10_trans = FALSE)

Arguments

Details

RMSE is calculated using the following formula, to properly handle summary data:

\sqrt{ \frac{1}{N} \sum_{i=1}^G \left( (n_i - 1) s_i^2 + n_i \bar{y}_i^2 - 2 n_i \bar{y}_i \mu_i + \mu_i^2 \right) }

In this formula, there are G groups. (For CvTdb data, a "group" is a specific combination of chemical, species, route, medium, dose, and timepoint.) n_i is the number of subjects for group i. \bar{y}_i is the sample mean for group i. s_i is the sample standard deviation for group i.\mu_i is the model-predicted value for group i.

N is the grand total of subjects:

N = \sum_{i=1}^G n_i

For the non-summary case (N single-subject observations, with all n_i = 1, s_i = 0, and \bar{y}_i = y_i), this formula reduces to the familiar RMSE formula

\sqrt{\frac{1}{N} \sum_{i=1}^N (y_i - \mu_i)^2}

# Left-censored data

If the observed value is censored, and the predicted value is less than the reported LOQ, then the observed value is (temporarily) set equal to the predicted value, for an effective error of zero.

If the observed value is censored, and the predicted value is greater than the reported LOQ, the the observed value is set equal to the reported LOQ.

# Log10 transformation

If 'log10_trans log10-transformed before calculating the RMSE. In the case where observed values are reported in summary format, each sample mean and sample SD (reported on the natural scale, i.e. the mean and SD of natural-scale individual observations) are used to produce an estimate of the log10-scale sample mean and sample SD (i.e., the mean and SD of log10-transformed individual observations), using [convert_summary_to_log10()].

The formulas are as follows. Again, \bar{y}_i is the sample mean for group i. s_i is the sample standard deviation for group i.

\textrm{log10-scale sample mean}_i = \log_{10} \left(\frac{\bar{y}_i^2}{\sqrt{\bar{y}_i^2 + s_i^2}} \right)

\textrm{log10-scale sample SD}_i = \sqrt{\log_{10} \left(1 + \frac{s_i^2}{\bar{y}_i^2} \right)}

Value

A numeric scalar: the root mean squared error (RMSE) for this set of observations and predictions.

Author(s)

Caroline Ring

Calculate r-squared for observed vs. predicted values

Description

Calculate the square of the Pearson correlation coefficient (r) between observed and model-predicted values

Usage

calc_rsq(pred, obs, obs_sd, n_subj, detect, log10_trans = FALSE)

Arguments

Details

Calculate the square of the Pearson correlation coefficient (r) between observed and model-predicted values, when observed data may be left-censored (non-detect) or may be reported in summary form (as sample mean, sample standard deviation, and sample number of subjects). Additionally, handle the situation when observed data and predictions need to be log-transformed before RMSE is calculated.

r^2 is calculated according to the following formula, to properly handle observations reported in summary format:

r^2 = \left( \frac{ \sum_{i=1}^G \mu_i n_i \bar{y}_i - (\bar{\mu} + \bar{y}) \sum_{i=1}^G n_i \mu_i + (\bar{\mu} \bar{y}) \sum_{i=1}^G n_i } { \sqrt{ \sum_{i=1}^G (n_i - 1) s_i^2 + \sum_{i=1}^G n_i \bar{y}_i^2 - 2 \bar{y} \sum_{i=1}^G n_i \bar{y}_i + N + \bar{y}^2 } \sqrt{ \sum_{i=1}^G n_i \mu_i^2 - 2 \bar{y} \sum_{i=1}^G n_i \mu_i + N + \bar{y}^2 } } \right)^2

In this formula, there are G groups (reported observations). (For CvTdb data, a "group" is a specific combination of chemical, species, route, medium, dose, and timepoint.) n_i is the number of subjects for group i. \bar{y}_i is the sample mean for group i. s_i is the sample standard deviation for group i.\mu_i is the model-predicted value for group i. \bar{y} is the grand mean of observations:

\bar{y} = \frac{ \sum_{i=1}^G n_i \bar{y}_i }{\sum_{i=1}^G n_i}

\bar{\mu} is the grand mean of predictions:

\bar{\mu} = \frac{ \sum_{i=1}^G n_i \mu_i }{\sum_{i=1}^G n_i}

N is the grand total of subjects:

N = \sum_{i=1}^G n_i

For the non-summary case (N single-subject observations, with all n_i = 1, s_i = 0, and \bar{y}_i = y_i), this formula reduces to the familiar formula

r^2 = \left( \frac{\sum_{i=1}^N (y_i - \bar{y}) (\mu_i - \bar{\mu})} {\sqrt{ \sum_{i=1}^N (y_i - \bar{y})^2 } \sqrt{ \sum_{i=1}^N (\mu_i - \bar{\mu})^2 } } \right)^2

# Left-censored data

If the observed value is censored, and the predicted value is less than the reported LOQ, then the observed value is (temporarily) set equal to the predicted value, for an effective error of zero.

If the observed value is censored, and the predicted value is greater than the reported LOQ, the the observed value is (temporarily) set equal to the reported LOQ, for an effective error of (LOQ - predicted).

# Log-10 transformation

If 'log10 log10-transformed before calculating the RMSE. In the case where observed values are reported in summary format, each sample mean and sample SD (reported on the natural scale, i.e. the mean and SD of natural-scale individual observations) are used to produce an estimate of the log10-scale sample mean and sample SD (i.e., the mean and SD of log10-transformed individual observations), using [convert_summary_to_log10()].

The formulas are as follows. Again, \bar{y}_i is the sample mean for group i. s_i is the sample standard deviation for group i.

\textrm{log10-scale sample mean}_i = \log_{10} \left(\frac{\bar{y}_i^2}{\sqrt{\bar{y}_i^2 + s_i^2}} \right)

\textrm{log10-scale sample SD}_i = \sqrt{\log_{10} \left(1 + \frac{s_i^2}{\bar{y}_i^2} \right)}

Value

A numeric scalar: the R-squared value for observations vs. predictions.

Author(s)

Caroline Ring

Calculate parameter SDs

Description

Calculate parameter SDs using inverse Hessian

Usage

calc_sds_alerts(
  pars_opt,
  pars_const,
  observations,
  modelfun,
  dose_norm,
  log10_trans
)

Arguments

Details

Calculate parameter SDs using inverse Hessian approach for a single set of parameter values for a single model and a single data set.

This is a workhorse function called by [coef_sd.pk()]. If the length of this vector is n, the Hessian matrix will be n \times n.

The coefficient standard deviations are estimated by computing a numerical approximation to the model Hessian (the matrix of second derivatives of the model objective function with respect to each model parameter) and then attempting to invert it. This procedure yields a variance/covariance matrix for the model parameters. The square root of the diagonal elements of this matrix represent the parameter standard deviations.

A first attempt is made to invert the Hessian using [solve()] (see [hess_sd1()]). If the Hessian is singular, an attempt is made to calculate a pseudovariance matrix, following the procedure outlined in Gill & King (2004) (see [hess_sd2()]). First, the generalized inverse of the Hessian is calculated using [MASS::ginv()]. Then, a generalized Cholesky decomposition (to ensure positive-definiteness) is calculated using [Matrix::Cholesky] with argument 'perm = TRUE'. The generalized inverse is reconstructed from the generalized Cholesky factorization. The square root of the diagonal elements of this matrix represent the parameter standard deviations.

If neither of these procedures is successful, then 'NA_real_' is returned for all coefficient standard deviations. Record any error messages encountered during the process, and note which method was used to produce the final results. This is a workhorse function called by [coef_sd.pk()].

Value

A data.frame with variables 'param_name', 'param_sd', and 'sd_alert', and as many rows as the length of 'pars_opt'. 'param_name' contains the names of 'pars_opt'. 'param_sd' contains the parameter standard deviations calculated using the inverse Hessian. 'sd_alerts' is a character variable noting any errors encountered while attempting to calculate the parameter SDs.

Author(s)

Caroline Ring

References

Gill J, King G. (2004) What to Do When Your Hessian is Not Invertible: Alternatives to Model Respecification in Nonlinear Estimation. Sociological Methods & Research 33(1):54-87. DOI: 10.1177/0049124103262681

Check methods

Description

Check methods for validity

Usage

check_method(obj, method)

Arguments

Details

Helper function to ensure that a list of methods specified by the user matches the methods available in the fitted [pk()] object.

Value

'TRUE' if all 'method

Author(s)

Caroline Ring

Check models

Description

Check models for validity

Usage

check_model(obj, model)

Arguments

Details

Helper function to ensure that a list of models specified by the user matches the models available in the fitted [pk()] object.

Value

'TRUE' if all 'model

Author(s)

Caroline Ring

Check new data

Description

Check new data to ensure it has the required variables and classes

Usage

check_newdata(newdata, olddata, req_vars, exclude = FALSE)

Arguments

Details

This is a helper function to check new data to ensure it has the required variables and that those variables are of the correct classes. This is useful, for example, when making predictions from a fitted [pk()] model object on new data.

Value

'TRUE', if required variables are present in 'newdata', and required variables are of the same class in 'newdata' and 'olddata'. Otherwise, this function will stop with an error.

Author(s)

Caroline Ring

Check 1-compartment model parameters

Description

Check to make sure required parameters are present to evaluate 1-compartment model for a given route and medium

Usage

check_params_1comp(params, route, medium, ...)

Arguments

Value

Character: A message. If all required parameters are present for the given media & routes, the message is "Parameters OK". If required parameters for the oral route are missing, the message is "Error: For 1-compartment oral model, missing parameters (comma-separated list of parameter names)". If required parameters for the IV route are missing, the message is "Error: For 1-compartment oral model, missing parameters (comma-separated list of parameter names)".

Author(s)

Caroline Ring

Check 1-compartment model parameters

Description

Check to make sure required parameters are present to evaluate 1-compartment model for a given route and medium

Usage

check_params_1comp_cl(params, route, medium, ...)

Arguments

Value

Character: A message. If all required parameters are present for the given media & routes, the message is "Parameters OK". If required parameters for the oral route are missing, the message is "Error: For 1-compartment oral model, missing parameters (comma-separated list of parameter names)". If required parameters for the IV route are missing, the message is "Error: For 1-compartment oral model, missing parameters (comma-separated list of parameter names)".

Author(s)

Caroline Ring

Check 2-compartment model parameters

Description

Check to make sure required parameters are present to evaluate 2-compartment model for a given route and medium

Usage

check_params_2comp(params, route, medium, ...)

Arguments

Value

Character: A message. If all required parameters are present for the given media & routes, the message is "Parameters OK". If required parameters for the oral route are missing, the message is "Error: For 2-compartment oral model, missing parameters (comma-separated list of parameter names)". If required parameters for the IV route are missing, the message is "Error: For 2-compartment oral model, missing parameters (comma-separated list of parameter names)".

Author(s)

Caroline Ring

Check flat model parameters

Description

Check to make sure required parameters are present to evaluate flat model for a given route and medium

Usage

check_params_flat(params, route, medium, ...)

Arguments

Value

Character: A message. If all required parameters are present for the given media & routes, the message is "Parameters OK". If required parameters for the oral route are missing, the message is "Error: For flat oral model, missing parameters (comma-separated list of parameter names)". If required parameters for the IV route are missing, the message is "Error: For flat oral model, missing parameters (comma-separated list of parameter names)".

Author(s)

Caroline Ring

Check required status

Description

This is the S3 method generic.

Usage

check_required_status(obj, ...)

Arguments

Value

If the [pk()] object has the required status or greater, returns TRUE. If the [pk()] object has less than the required status, returns FALSE. Returned value has an attribute 'msg', containing an informative message as a string.

See Also

[check_required_status.pk()] for the method for class [pk()]

Default method for checking required status

Description

Default method for checking required status

Usage

## Default S3 method:
check_required_status(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Check required status

Description

Check whether a [pk()] object has a particular required status level

Usage

## S3 method for class 'pk'
check_required_status(obj, required_status, ...)

Arguments

Details

This is a helper function to check whether a [pk()] object has the status required for certain operations. For example, status 4 (fitting complete) is required for any fit evaluation functions: [predict.pk()], [residuals.pk()], [coef.pk()], [coef_sd.pk()], [rmse.pk()], [fold_error.pk()]

Value

If the [pk()] object has the required status or greater, returns TRUE. If the [pk()] object has less than the required status, returns FALSE. Returned value has an attribute 'msg', containing an informative message as a string.

Author(s)

Caroline Ring

Get coefficients

Description

Extract coefficients from a fitted [pk()] object

Usage

## S3 method for class 'pk'
coef(
  object,
  model = NULL,
  method = NULL,
  drop_sigma = FALSE,
  include_NAs = FALSE,
  include_type = "use",
  suppress.messages = NULL,
  ...
)

Arguments

Details

This function extracts fitted model parameter values from a fitted [pk()] object.

Value

A data.frame with a row for each 'data_group' x 'method' x 'model' combination in a fitted [pk()] object. When 'drop_sigma = TRUE' there is also a row for each unique standard deviation hyper-parameter defined by 'error_group' in the fitted [pk()] object. There is a column for all parameter estimates given each model in 'model'. A list-column 'coefs_vector' summarizes all estimated parameters into a named vector. This named vector is used in functions that call upon the model functions, such as [predict()].

Author(s)

Caroline Ring, Gilberto Padilla Mercado

See Also

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

Coefficient standard deviations

Description

This is the S3 method generic for 'coef_sd'.

Usage

coef_sd(obj, model, method, suppress.messages, ...)

Arguments

Value

A dataframe with one row for each 'data_group', 'model' and 'method'. The remaining columns include the parameters & hyperparameters as returned by [coef.pk()], as well as their calculated standard deviations.

See Also

[coef_sd.pk()] for the 'coef_sd' method for class [pk()]

Coefficient standard deviation default

Description

Coefficient standard deviation default

Usage

## Default S3 method:
coef_sd(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Get coefficient standard deviations

Description

Extract coefficient/parameter standard deviations from a fitted 'pk' object

Usage

## S3 method for class 'pk'
coef_sd(obj, model = NULL, method = NULL, suppress.messages = TRUE, ...)

Arguments

Details

The coefficient standard deviations are estimated by computing a numerical approximation to the model Hessian (the matrix of second derivatives of the model objective function with respect to each model parameter) and then attempting to invert it. This procedure yields a variance/covariance matrix for the model parameters. The square root of the diagonal elements of this matrix represent the parameter standard deviations.

A first attempt is made to invert the Hessian using [solve()] (see [hess_sd1()]). If the Hessian is singular, an attempt is made to calculate a pseudovariance matrix, following the procedure outlined in Gill & King (2004) (see [hess_sd2()]). First, the generalized inverse of the Hessian is calculated using [MASS::ginv()]. Then, a generalized Cholesky decomposition (to ensure positive-definiteness) is calculated using [Matrix::Cholesky] with argument 'perm = TRUE'. The generalized inverse is reconstructed from the generalized Cholesky factorization. The square root of the diagonal elements of this matrix represent the parameter standard deviations.

If neither of these procedures is successful, then 'NA_real_' is returned for all coefficient standard deviations.

Value

A dataframe with one row for each 'data_group', 'model' and 'method'. The remaining columns include the parameters & hyperparameters as returned by [coef.pk()], as well as their calculated standard deviations.

Author(s)

Caroline Ring and Gilberto Padilla Mercado

References

Gill J, King G. (2004) What to Do When Your Hessian is Not Invertible: Alternatives to Model Respecification in Nonlinear Estimation. Sociological Methods & Research 33(1):54-87. DOI: 10.1177/0049124103262681

See Also

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

Combined standard deviation

Description

Given mean, standard deviation, and N for some set of groups, calculate the combined standard deviation. Note that the groups may not overlap.

Usage

combined_sd(
  group_mean,
  group_sd,
  group_n,
  unbiased = TRUE,
  na.rm = TRUE,
  log10 = FALSE
)

Arguments

Value

Numeric: the standard deviation of the combined population (i.e. if all the groups were concatenated into one large group).

Author(s)

Caroline Ring

Model comparison

Description

This is the S3 method generic for compare_models()

Usage

compare_models(obj, ...)

Arguments

Value

A 'data.frame' with variables - 'model': The name of each model - 'method': The name of each method - A variable named for 'criterion' (e.g. if 'criterion = "AIC"' then the result will have a variable named 'AIC'): The criterion value for each model/method

See Also

[compare_models.pk()] for the method for class [pk()]

Default method for compare_models()

Description

Default method for compare_models()

Usage

## Default S3 method:
compare_models(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Model comparison for [pk()] objects

Description

Perform model comparison for a fitted [pk()] object.

Usage

## S3 method for class 'pk'
compare_models(
  obj,
  newdata = NULL,
  model = NULL,
  method = NULL,
  criterion = "AIC",
  ...
)

Arguments

Details

Models are compared according to the goodness-of-fit criterion named in "criterion", and the name of the winning model is returned.

Value

A 'data.frame' with variables - 'model': The name of each model - 'method': The name of each method - A variable named for 'criterion' (e.g. if 'criterion = "AIC"' then the result will have a variable named 'AIC'): The criterion value for each model/method

Author(s)

Caroline Ring

Get concentration scalings

Description

A helper function to get concentration scalings

Usage

conc_scale_use(use_scale_conc, obj)

Arguments

Details

In methods applied to fitted [pk()] objects that also accept 'newdata' arguments, the user may specify whether to use the concentration scaling of the fitted [pk()] object, or use a different concentration scaling. This is done by specifying an argument 'use_scale_conc', which may be 'TRUE' (to use the scaling from the fitted object), 'FALSE' (to use no scaling), or may be a named list with elements 'dose_norm' and 'log10_trans' to specify scaling/transformation directly. This helper function parses the 'use_scale_conc' argument.

Value

A named list with elements 'dose_norm' and 'log10_trans', both logical.

Convert sample mean and SD to log10-scale

Description

Estimate log10-scale sample mean and standard deviation from natural-scale sample mean and standard deviation

Usage

convert_summary_to_log10(sample_mean, sample_SD)

Arguments

Details

\bar{y}_i is the natural-scale sample mean for group i. s_i is the natural-scale sample standard deviation for group i.

\textrm{log10-scale sample mean}_i = \log_{10} \left(\frac{\bar{y}_i^2}{\sqrt{\bar{y}_i^2 + s_i^2}} \right)

\textrm{log10-scale sample SD}_i = \sqrt{ \log_{10} \left(1 + \frac{s_i^2}{\bar{y}_i^2} \right) }

Value

A list with two named elements: "log10mean" and "log10SD", the log10-scale sample means and log10-scale sample SDs, respectively.

Author(s)

Caroline Ring

Helper function to convert time units

Description

Convert a vector of times between units

Usage

convert_time(x, from = "hours", to = "identity", inverse = FALSE)

Arguments

Value

A numeric vector the same length as 'x', converted from the units in 'from' to the units in 'to'.

Author(s)

Caroline Ring, Gilberto Padilla Mercado

Analytical 1-compartment model

Description

Calculates plasma concentrations vs. time according to the analytical solution for the 1-compartment model, for single bolus doses (IV and/or oral).

Usage

cp_1comp(params, time, dose, route, medium = "plasma")

Arguments

Details

# Required parameters

'params' must include the following named items:

kelim

Elimination rate, 1/time.

Vdist

Apparent volume of central compartment, volume/unit BW. Or see below for 'Fgutabs_Vdist'

For oral administration (if any 'route include:

Fgutabs

Oral bioavailability, unitless fraction. Or see below for 'Fgutabs_Vdist'

kgutabs

Rate of absorption from gut, 1/time.

For oral administration, in lieu of 'Vdist' and 'Fgutabs', you may instead provide 'Fgutabs_Vdist', the ratio of Fgutabs to Vdist (1/volume). This is an alternate parameterization for situations where 'Fgutabs' and 'Vdist' are not identifiable separately (i.e., when oral TK data are available, but IV data are not). If 'Fgutabs' and 'Vdist' are provided, they will override any value provided for 'Fgutabs_Vdist'.

If both oral and IV administration are specified (i.e., some 'route and some 'route 'Fgutabs' or 'Fgutabs_Vdist'. (If 'Vdist' and 'Fgutabs_Vdist' are provided, but 'Fgutabs' is not provided, then 'Fgutabs' will be calculated from 'Vdist' and 'Fgutabs_Vdist'.)

If 'any(medium 'Rblood2plasma', the ratio of chemical concentration in whole blood to the chemical concentration in blood plasma.

Value

A vector of blood or plasma concentration values corresponding to 'time'.

Author(s)

Caroline Ring, John Wambaugh

See Also

Other built-in model functions: auc_1comp(), auc_1comp_cl(), auc_2comp(), auc_flat(), cp_1comp_cl(), cp_2comp(), cp_2comp_dt(), cp_flat(), get_params_1comp(), get_params_1comp_cl(), get_params_1comp_fup(), get_params_2comp(), get_params_flat(), get_starts_1comp(), get_starts_1comp_cl(), get_starts_1comp_fup(), get_starts_2comp(), get_starts_flat(), tkstats_2comp(), transformed_params_2comp()

Other 1-compartment model functions: auc_1comp(), auc_1comp_cl(), cp_1comp_cl(), get_params_1comp(), get_params_1comp_cl(), get_params_1comp_fup(), get_starts_1comp(), get_starts_1comp_cl(), get_starts_1comp_fup()

Other model concentration functions: cp_1comp_cl(), cp_2comp(), cp_flat()

Analytical 1-compartment model with specific clearance

Description

Calculates plasma concentrations vs. time according to the analytical solution for the 1-compartment model, for single bolus doses (IV and/or oral).

Usage

cp_1comp_cl(params, time, dose, route, medium = "plasma", restrictive = FALSE)

Arguments

Details

# Required parameters

'params' must include the following named items:

Fup

Fraction of compound unbound in plasma. Unitless.

Clint

Intrinsic clearance by hepatocytes. Units: 1/hr

Q_totli

Total blood flow through the liver. Units: L/h/kg body weight ^ (3/4)

Q_gfr

Glomerular filtration rate, how quickly do kidneys filter. Units: L/h/kg body weight ^ (3/4)

Vdist

Apparent volume of central compartment, volume/unit BW. Or see below for 'Fgutabs_Vdist'

For oral administration (if any 'route include:

Fgutabs

Oral bioavailability, unitless fraction. Or see below for 'Fgutabs_Vdist'

kgutabs

Rate of absorption from gut, 1/time.

For oral administration, in lieu of 'Vdist' and 'Fgutabs', you may instead provide 'Fgutabs_Vdist', the ratio of Fgutabs to Vdist (1/volume). This is an alternate parameterization for situations where 'Fgutabs' and 'Vdist' are not identifiable separately (i.e., when oral TK data are available, but IV data are not). If 'Fgutabs' and 'Vdist' are provided, they will override any value provided for 'Fgutabs_Vdist'.

If both oral and IV administration are specified (i.e., some 'route and some 'route 'Fgutabs' or 'Fgutabs_Vdist'. (If 'Vdist' and 'Fgutabs_Vdist' are provided, but 'Fgutabs' is not provided, then 'Fgutabs' will be calculated from 'Vdist' and 'Fgutabs_Vdist'.)

If 'any(medium 'Rblood2plasma', the ratio of chemical concentration in whole blood to the chemical concentration in blood plasma.

Value

A vector of blood or plasma concentration values corresponding to 'time'.

Author(s)

Caroline Ring, John Wambaugh

See Also

Other built-in model functions: auc_1comp(), auc_1comp_cl(), auc_2comp(), auc_flat(), cp_1comp(), cp_2comp(), cp_2comp_dt(), cp_flat(), get_params_1comp(), get_params_1comp_cl(), get_params_1comp_fup(), get_params_2comp(), get_params_flat(), get_starts_1comp(), get_starts_1comp_cl(), get_starts_1comp_fup(), get_starts_2comp(), get_starts_flat(), tkstats_2comp(), transformed_params_2comp()

Other 1-compartment model functions: auc_1comp(), auc_1comp_cl(), cp_1comp(), get_params_1comp(), get_params_1comp_cl(), get_params_1comp_fup(), get_starts_1comp(), get_starts_1comp_cl(), get_starts_1comp_fup()

Other model concentration functions: cp_1comp(), cp_2comp(), cp_flat()

Analytical 2-compartment model

Description

Calculates plasma concentration according to the analytical solution for the 2-compartment model.

Usage

cp_2comp(params, time, dose, route, medium = "plasma")

Arguments

Value

A vector of blood or plasma concentration values (mass chemical/volume media) corresponding to each value in time

Author(s)

Caroline Ring, John Wambaugh

See Also

Other built-in model functions: auc_1comp(), auc_1comp_cl(), auc_2comp(), auc_flat(), cp_1comp(), cp_1comp_cl(), cp_2comp_dt(), cp_flat(), get_params_1comp(), get_params_1comp_cl(), get_params_1comp_fup(), get_params_2comp(), get_params_flat(), get_starts_1comp(), get_starts_1comp_cl(), get_starts_1comp_fup(), get_starts_2comp(), get_starts_flat(), tkstats_2comp(), transformed_params_2comp()

Other 2-compartment model functions: auc_2comp(), cp_2comp_dt(), get_params_2comp(), get_starts_2comp(), tkstats_2comp(), transformed_params_2comp()

Other model concentration functions: cp_1comp(), cp_1comp_cl(), cp_flat()

Time derivative of analytical 2-compartment model

Description

Calculates the time derivative (instantaneous rate of change) of plasma concentration according to the analytical solution for the 2-compartment model.

Usage

cp_2comp_dt(params, time, dose, route, medium)

Arguments

Details

This function is used by [postprocess_data()] to determine the time of peak concentration for the 2-compartment model, by locating the point where the time derivative of concentration crosses zero.

Value

A vector of instantaneous rates of change of plasma concentration values (mg/L/time) corresponding to each value in time

Author(s)

Caroline Ring, John Wambaugh

See Also

Other built-in model functions: auc_1comp(), auc_1comp_cl(), auc_2comp(), auc_flat(), cp_1comp(), cp_1comp_cl(), cp_2comp(), cp_flat(), get_params_1comp(), get_params_1comp_cl(), get_params_1comp_fup(), get_params_2comp(), get_params_flat(), get_starts_1comp(), get_starts_1comp_cl(), get_starts_1comp_fup(), get_starts_2comp(), get_starts_flat(), tkstats_2comp(), transformed_params_2comp()

Other 2-compartment model functions: auc_2comp(), cp_2comp(), get_params_2comp(), get_starts_2comp(), tkstats_2comp(), transformed_params_2comp()

Flat model

Description

Evaluates a "flat" model for concentration vs. time

Usage

cp_flat(params, time, dose, route, medium = "plasma")

Arguments

Details

This function is used for model comparison: does a 1- or 2-compartment TK model fit the data any better than this naive "flat" model?

# Required parameters

'params' must include the following named items:

Vdist

Apparent volume of central compartment, volume/unit BW. Or see below for 'Fgutabs_Vdist'

For oral administration (if any 'route include:

Fgutabs

Oral bioavailability, unitless fraction. Or see below for 'Fgutabs_Vdist'

For oral administration, in lieu of 'Vdist' and 'Fgutabs', you may instead provide 'Fgutabs_Vdist', the ratio of Fgutabs to Vdist (1/volume). This is an alternate parameterization for situations where 'Fgutabs' and 'Vdist' are not identifiable separately (i.e., when oral TK data are available, but IV data are not). If 'Fgutabs' and 'Vdist' are provided, they will override any value provided for 'Fgutabs_Vdist'.

If both oral and IV administration are specified (i.e., some 'route and some 'route 'Fgutabs' or 'Fgutabs_Vdist'. (If 'Vdist' and 'Fgutabs_Vdist' are provided, but 'Fgutabs' is not provided, then 'Fgutabs' will be calculated from 'Vdist' and 'Fgutabs_Vdist'.)

If 'any(medium 'Rblood2plasma', the ratio of chemical concentration in whole blood to the chemical concentration in blood plasma.

# Flat model equations

## IV administration

\textrm{Conc} = \frac{\textrm{Dose}}{V_{\textrm{dist}}}

## Oral administration

\textrm{Conc} = \frac{F_{\textrm{gutabs}} \textrm{Dose}}{V_{\textrm{dist}}}

Value

A vector of plasma concentration values (mass chemical/volume) corresponding to time.

Author(s)

Caroline Ring, John Wambaugh, Chris Cook

See Also

Other built-in model functions: auc_1comp(), auc_1comp_cl(), auc_2comp(), auc_flat(), cp_1comp(), cp_1comp_cl(), cp_2comp(), cp_2comp_dt(), get_params_1comp(), get_params_1comp_cl(), get_params_1comp_fup(), get_params_2comp(), get_params_flat(), get_starts_1comp(), get_starts_1comp_cl(), get_starts_1comp_fup(), get_starts_2comp(), get_starts_flat(), tkstats_2comp(), transformed_params_2comp()

Other flat model functions: auc_flat(), get_params_flat(), get_starts_flat()

Other model concentration functions: cp_1comp(), cp_1comp_cl(), cp_2comp()

CvTdb data

Description

Concentration vs. time data from CvTdb

Usage

cvt

Format

A 'data.frame' with 13937 rows and 61 variables:

conc_time_id

Unique database identifier for each CvT observation.

time_original

Timepoint in original units.

time_hr

Timepoint in hours.

conc_original

Concentration in original units.

conc_sd_original

Standard deviation of concentration in original units.

conc

Concentration in normalized units.

conc_sd

Standard deviation of concentration in normalized units.

fk_series_id

Unique database identifier for experimental series.

analyte_name_original

Original analyte name.

analyte_dtxsid

DTXSID of chemical analyte.

analyte_casrn

CASRN of chemical analyte.

fk_analyzed_chemical_id

Unique database identifier for analyte.

fk_test_chemical_id

Unique database identifier for tested chemical.

test_substance_dtxsid

DTXSID of tested chemical.

analyte_name_secondary_original

Alternative names for analyte.

conc_medium_normalized

Standardized media names, blood or plasma.

conc_medium_original

Original media names.

time_units_original

Original time units.

conc_units_original

Original concentration units.

conc_units_normalized

Normalized concentration units.

conc_unit_norm_factor

Ratio of conc/conc_original

loq

Level of quantification.

loq_units

Units for loq.

n_subjects_in_series

Number of subjects in each series.

radiolabeled

Answers whether this observation comes from a radiolabelling or isotope tracing experiment.

fk_study_id

Unique database identifier for each study.

administration_route_normalized

Route of exposure/administration, either oral or iv.

fk_dosed_chemical_id

Unique database identifier for dosed chemical.

dose_volume

Volume of dose.

dose_volume_units

Units for dose_volume.

dose_vehicle

If available, specifies what vehicle was used CvT experiment.

dose_duration

Duration of the dose, if available.

dose_duration_units

Units for dose_duration.

dose_frequency

Frequency of dosing, these should all be 1 for a single bolus.

fasting_period

If available, describes the fasting period for subjects.

dose_level_normalized

Dose levels in normalized units.

dose_level_original

Dose levels in original units.

dose_level_units_original

Units for dose_level_original.

fk_subject_id

Unique database identifier for each subject.

weight_kg

Subject weight, in kilograms.

species

Subject species.

sex

Subject sex, if available.

age

Subject age, if available.

age_units

Units for age.

age_category

Categories for age.

fk_extraction_document_id

Unique database identifier for documents that were curated.

pmid

Document PubMed ID.

year

Year of publication.

other_study_identifier

Alternative identifier for documents, used for NTP studies.

url

Document URL address.

doi

Document DOI.

extracted

Curation level of document.

curation_set_tag

A grouping tag for specific document extraction and curation efforts.

n_subjects_normalized

Normalized subject number.

invivPK_dose_level_units

dose_level_units used in this package, mg/kg.

invivPK_conc_units

conc_units used in this package, ug/mL

invivPK_conc

Concentrations normalized to ug/mL

invivPK_dose_level

Dose normalized to mg/kg

invivPK_loq

Level of quantification in ug/mL

invivPK_loq_units

LOQ units used in this package, ug/mL.

invivPK_conc_sd

Standard deviation of concentrations, in ug/mL.

Details

This is concentration vs. time data from CvTdb, most recently downloaded as of the date in ['cvt_date'].

These data have been filtered to retain only oral and intravenous administration, and only measurements in blood and plasma. They have also been filtered to retain only observations where the same chemical was both administered and measured in blood/plasma (i.e., excluding observations where a metabolite was measured).

CvTdb download date

Description

The most recent download date of ['cvt'] data

Usage

cvt_date

Format

An object of class Date of length 1.

Details

A character scalar giving the date in "YYYY-MM-DD" format of the download date of the data in ['cvt'] from the CvTdb database.

data_summary()

Description

This is the S3 method generic for data_summary()

Usage

data_summary(obj, ...)

Arguments

Value

A 'data.frame' with variables including all the grouping variables in 'summary_group', 'group_id'; 'param_name' (the name of the summary statistic; see Details); 'param_value' (the summary statistic value); 'param_units' (the units of the summary statistic, derived from the units of the data).

See Also

[data_summary.pk()] for the method for class [pk()]

Default method for data_summary()

Description

Default method for data_summary()

Usage

## Default S3 method:
data_summary(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Data summary for a 'pk' object

Description

Calculate data summary statistics for a 'pk' object

Usage

## S3 method for class 'pk'
data_summary(obj, newdata = NULL, summary_group = NULL, ...)

Arguments

Details

Get summary statistics for data in a 'pk' object (or optionally, new data), using data groupings defined by 'get_nca_group()' for the 'pk' object (or optionally, new groupings). If you provide both 'newdata' and 'summary_group', then everything in the 'pk' object will be ignored and you will simply be doing data summary *de novo* (which may be what you want).

Summary statistics include, for each group:

- 'n_obs': the number of observations - 'n_exclude': The number of excluded observations - 'n_detect': The number of non-excluded detected observations - 'n_series_id': The number of unique series IDs - 'n_timepts': The number of unique time points - 'n_ref': The number of unique reference IDs - 'tlast': The time of the latest non-excluded observation - 'tlast_detect': The time of the latest non-excluded detected observation - 'tfirst': The time of the earliest non-excluded observation - 'tfirst_detect': The time of the earliest non-excluded detected observation

Value

A 'data.frame' with variables including all the grouping variables in 'summary_group', 'group_id'; 'param_name' (the name of the summary statistic; see Details); 'param_value' (the summary statistic value); 'param_units' (the units of the summary statistic, derived from the units of the data).

Author(s)

Caroline Ring

Log-normal distribution density function for summary data

Description

Evaluates the normal distribution density function for summary data reported as sample mean, sample SD, and sample N. Sample mean and sample SD should be on the *natural* scale. If you have log-scale sample mean and SD (i.e., the mean and SD of log-transformed observations),then use [dnorm_summary()] instead.

Usage

dlnorm_summary(mu, sigma, x_mean, x_sd, x_N, log = FALSE)

Arguments

Details

'x_mean', 'x_sd', 'X_N', 'mu', and 'sigma' should either be all the same size, or length 1. If they are different lengths, they will be repeated until their lengths match, with a warning.

Value

A numeric scalar or vector matching the length of the longest of 'mu', 'sigma', 'x_mean', 'x_sd', and 'x_N'.

Author(s)

Caroline Ring

Normal distribution density function for summary data

Description

Evaluates the normal distribution density function for summary data reported as sample mean, sample SD, and sample N.

Usage

dnorm_summary(mu, sigma, x_mean, x_sd, x_N, log = FALSE)

Arguments

Details

'x_mean', 'x_sd', 'X_N', 'mu', and 'sigma' should either be all the same size, or length 1. If they are different lengths, they will be repeated until their lengths match, with a warning.

Value

A numeric scalar or vector matching the length of the longest of 'mu', 'sigma', 'x_mean', 'x_sd', and 'x_N'.

Author(s)

Caroline Ring

do_data_info generic

Description

do_data_info generic

Usage

do_data_info(obj, ...)

Arguments

Value

Object of class [pk()] with an added '$data_info' list containing non-compartmental analysis results.

See Also

[do_data_info.pk()] for the 'do_data_info' method for class [pk()]

do_data_info default method

Description

do_data_info default method

Usage

## Default S3 method:
do_data_info(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

calculate summary data info

Description

Calculate summary data information, including non-compartmental analysis.

Usage

## S3 method for class 'pk'
do_data_info(obj, ...)

Arguments

Value

Object of class [pk()] with an added '$data_info' list containing non-compartmental analysis results.

Author(s)

Caroline Ring

Fitting

Description

This is the S3 generic method for 'do_fit'.

Usage

do_fit(obj, ...)

Arguments

Value

The same [pk] object, with element 'fit' containing the fitted results for each model in 'stat_model'.

See Also

[do_fit.pk()] for the 'do_fit' method for class [pk()]

do_fit default method

Description

do_fit default method

Usage

## Default S3 method:
do_fit(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Do fitting

Description

Fit PK model(s) for a 'pk' object

Usage

## S3 method for class 'pk'
do_fit(obj, n_cores = NULL, rate_names = NULL, max_multiplier = NULL, ...)

Arguments

Details

This function estimates the parameters for each model in 'stat_model' from the data, using numerical optimization implemented in [optimx::optimx()]. The optimization is done by maximizing the log-likelihood function implemented in [log_likelihood()] (technically, by minimizing the negative log-likelihood). Only the non-excluded observations are used.

Due to limitations of [optimx::optimx()], the log-likelihood function is forced to return finite values during this optimization. Impossible combinations of parameters (e.g., parameter values that produce negative predicted concentrations) should have a log-likelihood of '-Inf', but due to this limitation, they instead have a log-likelihood of '-Machine.doublexmax'. This limitation means that the log-likelihood function is flat in regions of impossible parameter values. It is unlikely, but possible, that the optimizer might get "stuck" in such a flat region – report convergence, but return a "bad" set of parameter values that produces non-physical predictions.

Before trusting the results of any fit, it is recommended to check the log-likelihood using [logLik()] and the Akaike Information Criterion using [AIC()], which check the log-likelihood *without* forcing it to return finite values.

Value

The same [pk] object, with element 'fit' containing the fitted results for each model in 'stat_model'.

Author(s)

Caroline Ring, Gilberto Padilla Mercado

Prefitting

Description

Prefitting

Usage

do_prefit(obj, ...)

Arguments

Value

The same 'pk' object, but with a new element 'prefit', containing the results of pre-fit calculations and checks for each model and for the error model.

See Also

[do_prefit.pk()] for the 'do_prefit' method for class [pk()]

do_prefit default method

Description

do_prefit default method

Usage

## Default S3 method:
do_prefit(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Do pre-fitting

Description

Do pre-fit calculations and checks

Usage

## S3 method for class 'pk'
do_prefit(obj, ...)

Arguments

Details

This function does the following:

- Based on the error model in 'stat_error_model' and the pre-processed data, determines the number of residual standard deviations ("sigmas") hyperparameters to be estimated. - Determines which "sigma" hyperparameter corresponds to each observation in the data. - Calculates lower/upper bounds and starting guesses for each "sigma" hyperparameter - For each model in ‘stat_model', calls its 'params_fun', the function that, based on the data, determines whether to optimize each model parameter, and calculates lower/upper bounds and starting guesses for each model parameter to be optimized. Only non-excluded observations are passed to each model’s 'params_fun'.

Lower bounds for each "sigma" hyperparameter are set to 'sqrt(.Machine$double_eps)'.

Upper bounds for each "sigma" hyperparameter are calculated as the standard deviation of observations in the corresponding error SD group (see [combined_sd()]), with any specified transformations applied (dose-normalization and/or log10-transformation). If the combined SD is non-finite or less than the sigma lower bound, then the maximum concentration is used as an upper bound; if this still returns a non-finite value or a value less than the lower bound, then a constant value of 1000 is substituted.

The starting guess for each "sigma" hyperparameter is one-tenth of the upper bound.

Value

The same 'pk' object, but with a new element 'prefit', containing the results of pre-fit calculations and checks for each model and for the error model.

Author(s)

Caroline Ring

Preprocess data generic

Description

Preprocess data generic

Usage

do_preprocess(obj, ...)

Arguments

Value

The same 'pk' object, with added elements 'data' (containing the cleaned, gap-filled data) and 'data_info' (containing summary information about the data, e.g. number of observations by route, media, detect/nondetect; empirical tmax, time of peak concentration for oral data; number of observations before and after empirical tmax)

See Also

[do_preprocess.pk()] for the 'do_preprocess' method for class [pk()]

do_preprocess default method

Description

do_preprocess default method

Usage

## Default S3 method:
do_preprocess(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Do pre-processing

Description

Pre-process data for a 'pk' object

Usage

## S3 method for class 'pk'
do_preprocess(obj, ...)

Arguments

Details

Data pre-processing for an object 'obj' includes the following steps, in order:

- Coerce data to class 'data.frame' (if it is not already) - Rename variables to harmonized "'invivopkfit' aesthetic" variable names, using 'obj$mapping' - Check that the data includes only routes in 'obj$settings_preprocess$routes_keep' and media in 'obj$settings_preprocess$media_keep' - Check that the data includes only one unit for concentration, one unit for time, and one unit for dose. - Coerce 'Value', 'Value_SD', 'LOQ', 'Dose', and 'Time' to numeric, if they are not already. - Coerce 'Species', 'Route', and 'Media' to lowercase. - Replace any negative 'Value', 'Value_SD', 'Dose', or 'Time' with 'NA' - If any non-NA 'Value' is currently less than its non-NA LOQ, then replace it with NA - Impute any NA 'LOQ': as 'calc_loq_factor' * minimum non-NA 'Value' in each 'loq_group' - For any cases where 'N_Subject's is NA, impute 'N_Subjects' = 1 - For anything with 'N_Subjects' == 1, set 'Value_SD' to 0 - Impute missing 'Value_SD' as follows: For observations with 'N_Subjects' > 1, take the minimum non-missing 'Value_SD' for each 'sd_group'. If all SDs are missing in an 'sd_group', then 'Value_SD' for each observation in that group will be imputed as 0. - Mark data for exclusion according to the following criteria: - Exclude any remaining observations where both Value and LOQ are NA - For any cases where 'N_Subjects' is NA, impute 'N_Subjects' = 1 - Exclude any remaining observations with 'N_Subjects' > 1 and 'Value_SD' still NA. (This should never occur, if SD imputation is performed, but just in case.) - Exclude any observations with 'N_Subjects' > 1 where reported 'Value' is NA, because log-likelihood for non-detect multi-subject observations has not been implemented. - Exclude any observations with NA 'Time' values - Exclude any observations with 'Dose' = 0 - Apply any time transformations specified by user - Scale concentration by 'ratio_conc_dose' - Apply any concentration transformations specified by the user. - If 'Series_ID' is not included, then assign it as NA - Create variable 'pLOQ' and set it equal to 'LOQ'

Value

The same 'pk' object, with added elements 'data' (containing the cleaned, gap-filled data) and 'data_info' (containing summary information about the data, e.g. number of observations by route, media, detect/nondetect; empirical tmax, time of peak concentration for oral data; number of observations before and after empirical tmax)

Author(s)

John Wambaugh, Caroline Ring, Christopher Cook, Gilberto Padilla Mercado

eval_tkstats()

Description

This is the S3 method generic for eval_tkstats()

Usage

eval_tkstats(obj, ...)

Arguments

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.

See Also

[eval_tkstats.pk()] for the method for class [pk()]

Default method for eval_tkstats()

Description

Default method for eval_tkstats()

Usage

## Default S3 method:
eval_tkstats(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

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

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()

Facet a PK fit

Description

Create a "faceted" [pk()] object.

Usage

facet_data(facets = vars(Chemical, Species), ...)

Arguments

Details

This function automates the process of doing PK fitting in "batch mode", when you have multiple concentration-dose-time datasets to fit, and you want to fit them all using the same set of instructions.

When you do something like

“' pk_cvt <- pk(cvt) + facet_data( facets = vars( chemicals_analyzed.dsstox_substance_id, subjects.species_harmonized ) ) “'

Now 'pk_cvt' is an object of class 'pk_faceted': under the hood, a [tibble::tibble()] with one row for each group defined by a unique combination of the faceting variables, and a 'list' column containing a [pk()] object corresponding to each group.

All of the [pk()] objects in the 'list' column contain the same set of instructions, and they will all have the same status (*i.e.*, they are all in the same stage of the workflow at the same time). The only thing different among them is the data.

If you call a 'pk' method on a 'pk_faceted' object, the method will be applied in turn to the [pk()] object for each group.

If the method returns a [pk()] object (e.g. [preprocess_data.pk()], [data_info.pk()], [prefit.pk()], and [fit.pk()]), then the result for a 'pk_faceted' object will be another 'pk_faceted' object.

If the method returns something other than a [pk()] object (e.g. [coef.pk()], [coef_sd.pk()], [residuals.pk()], [predict.pk()], ...) then the result for a 'pk_faceted' object will simply be a [tibble::tibble()] with a 'list' column containing the result for each group – it won't have class 'pk_faceted'.

This function is named by analogy to [ggplot2::facet_wrap()] and [ggplot2::facet_grid()]. Those functions split up a dataset into groups by one or more 'factor' variables, and produce a "faceted" grid of plots for each group of data. This function does an analogous thing for a [pk()] analysis. The dataset is split into groups by the unique combinations of variables in 'facets'. For each group, a separate [pk()] object is created, using the instructions provided by the user. When methods like [preprocess_data()], [data_info()], [prefit()], and [fit()] are called on the resulting "faceted"

Value

An object of class 'c("pkproto", "pk_facet_data")'. Under the hood, a named 'list' containing the arguments provided to this function. Almost always added to a [pk()] object using ['+.pk'].

Author(s)

Caroline Ring, Gilbert Padilla Mercado, Paul Kruse

Fill parameters for 1-compartment model

Description

Fill parameters for 1-compartment model

Usage

fill_params_1comp(params)

Arguments

Value

A named numeric vector of parameters, with any 1-compartment model parameters not present in 'params' filled with 'NA_real_'. If any two of 'Fgutabs', 'Vdist', and 'Fgutabs_Vdist' were present in 'params', the third will be imputed to agree with the other two.

Author(s)

Caroline Ring

Fill parameters for 1-compartment model with specific clearance

Description

Fill parameters for 1-compartment model with specific clearance

Usage

fill_params_1comp_cl(params)

Arguments

Value

A named numeric vector of parameters, with any 1-compartment model parameters not present in 'params' filled with 'NA_real_'. If any two of 'Fgutabs', 'Vdist', and 'Fgutabs_Vdist' were present in 'params', the third will be imputed to agree with the other two.

Author(s)

Caroline Ring

Fill parameters for 2-compartment model

Description

Fill parameters for 2-compartment model

Usage

fill_params_2comp(params)

Arguments

Value

A named numeric vector of parameters, with any 2-compartment model parameters not present in 'params' filled with 'NA_real_'. If any two of 'Fgutabs', 'V1', and 'Fgutabs_V1' were present in 'params', the third will be imputed to agree with the other two.

Author(s)

Caroline Ring

Fill parameters for flat model

Description

Fill parameters for flat model

Usage

fill_params_flat(params)

Arguments

Value

A named numeric vector of parameters, with any flat model parameters not present in 'params' filled with 'NA_real_'. If any two of 'Fgutabs', 'Vdist', and 'Fgutabs_Vdist' were present in 'params', the third will be imputed to agree with the other two.

Author(s)

Caroline Ring

Fit a single group of data

Description

Fit a single group of data

Usage

fit_group(
  data,
  par_DF,
  sigma_DF,
  fit_decision,
  this_model,
  settings_optimx,
  modelfun,
  dose_norm,
  log10_trans,
  max_mult,
  suppress.messages
)

Arguments

Value

An object of class 'optimx' (i.e. a data.frame with fit results)

Fold error

Description

This is the S3 method generic for 'fold_error'.

Usage

fold_error(obj, ...)

Arguments

Value

A data.frame with one row for each 'data_group', 'model' and 'method'. A column contains the fold errors (observed/predicted) of the model fitted by the corresponding method. These residuals are concentrations in the same units as 'obj$data$Conc.Units'; any concentration transformations (in 'obj$scale$conc') are *not* applied.

See Also

[fold_error.pk()] for the 'fold_error' method for class [pk()]

fold_error default method

Description

fold_error default method

Usage

## Default S3 method:
fold_error(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Fold errors

Description

Calculate fold errors for a fitted 'pk' object.

Usage

## S3 method for class 'pk'
fold_error(
  obj,
  newdata = NULL,
  model = NULL,
  method = NULL,
  exclude = TRUE,
  sub_pLOQ = TRUE,
  suppress.messages = NULL,
  ...
)

Arguments

Details

Here, fold error is defined as 'observed/predicted'.

# Scaling and transformation of concentration variables in 'newdata'

This function differs from some of the other methods for a fitted [pk()] object that accept 'newdata', in that there is no 'use_scale_conc' argument for [fold_error.pk()]. Fold errors are always computed on the natural, un-transformed concentration scale (but note that fold error on a dose-normalized scale will be the same as fold error on a non-dose-normalized scale).

Value

A data.frame with one row for each 'data_group', 'model' and 'method'. A column contains the fold errors (observed/predicted) of the model fitted by the corresponding method. These residuals are concentrations in the same units as 'obj$data$Conc.Units'; any concentration transformations (in 'obj$scale$conc') are *not* applied.

Author(s)

Caroline Ring

get_data()

Description

This is the S3 method generic for get_data()

Usage

get_data(obj, ...)

Arguments

Value

A 'data.frame': the 'data' element of 'obj'

See Also

[get_data.pk()] for the method for class [pk()]

Default method for get_data()

Description

Default method for get_data()

Usage

## Default S3 method:
get_data(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Get data

Description

Extract pre-processed data from a [pk()] object

Usage

## S3 method for class 'pk'
get_data(obj, ...)

Arguments

Value

A 'data.frame': the 'data' element of 'obj'

Author(s)

Caroline Ring

get_data_group()

Description

This is the S3 method generic for get_data_group()

Usage

get_data_group(obj, ...)

Arguments

Value

An object of class 'call' giving the data grouping as a 'dplyr::vars()' specification

See Also

[get_data_group.pk()] for the method for class [pk()]

Default method for get_data_group()

Description

Default method for get_data_group()

Usage

## Default S3 method:
get_data_group(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Get data grouping

Description

Get data grouping

Usage

## S3 method for class 'pk'
get_data_group(obj, ...)

Arguments

Value

An object of class 'call' giving the data grouping as a 'dplyr::vars()' specification

get_data_info()

Description

This is the S3 method generic for get_data_info()

Usage

get_data_info(obj, ...)

Arguments

Value

A 'list' of 'tibble's: the 'data_info' element of 'obj'

See Also

[get_data_info.pk()] for the method for class [pk()]

Default method for get_data_info()

Description

Default method for get_data_info()

Usage

## Default S3 method:
get_data_info(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Get data_info

Description

Extract summary data information results from a [pk()] object

Usage

## S3 method for class 'pk'
get_data_info(obj, ...)

Arguments

Value

A 'list' of 'tibble's: the 'data_info' element of 'obj'

Author(s)

Caroline Ring

get_data_original()

Description

This is the S3 method generic for get_data_original()

Usage

get_data_original(obj, ...)

Arguments

Value

A 'data.frame' – the 'data_original' element of 'obj'

See Also

[get_data_original.pk()] for the method for class [pk()]

Default method for get_data_original()

Description

Default method for get_data_original()

Usage

## Default S3 method:
get_data_original(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Get data_original

Description

Get data_original

Usage

## S3 method for class 'pk'
get_data_original(obj, ...)

Arguments

Value

A 'data.frame' – the 'data_original' element of 'obj'

Author(s)

Caroline Ring

get_data_sigma_group()

Description

This is the S3 method generic for get_data_sigma_group()

Usage

get_data_sigma_group(obj, ...)

Arguments

Value

A 'factor' vector giving the error SD group ID for each observation, as the interaction of the factors specified in 'obj$stat_error_model$error_group'.

See Also

[get_data_sigma_group.pk()] for the method for class [pk()]

Default method for get_data_sigma_group()

Description

Default method for get_data_sigma_group()

Usage

## Default S3 method:
get_data_sigma_group(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Get data_sigma_group

Description

Get data_sigma_group

Usage

## S3 method for class 'pk'
get_data_sigma_group(obj, newdata = NULL, ...)

Arguments

Value

A 'factor' vector giving the error SD group ID for each observation, as the interaction of the factors specified in 'obj$stat_error_model$error_group'.

Author(s)

Caroline Ring

get_data_summary()

Description

This is the S3 method generic for get_data_summary()

Usage

get_data_summary(obj, ...)

Arguments

Details

'get_data_summary()' is an alias for 'data_summary()'

Value

A 'data.frame' with variables including all the grouping variables in 'summary_group', 'group_id'; 'param_name' (the name of the summary statistic; see Details); 'param_value' (the summary statistic value); 'param_units' (the units of the summary statistic, derived from the units of the data).

See Also

[data_summary.pk()] for the method for class [pk()]

Default method for get_data_summary()

Description

Default method for get_data_summary()

Usage

## Default S3 method:
get_data_summary(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Get an elbow point

Description

Given a set of data specified as two vectors of 'x' and 'y' values, find an elbow point.

Usage

get_elbow(x, y, ...)

Arguments

Details

This is a helper function for [get_starts()] to find elbow points.

Given a set of (x,y) data points, an "elbow point" can be defined by drawing a line connecting the points for minimum and maximum x, and then finding the x value of the observation where the distance to that line is greatest.

[get_starts()] uses elbow points as a way to automate separation of concentration-time data into different kinetic phases in order to calculate starting points for fitting TK model parameters. For example, if concentration-time data are described by a two-compartment TK model, then early and late elimination phases will be separated by an elbow point. This helper function finds the elbow points. (When this function is called from [get_starts()], 'x' will be a vector of time values, and 'y' will be a vector of log-transformed dose-normalized concentration values.)

Value

A list with two named numeric scalar elements, 'x' and 'y'. 'x' contains the 'x' value at the elbow point. 'y' contains the 'y' value at the elbow point. The elbow point is *not* necessarily one of the input data points; it may be interpolated.

Author(s)

Caroline Ring

get_error_group()

Description

This is the S3 method generic for get_error_group()

Usage

get_error_group(obj, ...)

Arguments

Value

The stat_error_model error grouping

See Also

[get_error_group.pk()] for the method for class [pk()]

Default method for get_error_group()

Description

Default method for get_error_group()

Usage

## Default S3 method:
get_error_group(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Get error group

Description

Get error group

Usage

## S3 method for class 'pk'
get_error_group(obj, ...)

Arguments

Value

The stat_error_model error grouping

Author(s)

Caroline Ring

get_fit()

Description

This is the S3 method generic for get_fit()

Usage

get_fit(obj, ...)

Arguments

Value

A named list of objects of class 'optimx', named for the models in 'model'. As described in [optimx::optimx()] If only one model is specified, the return value will still be a list, but with only one element.

See Also

[get_fit.pk()] for the method for class [pk()]

Default method for get_fit()

Description

Default method for get_fit()

Usage

## Default S3 method:
get_fit(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Get fits from a 'pk' object

Description

Get the [optimx::optimx()] output from a fitted 'pk' object

Usage

## S3 method for class 'pk'
get_fit(obj, model = NULL, ...)

Arguments

Details

This function returns the object(s) returned by [optimx::optimx()] for the specified model(s) and method(s), for a fitted 'pk' object. See [optimx::optimx()] for details. Briefly, an 'optimx' object is a 'data.frame' with one row for each method used, and variables that give the optimized values for each parameter, along with several diagnostic variables (e.g. the objective function value at the optimized parameter values; the number of function evaluations/iterations; an integer code describing convergence status). The object will have attributes 'details' (providing any messages returned by the methods) and 'npar' (the number of parameters optimized).

Value

A named list of objects of class 'optimx', named for the models in 'model'. As described in [optimx::optimx()] If only one model is specified, the return value will still be a list, but with only one element.

Author(s)

Caroline Ring, Gilberto Padilla Mercado

See Also

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

get_hessian()

Description

This is the S3 method generic for get_hessian()

Usage

get_hessian(obj, ...)

Arguments

Value

A dataframe with one row for each 'data_group', 'model' and 'method'. The remaining column is a 'list' column containing the Hessian for each row.

See Also

[hessian.pk()] for the method for class [pk()]

Default method for get_hessian()

Description

Default method for get_hessian()

Usage

## Default S3 method:
get_hessian(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Get Hessian matrixes

Description

Extract Hessian matrixes from a fitted 'pk' object

Usage

## S3 method for class 'pk'
get_hessian(obj, model = NULL, method = NULL, suppress.messages = TRUE, ...)

Arguments

Details

This function computes a numerical approximation to the model Hessian for each data group and each model in a fitted 'pk' object. The Hessian is the matrix of second derivatives of the model objective function with respect to each model parameter. Here, the objective function is the negative log-likelihood implemented in [log_likelihood()], evaluated jointly across the data that was used to fit the model.

Value

A dataframe with one row for each 'data_group', 'model' and 'method'. The remaining column is a 'list' column containing the Hessian for each row.

Author(s)

Caroline Ring and Gilberto Padilla Mercado

References

Gill J, King G. (2004) What to Do When Your Hessian is Not Invertible: Alternatives to Model Respecification in Nonlinear Estimation. Sociological Methods & Research 33(1):54-87. DOI: 10.1177/0049124103262681

See Also

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_tkstats.pk(), logLik.pk(), predict.pk(), residuals.pk(), rmse.pk(), rsq.pk()

get_mapping()

Description

This is the S3 method generic for get_mapping()

Usage

get_mapping(obj, ...)

Arguments

Value

A list of 'quosure's – the 'mapping' element of 'obj'

See Also

[get_mapping.pk()] for the method for class [pk()]

Default method for get_mapping()

Description

Default method for get_mapping()

Usage

## Default S3 method:
get_mapping(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Get mapping

Description

Get mapping

Usage

## S3 method for class 'pk'
get_mapping(obj, ...)

Arguments

Value

A list of 'quosure's – the 'mapping' element of 'obj'

Author(s)

Caroline Ring

get_nca()

Description

This is the S3 method generic for get_nca()

Usage

get_nca(obj, ...)

Arguments

Value

A 'data.frame': the 'data' element of 'obj'

See Also

[get_nca.pk()] for the method for class [pk()]

Default method for get_nca()

Description

Default method for get_nca()

Usage

## Default S3 method:
get_nca(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Get NCA

Description

Extract non-compartmental analysis results from a [pk()] object

Usage

## S3 method for class 'pk'
get_nca(obj, ...)

Arguments

Value

A 'data.frame': the 'data' element of 'obj'

Author(s)

Caroline Ring, Gilberto Padilla Mercado

Get parameters for 1-compartment model

Description

Get parameters for 1-compartment model and determine whether each is to be estimated from the data

Usage

get_params_1comp(
  data,
  lower_bound = ggplot2::aes(kelim = log(2)/(2 * max(Time_trans)), Vdist = 0.01, Fgutabs
    = 0, kgutabs = log(2)/(2 * max(Time_trans)), Fgutabs_Vdist = 0.01, Rblood2plasma =
    0.01),
  upper_bound = ggplot2::aes(kelim = log(2)/(0.5 * min(Time_trans[Time_trans > 0])),
    Vdist = 100, Fgutabs = 1, kgutabs = log(2)/(0.5 * min(Time_trans[Time_trans > 0])),
    Fgutabs_Vdist = 100, Rblood2plasma = 100),
  param_units = ggplot2::aes(kelim = paste0("1/", unique(Time_trans.Units)), Vdist =
    paste0("(", unique(Dose.Units), ")", "/", "(", unique(Conc.Units), ")"), Fgutabs =
    "unitless fraction", kgutabs = paste0("1/", unique(Time_trans.Units)), Fgutabs_Vdist
    = paste0("(", unique(Conc.Units), ")", "/", "(", unique(Dose.Units), ")"),
    Rblood2plasma = "unitless ratio")
)

Arguments

Details

The full set of model parameters for the 1-compartment model includes 'Vdist', 'kelim', 'kgutabs', 'Fgutabs', and 'Rblood2plasma'. Whether each one can be estimated from the data depends on what routes of administration are included in the data.

# IV data, no oral data

If IV dosing data are available, but no oral dosing data are available, then only the parameters 'Vdist' and 'kelim' will be estimated from the data. The parameters 'kgutabs' and 'Fgutabs' cannot be estimated from IV data alone, and will not be used in evaluating the model.

# Oral data, no IV data

If oral dosing data are available, but no IV dosing data are available, then the parameters 'kelim' and 'kgutabs' can be estimated from the data. However, the parameters 'Fgutabs' and 'Vdist' cannot be identified separately. From oral data alone, only the ratio 'Fgutabs/Vdist' can be identified. This ratio is represented by a single parameter named 'Fgutabs_Vdist'. 'Fgutabs' and 'Vdist' will not be used to evaluate the model nor be estimated from data, but 'Fgutabs_Vdist' will be estimated from data, along with 'kelim' and 'kgutabs'.

# Oral data and IV data

If both oral and IV dosing data are available, then 'Vdist', 'kelim', 'kgutabs', and 'Fgutabs' will all be estimated from the data.

# Blood and plasma data

If both blood and plasma data are available, then 'Rblood2plasma' will be estimated from the data.

# Only one of blood or plasma data

If only one of blood or plasma data are available, then 'Rblood2plasma' will be held constant at 1, not estimated from the data.

# Default lower and upper bounds for each parameter

## Default lower and upper bounds for 'kelim' and 'kgutabs'

Default bounds for time constants 'kelim' and 'kgutabs' are set based on the time scale of the available data.

The lower bounds are based on the assumption that elimination and absorption are very slow compared to the time scale of the study. Specifically, the lower bounds assume that elimination and absorption half-lives are twice as long as the duration of the available study data, or '2*max(Time_trans)'. Under this assumption, the corresponding elimination and absorption time constants would be 'log(2)/(2*max(Time_trans))'. Therefore, the default lower bounds for 'kelim' and 'kgutabs' are 'log(2)/(2*max(Time_trans))'.

Upper bounds are based on the opposite assumption: that elimination and absorption are very fast compared to the time scale of the study. Specifically, the upper bounds assume that the elimination and absorption half-lives are half as long as the time of the first observation after time 0, or '0.5*min(Time_trans[Time_trans>0])'. Under this asumption, the corresponding elimination and absorption time constants would be 'log(2)/(0.5*min(Time_trans[Time_trans>0]))'. Therefore, the default lower bounds for 'kelim' and 'kgutabs' are 'log(2)/(0.5*min(Time_trans[Time_trans>0]))'.

## Default lower and upper bounds for 'Vdist'

By default, the lower bound for 'Vdist' is 0.01, and the upper bound for 'Vdist' is 100. These values were chosen based on professional judgment.

## Default lower and upper bounds for 'Fgutabs'

By default, the lower bound for 'Fgutabs' is 0.0, and the upper bound for 'Fgutabs' is 1. These are simply the bounds of the physically-meaningful range for a fraction.

## Default lower and upper bounds for 'Fgutabs_Vdist'

By default, the lower bound for the ratio 'Fgutabs_Vdist' is 0.01, and the upper bound is 100. These values were chosen based on professional judgment.

## Default lower and upper bounds for 'Rblood2plasma'

By default, the lower bound for the blood:plasma partition coefficient 'Rblood2plasma' is 0.01, and the upper bound is 100. These values were chosen based on professional judgment.

# Starting values for each parameter

Starting values for each parameter (starting guesses for the numerical optimizer) are derived from the data using [get_starts_1comp()].

If the starting values returned by [get_starts_1comp()] fall outside the bounds for any parameter(s), then the starting value will be reset to a value halfway between the lower and upper bounds for that parameter.

Value

A 'data.frame'with the following variables: - 'param_name': Character: Names of the model parameters - 'param_units': Character: Units of the model parameters - 'optimize_param': TRUE if each parameter is to be estimated from the data; FALSE otherwise - 'use_param': TRUE if each parameter is to be used in evaluating the model; FALSE otherwise -'lower_bounds': Numeric: The lower bounds for each parameter - 'upper_bounds': Numeric: The upper bounds for each parameter - 'start': Numeric: The starting guesses for each parameter

Author(s)

Caroline Ring

See Also

Other 1-compartment model functions: auc_1comp(), auc_1comp_cl(), cp_1comp(), cp_1comp_cl(), get_params_1comp_cl(), get_params_1comp_fup(), get_starts_1comp(), get_starts_1comp_cl(), get_starts_1comp_fup()

Other get_params functions: get_params_1comp_cl(), get_params_1comp_fup(), get_params_2comp(), get_params_flat()

Other built-in model functions: auc_1comp(), auc_1comp_cl(), auc_2comp(), auc_flat(), cp_1comp(), cp_1comp_cl(), cp_2comp(), cp_2comp_dt(), cp_flat(), get_params_1comp_cl(), get_params_1comp_fup(), get_params_2comp(), get_params_flat(), get_starts_1comp(), get_starts_1comp_cl(), get_starts_1comp_fup(), get_starts_2comp(), get_starts_flat(), tkstats_2comp(), transformed_params_2comp()

Get parameters for 1-compartment model with clearance assumption

Description

Get parameters for 1-compartment model and determine whether each is to be estimated from the data

Usage

get_params_1comp_cl(
  data,
  lower_bound = ggplot2::aes(Q_totli = NA, Q_gfr = NA, Fup = 0, Clint = 0, Vdist = 0.01,
    Fgutabs = 0, kgutabs = log(2)/(2 * max(Time_trans)), Fgutabs_Vdist = 0.01,
    Rblood2plasma = 0.01),
  upper_bound = ggplot2::aes(Q_totli = NA, Q_gfr = NA, Fup = 1, Clint = 1e+05, Vdist =
    100, Fgutabs = 1, kgutabs = log(2)/(0.5 * min(Time_trans[Time_trans > 0])),
    Fgutabs_Vdist = 100, Rblood2plasma = 100),
  param_units = ggplot2::aes(Q_totli = "L/h/kg ^3/4", Q_gfr = "L/h/kg ^3/4", Fup =
    "unitless fraction", Clint = "L/h/kg", Vdist = paste0("(", unique(Dose.Units), ")",
    "/", "(", unique(Conc.Units), ")"), Fgutabs = "unitless fraction", kgutabs =
    paste0("1/", unique(Time_trans.Units)), Fgutabs_Vdist = paste0("(",
    unique(Conc.Units), ")", "/", "(", unique(Dose.Units), ")"), Rblood2plasma =
    "unitless ratio"),
  restrictive = FALSE
)

Arguments

Details

The full set of model parameters for the 1-compartment model includes 'Vdist', 'Clint', 'kgutabs', 'Fgutabs', 'Q_totli', 'Q_gfr', 'Fup', and 'Rblood2plasma'. Whether each one can be estimated from the data depends on which routes of administration are included in the data.

# Constant parameters from 'httk' 'Q_totli' is the flow through the portal vein from the gut to the liver and is estimated in this model via [httk::tissue.data] in a species-specific manner. 'Q_gfr' is the glomular filtration rate of kidneys. It is estimated via [httk::physiology.data] in a species specific manner. 'Fup' and 'Rblood2plasma' are both calculated in [httk::parameterize_1comp()] For each of these parameters default lower bounds are 10

# IV data, no oral data

If IV dosing data are available, but no oral dosing data are available, then only the parameters 'Vdist' and 'kelim' will be estimated from the data. The parameters 'kgutabs' and 'Fgutabs' cannot be estimated from IV data alone, and will not be used in evaluating the model.

# Oral data, no IV data

If oral dosing data are available, but no IV dosing data are available, then the parameters 'kelim' and 'kgutabs' can be estimated from the data. However, the parameters 'Fgutabs' and 'Vdist' cannot be identified separately. From oral data alone, only the ratio 'Fgutabs/Vdist' can be identified. This ratio is represented by a single parameter named 'Fgutabs_Vdist'. 'Fgutabs' and 'Vdist' will not be used to evaluate the model nor be estimated from data, but 'Fgutabs_Vdist' will be estimated from data, along with 'kelim' and 'kgutabs'.

# Oral data and IV data

If both oral and IV dosing data are available, then 'Vdist', 'kelim', 'kgutabs', and 'Fgutabs' will all be estimated from the data.

# Blood and plasma data

If both blood and plasma data are available, then 'Rblood2plasma' will be estimated from the data.

# Only one of blood or plasma data

If only one of blood or plasma data are available, then 'Rblood2plasma' will be held constant at 1, not estimated from the data.

# Default lower and upper bounds for each parameter

## Default lower and upper bounds for 'kelim' and 'kgutabs'

Default bounds for time constants 'kelim' and 'kgutabs' are set based on the time scale of the available data.

The lower bounds are based on the assumption that elimination and absorption are very slow compared to the time scale of the study. Specifically, the lower bounds assume that elimination and absorption half-lives are twice as long as the duration of the available study data, or '2*max(Time_trans)'. Under this assumption, the corresponding elimination and absorption time constants would be 'log(2)/(2*max(Time_trans))'. Therefore, the default lower bounds for 'kelim' and 'kgutabs' are 'log(2)/(2*max(Time_trans))'.

Upper bounds are based on the opposite assumption: that elimination and absorption are very fast compared to the time scale of the study. Specifically, the upper bounds assume that the elimination and absorption half-lives are half as long as the time of the first observation after time 0, or '0.5*min(Time_trans[Time_trans>0])'. Under this asumption, the corresponding elimination and absorption time constants would be 'log(2)/(0.5*min(Time_trans[Time_trans>0]))'. Therefore, the default lower bounds for 'kelim' and 'kgutabs' are 'log(2)/(0.5*min(Time_trans[Time_trans>0]))'.

## Default lower and upper bounds for 'Vdist'

By default, the lower bound for 'Vdist' is 0.01, and the upper bound for 'Vdist' is 100. These values were chosen based on professional judgment.

## Default lower and upper bounds for 'Fgutabs'

By default, the lower bound for 'Fgutabs' is 0.0, and the upper bound for 'Fgutabs' is 1. These are simply the bounds of the physically-meaningful range for a fraction.

## Default lower and upper bounds for 'Fgutabs_Vdist'

By default, the lower bound for the ratio 'Fgutabs_Vdist' is 0.01, and the upper bound is 100. These values were chosen based on professional judgment.

## Default lower and upper bounds for 'Rblood2plasma'

By default, the lower bound for the blood:plasma partition coefficient 'Rblood2plasma' is 0.01, and the upper bound is 100. These values were chosen based on professional judgment.

# Starting values for each parameter

Starting values for each parameter (starting guesses for the numerical optimizer) are derived from the data using [get_starts_1comp()].

If the starting values returned by [get_starts_1comp()] fall outside the bounds for any parameter(s), then the starting value will be reset to a value halfway between the lower and upper bounds for that parameter.

Value

A 'data.frame'with the following variables: - 'param_name': Character: Names of the model parameters - 'param_units': Character: Units of the model parameters - 'optimize_param': TRUE if each parameter is to be estimated from the data; FALSE otherwise - 'use_param': TRUE if each parameter is to be used in evaluating the model; FALSE otherwise -'lower_bounds': Numeric: The lower bounds for each parameter - 'upper_bounds': Numeric: The upper bounds for each parameter - 'start': Numeric: The starting guesses for each parameter

Author(s)

Caroline Ring

See Also

Other 1-compartment model functions: auc_1comp(), auc_1comp_cl(), cp_1comp(), cp_1comp_cl(), get_params_1comp(), get_params_1comp_fup(), get_starts_1comp(), get_starts_1comp_cl(), get_starts_1comp_fup()

Other get_params functions: get_params_1comp(), get_params_1comp_fup(), get_params_2comp(), get_params_flat()

Other built-in model functions: auc_1comp(), auc_1comp_cl(), auc_2comp(), auc_flat(), cp_1comp(), cp_1comp_cl(), cp_2comp(), cp_2comp_dt(), cp_flat(), get_params_1comp(), get_params_1comp_fup(), get_params_2comp(), get_params_flat(), get_starts_1comp(), get_starts_1comp_cl(), get_starts_1comp_fup(), get_starts_2comp(), get_starts_flat(), tkstats_2comp(), transformed_params_2comp()

Get parameters for 1-compartment model with clearance assumption

Description

Get parameters for 1-compartment model and determine whether each is to be estimated from the data

Usage

get_params_1comp_fup(
  data,
  lower_bound = ggplot2::aes(Q_totli = NA, Q_gfr = NA, Fup = 0, Clint = 0, Vdist = 0.01,
    Fgutabs = 0, kgutabs = log(2)/(2 * max(Time_trans)), Fgutabs_Vdist = 0.01,
    Rblood2plasma = 0.01),
  upper_bound = ggplot2::aes(Q_totli = NA, Q_gfr = NA, Fup = 1, Clint = 1e+05, Vdist =
    100, Fgutabs = 1, kgutabs = log(2)/(0.5 * min(Time_trans[Time_trans > 0])),
    Fgutabs_Vdist = 100, Rblood2plasma = 100),
  param_units = ggplot2::aes(Q_totli = "L/h/kg ^3/4", Q_gfr = "L/h/kg ^3/4", Fup =
    "unitless fraction", Clint = "L/h/kg", Vdist = paste0("(", unique(Dose.Units), ")",
    "/", "(", unique(Conc.Units), ")"), Fgutabs = "unitless fraction", kgutabs =
    paste0("1/", unique(Time_trans.Units)), Fgutabs_Vdist = paste0("(",
    unique(Conc.Units), ")", "/", "(", unique(Dose.Units), ")"), Rblood2plasma =
    "unitless ratio")
)

Arguments

Details

The full set of model parameters for the 1-compartment model includes 'Vdist', 'Clint', 'kgutabs', 'Fgutabs', 'Q_totli', 'Q_gfr', 'Fup', and 'Rblood2plasma'. Whether each one can be estimated from the data depends on which routes of administration are included in the data.

# Constant parameters from 'httk' 'Q_totli' is the flow through the portal vein from the gut to the liver and is estimated in this model via [httk::tissue.data] in a species-specific manner. 'Q_gfr' is the glomular filtration rate of kidneys. It is estimated via [httk::physiology.data] in a species specific manner. 'Fup' and 'Rblood2plasma' are both calculated in [httk::parameterize_1comp()] For each of these parameters default lower bounds are 10

# IV data, no oral data

If IV dosing data are available, but no oral dosing data are available, then only the parameters 'Vdist' and 'kelim' will be estimated from the data. The parameters 'kgutabs' and 'Fgutabs' cannot be estimated from IV data alone, and will not be used in evaluating the model.

# Oral data, no IV data

If oral dosing data are available, but no IV dosing data are available, then the parameters 'kelim' and 'kgutabs' can be estimated from the data. However, the parameters 'Fgutabs' and 'Vdist' cannot be identified separately. From oral data alone, only the ratio 'Fgutabs/Vdist' can be identified. This ratio is represented by a single parameter named 'Fgutabs_Vdist'. 'Fgutabs' and 'Vdist' will not be used to evaluate the model nor be estimated from data, but 'Fgutabs_Vdist' will be estimated from data, along with 'kelim' and 'kgutabs'.

# Oral data and IV data

If both oral and IV dosing data are available, then 'Vdist', 'kelim', 'kgutabs', and 'Fgutabs' will all be estimated from the data.

# Blood and plasma data

If both blood and plasma data are available, then 'Rblood2plasma' will be estimated from the data.

# Only one of blood or plasma data

If only one of blood or plasma data are available, then 'Rblood2plasma' will be held constant at 1, not estimated from the data.

# Default lower and upper bounds for each parameter

## Default lower and upper bounds for 'kelim' and 'kgutabs'

Default bounds for time constants 'kelim' and 'kgutabs' are set based on the time scale of the available data.

The lower bounds are based on the assumption that elimination and absorption are very slow compared to the time scale of the study. Specifically, the lower bounds assume that elimination and absorption half-lives are twice as long as the duration of the available study data, or '2*max(Time_trans)'. Under this assumption, the corresponding elimination and absorption time constants would be 'log(2)/(2*max(Time_trans))'. Therefore, the default lower bounds for 'kelim' and 'kgutabs' are 'log(2)/(2*max(Time_trans))'.

Upper bounds are based on the opposite assumption: that elimination and absorption are very fast compared to the time scale of the study. Specifically, the upper bounds assume that the elimination and absorption half-lives are half as long as the time of the first observation after time 0, or '0.5*min(Time_trans[Time_trans>0])'. Under this asumption, the corresponding elimination and absorption time constants would be 'log(2)/(0.5*min(Time_trans[Time_trans>0]))'. Therefore, the default lower bounds for 'kelim' and 'kgutabs' are 'log(2)/(0.5*min(Time_trans[Time_trans>0]))'.

## Default lower and upper bounds for 'Vdist'

By default, the lower bound for 'Vdist' is 0.01, and the upper bound for 'Vdist' is 100. These values were chosen based on professional judgment.

## Default lower and upper bounds for 'Fgutabs'

By default, the lower bound for 'Fgutabs' is 0.0, and the upper bound for 'Fgutabs' is 1. These are simply the bounds of the physically-meaningful range for a fraction.

## Default lower and upper bounds for 'Fgutabs_Vdist'

By default, the lower bound for the ratio 'Fgutabs_Vdist' is 0.01, and the upper bound is 100. These values were chosen based on professional judgment.

## Default lower and upper bounds for 'Rblood2plasma'

By default, the lower bound for the blood:plasma partition coefficient 'Rblood2plasma' is 0.01, and the upper bound is 100. These values were chosen based on professional judgment.

# Starting values for each parameter

Starting values for each parameter (starting guesses for the numerical optimizer) are derived from the data using [get_starts_1comp()].

If the starting values returned by [get_starts_1comp()] fall outside the bounds for any parameter(s), then the starting value will be reset to a value halfway between the lower and upper bounds for that parameter.

Value

A 'data.frame'with the following variables: - 'param_name': Character: Names of the model parameters - 'param_units': Character: Units of the model parameters - 'optimize_param': TRUE if each parameter is to be estimated from the data; FALSE otherwise - 'use_param': TRUE if each parameter is to be used in evaluating the model; FALSE otherwise -'lower_bounds': Numeric: The lower bounds for each parameter - 'upper_bounds': Numeric: The upper bounds for each parameter - 'start': Numeric: The starting guesses for each parameter

Author(s)

Caroline Ring, Gilberto Padilla Mercado

See Also

Other 1-compartment model functions: auc_1comp(), auc_1comp_cl(), cp_1comp(), cp_1comp_cl(), get_params_1comp(), get_params_1comp_cl(), get_starts_1comp(), get_starts_1comp_cl(), get_starts_1comp_fup()

Other get_params functions: get_params_1comp(), get_params_1comp_cl(), get_params_2comp(), get_params_flat()

Other built-in model functions: auc_1comp(), auc_1comp_cl(), auc_2comp(), auc_flat(), cp_1comp(), cp_1comp_cl(), cp_2comp(), cp_2comp_dt(), cp_flat(), get_params_1comp(), get_params_1comp_cl(), get_params_2comp(), get_params_flat(), get_starts_1comp(), get_starts_1comp_cl(), get_starts_1comp_fup(), get_starts_2comp(), get_starts_flat(), tkstats_2comp(), transformed_params_2comp()

Get parameters for 2-compartment model

Description

Get parameters for 2-compartment model and determine whether each is to be estimated from the data

Usage

get_params_2comp(
  data,
  lower_bound = ggplot2::aes(kelim = log(2)/(2 * max(Time_trans)), k12 = log(2)/(2 *
    max(Time_trans)), k21 = log(2)/(2 * max(Time_trans)), V1 = 0.01, Fgutabs = 0, kgutabs
    = log(2)/(2 * max(Time_trans)), Fgutabs_V1 = 0.01, Rblood2plasma = 0.01),
  upper_bound = ggplot2::aes(kelim = log(2)/(0.5 * min(Time_trans[Time_trans > 0])), k12
    = log(2)/(0.5 * min(Time_trans[Time_trans > 0])), k21 = log(2)/(0.5 *
    min(Time_trans[Time_trans > 0])), V1 = 100, Fgutabs = 1, kgutabs = log(2)/(0.5 *
    min(Time_trans[Time_trans > 0])), Fgutabs_V1 = 100, Rblood2plasma = 100),
  param_units = ggplot2::aes(kelim = paste0("1/", unique(Time_trans.Units)), V1 =
    paste0("(", unique(Dose.Units), ")", "/", "(", unique(Conc.Units), ")"), k21 =
    paste0("1/", unique(Time_trans.Units)), k12 = paste0("1/", unique(Time_trans.Units)),
    Fgutabs = "unitless fraction", kgutabs = paste0("1/", unique(Time_trans.Units)),
    Fgutabs_V1 = paste0("(", unique(Conc.Units), ")", "/", "(", unique(Dose.Units), ")"),
    Rblood2plasma = "unitless ratio")
)

Arguments

Details

The full set of model parameters for the 2-compartment model includes 'V1', 'kelim', 'k12', 'k21', 'kgutabs','Fgutabs', and 'Rblood2plasma'. Whether each one can be estimated from the data depends on what routes of administration are included in the data.

## IV data, no oral data

If IV dosing data are available, but no oral dosing data are available, then only the parameters 'V1', 'kelim', 'k12', and 'k21' will be estimated from the data. The parameters 'kgutabs' and 'Fgutabs' cannot be estimated from IV data alone.

## Oral data, no IV data

If oral dosing data are available, but no IV dosing data are available, then the parameters 'kelim', 'k12', 'k21', and 'kgutabs' will be estimated from the data. However, the parameters 'Fgutabs' and 'V1' cannot be identified separately. From oral data alone, only the ratio 'Fgutabs/V1' can be identified. This ratio is represented by a single parameter named 'Fgutabs_V1'. 'Fgutabs' and 'V1' will not be optimized, but 'Fgutabs_V1' will be optimized, along with 'kelim', 'k12', 'k21', and 'kgutabs'.

## Oral data and IV data

If both oral and IV dosing data are available, then 'V1', 'kelim', 'k12', 'k21', 'kgutabs', and 'Fgutabs' will all be estimated from the data.

# Blood and plasma data

If both blood and plasma data are available, then 'Rblood2plasma' will be estimated from the data.

# Only one of blood or plasma data

If only one of blood or plasma data are available, then 'Rblood2plasma' will be held constant at 1, not estimated from the data.

# Default lower and upper bounds for each parameter

## Default lower and upper bounds for time constants 'kelim', 'kgutabs', 'k12', and 'k21'.

Default bounds for time constants 'kelim' and 'kgutabs' are set based on the time scale of the available data.

The lower bounds are based on the assumption that elimination, absorption, and distribution are very slow compared to the time scale of the study. Specifically, the lower bounds assume thatelimination, absorption, and distribution half-lives are twice as long as the duration of the available study data, or '2*max(Time_trans)'. Under this assumption, the corresponding elimination, absorption, and distribution time constants would be 'log(2)/(2*max(Time_trans))'. Therefore, the default lower bounds for 'kelim', 'kgutabs', 'k12', and 'k21' are 'log(2)/(2*max(Time_trans))'.

Upper bounds are based on the opposite assumption: that elimination, absorption, and distribution are very fast compared to the time scale of the study. Specifically, the upper bounds assume that the elimination, absorption, and distribution half-lives are half as long as the time of the first observation after time 0, or '0.5*min(Time_trans[Time_trans>0])'. Under this assumption, the correspondingelimination, absorption, and distribution time constants would be 'log(2)/(0.5*min(Time_trans[Time_trans>0]))'. Therefore, the default lower bounds for 'kelim', 'kgutabs', 'k12', and 'k21' are 'log(2)/(0.5*min(Time_trans[Time_trans>0]))'.

## Default lower and upper bounds for 'V1'

By default, the lower bound for 'V1' is 0.01, and the upper bound for 'V1' is 100. These values were chosen based on professional judgment.

## Default lower and upper bounds for 'Fgutabs'

By default, the lower bound for 'Fgutabs' is 0.0, and the upper bound for 'Fgutabs' is 1. These are simply the bounds of the physically-meaningful range for a fraction.

## Default lower and upper bounds for 'Fgutabs_V1'

By default, the lower bound for the ratio 'Fgutabs_V1' is 0.01, and the upper bound is 100. These values were chosen based on professional judgment.

## Default lower and upper bounds for 'Rblood2plasma'

By default, the lower bound for the blood:plasma partition coefficient 'Rblood2plasma' is 0.01, and the upper bound is 100. These values were chosen based on professional judgment.

# Starting values for each parameter

Starting values for each parameter (starting guesses for the numerical optimizer) are derived from the data using [get_starts_2comp()].

If the starting values returned by [get_starts_2comp()] fall outside the bounds for any parameter(s), then the starting value will be reset to a value halfway between the lower and upper bounds for that parameter.

Value

A 'data.frame'with the following variables: - 'param_name': Character: Names of the model parameters - 'param_units': Character: Units of the model parameters - 'optimize_param': TRUE if each parameter is to be estimated from the data; FALSE otherwise - 'use_param': TRUE if each parameter is to be used in evaluating the model; FALSE otherwise -'lower_bounds': Numeric: The lower bounds for each parameter - 'upper_bounds': Numeric: The upper bounds for each parameter - 'start': Numeric: The starting guesses for each parameter

Author(s)

Caroline Ring

See Also

Other 2-compartment model functions: auc_2comp(), cp_2comp(), cp_2comp_dt(), get_starts_2comp(), tkstats_2comp(), transformed_params_2comp()

Other get_params functions: get_params_1comp(), get_params_1comp_cl(), get_params_1comp_fup(), get_params_flat()

Other built-in model functions: auc_1comp(), auc_1comp_cl(), auc_2comp(), auc_flat(), cp_1comp(), cp_1comp_cl(), cp_2comp(), cp_2comp_dt(), cp_flat(), get_params_1comp(), get_params_1comp_cl(), get_params_1comp_fup(), get_params_flat(), get_starts_1comp(), get_starts_1comp_cl(), get_starts_1comp_fup(), get_starts_2comp(), get_starts_flat(), tkstats_2comp(), transformed_params_2comp()

Get parameters to be optimized for flat model

Description

The full set of model parameters for the flat model includes 'Vdist', 'Fgutabs', and 'Rblood2plasma'. Whether each one can be estimated from the data depends on what routes of administration are included in the data.

Usage

get_params_flat(
  data,
  lower_bound = ggplot2::aes(Vdist = 0.01, Fgutabs = 0, Fgutabs_Vdist = 0.01,
    Rblood2plasma = 0.01),
  upper_bound = ggplot2::aes(Vdist = 100, Fgutabs = 1, Fgutabs_Vdist = 100, Rblood2plasma
    = 100),
  param_units = ggplot2::aes(Vdist = paste0("(", unique(Dose.Units), ")", "/", "(",
    unique(Conc.Units), ")"), Fgutabs = "unitless fraction", Fgutabs_Vdist = paste0("(",
    unique(Conc.Units), ")", "/", "(", unique(Dose.Units), ")"), Rblood2plasma =
    "unitless ratio")
)

Arguments

Details

## IV data, no oral data

If IV dosing data are available, but no oral dosing data are available, then only the parameter 'Vdist' will be estimated from the data. The parameter 'Fgutabs' cannot be estimated from IV data alone and will not be used to evaluate the model.

## Oral data, no IV data

If oral dosing data are available, but no IV dosing data are available, then the parameters 'Fgutabs' and 'Vdist' cannot be identified separately. From oral data alone, only the ratio 'Fgutabs/Vdist' can be identified. This ratio is represented by a single parameter named 'Fgutabs_Vdist'. 'Fgutabs' and 'Vdist' will not be estimated nor used in model evaluation, but 'Fgutabs_Vdist' will be estimated.

## Oral data and IV data

If both oral and IV dosing data are available, then 'Vdist' and 'Fgutabs' will both be estimated from the data.

# Blood and plasma data

If both blood and plasma data are available, then 'Rblood2plasma' will be estimated from the data.

# Only one of blood or plasma data

If only one of blood or plasma data are available, then 'Rblood2plasma' will be held constant at 1, not estimated from the data.

# Default lower and upper bounds for each parameter

## Default lower and upper bounds for 'Vdist'

By default, the lower bound for 'Vdist' is 0.01, and the upper bound for 'Vdist' is 100. These values were chosen based on professional judgment.

## Default lower and upper bounds for 'Fgutabs'

By default, the lower bound for 'Fgutabs' is 0.0, and the upper bound for 'Fgutabs' is 1. These are simply the bounds of the physically-meaningful range for a fraction.

## Default lower and upper bounds for 'Fgutabs_Vdist'

By default, the lower bound for the ratio 'Fgutabs_Vdist' is 0.01, and the upper bound is 100. These values were chosen based on professional judgment.

## Default lower and upper bounds for 'Rblood2plasma'

By default, the lower bound for the blood:plasma partition coefficient 'Rblood2plasma' is 0.01, and the upper bound is 100. These values were chosen based on professional judgment.

# Starting values for each parameter

Starting values for each parameter (starting guesses for the numerical optimizer) are derived from the data using [get_starts_flat()].

If the starting values returned by [get_starts_flat()] fall outside the bounds for any parameter(s), then the starting value will be reset to a value halfway between the lower and upper bounds for that parameter.

Value

A 'data.frame'with the following variables: - 'param_name': Character: Names of the model parameters - 'param_units': Character: Units of the model parameters - 'optimize_param': TRUE if each parameter is to be estimated from the data; FALSE otherwise - 'use_param': TRUE if each parameter is to be used in evaluating the model; FALSE otherwise -'lower_bounds': Numeric: The lower bounds for each parameter - 'upper_bounds': Numeric: The upper bounds for each parameter - 'start': Numeric: The starting guesses for each parameter

Author(s)

Caroline Ring

See Also

Other flat model functions: auc_flat(), cp_flat(), get_starts_flat()

Other get_params functions: get_params_1comp(), get_params_1comp_cl(), get_params_1comp_fup(), get_params_2comp()

Other built-in model functions: auc_1comp(), auc_1comp_cl(), auc_2comp(), auc_flat(), cp_1comp(), cp_1comp_cl(), cp_2comp(), cp_2comp_dt(), cp_flat(), get_params_1comp(), get_params_1comp_cl(), get_params_1comp_fup(), get_params_2comp(), get_starts_1comp(), get_starts_1comp_cl(), get_starts_1comp_fup(), get_starts_2comp(), get_starts_flat(), tkstats_2comp(), transformed_params_2comp()

Find the peak of a data series

Description

Finds x- and y-value at peak y value.

Usage

get_peak(x, y, ties = "median", na.rm = TRUE, ...)

Arguments

Details

If there is more than one unique 'x' value where both 'x' and corresponding ‘y' are finite, this function calls [stats::approx()] with 'method = ’linear'', then uses [base::which.max()] to locate the maximum interpolated 'y'-value.

If there is only one unique 'x' value where both 'x' and corresponding 'y' are finite, this function calls [stats::approx()] with ‘method = ’constant'', then uses [base::which.max()] to locate the maximum interpolated 'y'-value.

If there are no unique 'x' values where both 'x' and corresponding 'y' are finite, this function returns 'NA_real_' for the peak 'x' and 'y' values.

Value

A list with two named numeric scalar components, 'x' and 'y', containing the x- and y-values at the peak.

Author(s)

Caroline Ring

get_prefit()

Description

This is the S3 method generic for get_prefit()

Usage

get_prefit(obj, ...)

Arguments

Value

A list of ‘data.frame's in the object’s 'prefit' element.

See Also

[get_prefit.pk()] for the method for class [pk()]

Default method for get_prefit()

Description

Default method for get_prefit()

Usage

## Default S3 method:
get_prefit(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Get prefit

Description

Extract pre-fitting results from a [pk()] object

Usage

## S3 method for class 'pk'
get_prefit(obj, ...)

Arguments

Value

A list of ‘data.frame's in the object’s 'prefit' element.

Author(s)

Caroline Ring

get_scale_conc()

Description

This is the S3 method generic for get_scale_conc()

Usage

get_scale_conc(obj, ...)

Arguments

Value

A 'list': 'obj$scales$conc'

See Also

[get_scale_conc.pk()] for the method for class [pk()]

Default method for get_scale_conc()

Description

Default method for get_scale_conc()

Usage

## Default S3 method:
get_scale_conc(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Get scale_conc

Description

Extract concentration scale/transformation instructions from a [pk()] object

Usage

## S3 method for class 'pk'
get_scale_conc(obj, ...)

Arguments

Value

A 'list': 'obj$scales$conc'

Author(s)

Caroline Ring

get_scale_time()

Description

This is the S3 method generic for get_scale_time()

Usage

get_scale_time(obj, ...)

Arguments

Value

A 'list': 'obj$scales$time'

See Also

[get_scale_time.pk()] for the method for class [pk()]

Default method for get_scale_time()

Description

Default method for get_scale_time()

Usage

## Default S3 method:
get_scale_time(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Get scale_time

Description

Extract time scale/transformation instructions from a [pk()] object

Usage

## S3 method for class 'pk'
get_scale_time(obj, ...)

Arguments

Value

A 'list': 'obj$scales$time'

Author(s)

Caroline Ring

get_settings_data_info()

Description

This is the S3 method generic for get_settings_data_info()

Usage

get_settings_data_info(obj, ...)

Arguments

Value

A named list of the data_info settings

See Also

[get_settings_data_info.pk()] for the method for class [pk()]

Default method for get_settings_data_info()

Description

Default method for get_settings_data_info()

Usage

## Default S3 method:
get_settings_data_info(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Get settings_data_info

Description

Get settings_data_info

Usage

## S3 method for class 'pk'
get_settings_data_info(obj, ...)

Arguments

Value

A named list of the data_info settings

Author(s)

Caroline Ring

get_settings_optimx()

Description

This is the S3 method generic for get_settings_optimx()

Usage

get_settings_optimx(obj, ...)

Arguments

Value

A named list of the optimx settings

See Also

[get_settings_optimx.pk()] for the method for class [pk()]

Default method for get_settings_optimx()

Description

Default method for get_settings_optimx()

Usage

## Default S3 method:
get_settings_optimx(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Get settings_optimx

Description

Get settings_optimx

Usage

## S3 method for class 'pk'
get_settings_optimx(obj, ...)

Arguments

Value

A named list of the optimx settings

Author(s)

Caroline Ring

get_settings_preprocess()

Description

This is the S3 method generic for get_settings_preprocess()

Usage

get_settings_preprocess(obj, ...)

Arguments

Value

A named list of the preprocessing settings

See Also

[get_settings_preprocess.pk()] for the method for class [pk()]

Default method for get_settings_preprocess()

Description

Default method for get_settings_preprocess()

Usage

## Default S3 method:
get_settings_preprocess(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Get settings_preprocess

Description

Get settings_preprocess

Usage

## S3 method for class 'pk'
get_settings_preprocess(obj, ...)

Arguments

Value

A named list of the preprocessing settings

Author(s)

Caroline Ring

Get starting values for 1-compartment model

Description

Derive starting values for 1-compartment model parameters from available data

Usage

get_starts_1comp(data, par_DF)

Arguments

Details

This function is called internally by [get_params_1comp()] and should generally not be called directly by the user.

The full set of model parameters for the 1-compartment model includes 'Vdist', 'kelim', 'kgutabs', 'Fgutabs', and 'Rblood2plasma'. Whether each one can be estimated from the data depends on what routes of administration are included in the data.

The numerical optimizer requires starting guesses for the value of each parameter to be estimated from the data. Default starting guesses are derived from the available data.

These are intended to be *very* rough starting guesses, so the algorithm here is extremely naive. This function is not itself intended to produce valid estimates for any of the model parameters, and it is highly unlikely to do so.

The derivation process is as follows.

First, data are filtered to exclude any non-detects.

Then, data are split by route of administration, into an IV data set and an oral data set. (It is possible that either IV or oral data may not be available for a chemical.)

# Starting value for 'kelim'

If IV data exist, then only IV data are used to derive starting estimates for 'kelim', even if oral data also exist.

If only oral data exist, then the oral data are used to derive a starting estimate for 'kelim'.

Whichever data set is used (IV or oral), the starting value for 'kelim' is derived by assuming that the range of observed time values in the data set spans two elimination half-lives. This implies that the elimination half-life is equal to the midpoint of observed time values, and that the starting value for the elimination time constant 'kelim' is therefore 'log(2)' divided by the midpoint of observed time values.

Of course, this assumption is unlikely to be correct. However, we hope that it will yield a starting guess for 'kelim' that is at least on the right order of magnitude.

# Starting value for 'Vdist'

If IV data exist, then only IV data are used to derive a starting estimate for 'Vdist'.

This starting estimate is derived by assuming that the IV data obey a one-compartment model, which means that when concentrations are dose-normalized and log10-transformed and plotted against time, they will follow a straight line with slope '-kelim'.

First, concentrations are dose-normalized by dividing them by their corresponding doses. Then the normalized concentrations are log10-transformed.

From all observations at the earliest observed time point in the data set (call it 'tmin'), the median of the dose-normalized, log10-transformed concentrations is calculated; call it 'C_tmin'. (The median is used, rather than the mean, in an attempt to be more robust to outliers.)

If the earliest observed time point is not at time = 0, then the dose-normalized, log10-transformed concentration at time = 0 is extrapolated by drawing a straight line with slope '-kelim' back from 'C_tmin', where the value of 'kelim' is the starting value derived as in the previous section.

This extrapolated concentration at time t = 0 is called 'A_log10'. 'A_log10' represents the expected body concentration immediately after IV injection of a unit dose (under the assumption that TK obeys a one-compartment model).

Then, the volume of distribution 'Vdist' is derived as '1/(10^A_log10)'. In other words, 'Vdist' is the volume that would be required to produce a concentration equal to 'A_log10' after injecting a unit dose.

(No starting value for 'Vdist' can be derived with only oral data, but none is needed, because with only oral data, 'Vdist' will not be estimated from the data).

# Starting value for 'kgutabs'

If oral data exist (whether or not IV data also exist), then the oral data are used to derive a starting value for 'kgutabs'.

First, concentrations are dose-normalized by dividing them by their corresponding doses. Then the normalized concentrations are log10-transformed.

The time of peak concentration ('tmax'), and the median (normalized, log-transformed) peak concentration ('Cmax_log10'), are identified using [get_peak()].

As a very rough guess,'tmax' is assumed to occur at one absorption half-life. Under this assumption, 'kgutabs' is equal to 'log(2)/tmax', and this is taken as the starting value.

# Starting value for 'Fgutabs_Vdist'

If any oral data exist (whether or not IV data also exist), then the oral data are used to derive a starting value for 'Fgutabs_Vdist'.

If the kinetics obey a one-compartment model, then if concentrations are dose-normalized, log-transformed, and plotted vs. time, then at late time points (after concentration has peaked), the concentration vs. time relationship will approach a straight line with slope '-kelim'.

If this straight line is extrapolated back to time 0, then the resulting intercept (call it 'A'), expressed on the natural scale, is equal to 'Fgutabs_Vdist * kgutabs/(kgutabs-kelim)'. See https://www.boomer.org/c/p4/c09/c0902.php .

Roughly, we approximate 'A' on the log10 scale by extrapolating back from the peak along a straight line with slope '-kelim', using the previously-derived starting value for 'kelim'. So 'log10(A) = Cmax_log10 + kelim*tmax'.

Using the previously-derived starting values for 'kgutabs' and 'kelim', then, the starting value for 'Fgutabs_Vdist' can be derived as 'A * (kgutabs-kelim)/kgutabs'.

# Starting value for 'Fgutabs'

If both oral and IV data exist, then the derived starting values for 'Vdist' (from the IV data) and 'Fgutabs_Vdist' (from the oral data) are multiplied to yield a derived starting value for 'Fgutabs'.

#Starting value for 'Rblood2plasma'

The starting value for 'Rblood2plasma' is always set at a constant 1.

Value

The same 'data.frame' as 'par_DF', with an additional variable 'starts' containing the derived starting value for each parameter. If a parameter cannot be estimated from the available data, then its starting value will be 'NA_real_'

Author(s)

Caroline Ring

See Also

Other 1-compartment model functions: auc_1comp(), auc_1comp_cl(), cp_1comp(), cp_1comp_cl(), get_params_1comp(), get_params_1comp_cl(), get_params_1comp_fup(), get_starts_1comp_cl(), get_starts_1comp_fup()

Other get_starts functions: get_starts_1comp_cl(), get_starts_1comp_fup(), get_starts_2comp(), get_starts_flat()

Other built-in model functions: auc_1comp(), auc_1comp_cl(), auc_2comp(), auc_flat(), cp_1comp(), cp_1comp_cl(), cp_2comp(), cp_2comp_dt(), cp_flat(), get_params_1comp(), get_params_1comp_cl(), get_params_1comp_fup(), get_params_2comp(), get_params_flat(), get_starts_1comp_cl(), get_starts_1comp_fup(), get_starts_2comp(), get_starts_flat(), tkstats_2comp(), transformed_params_2comp()

Get starting values for 1-compartment model with specific clearance

Description

Derive starting values for 1-compartment model parameters from available data

Usage

get_starts_1comp_cl(data, par_DF, restrictive)

Arguments

Details

This function is called internally by [get_params_1comp()] and should generally not be called directly by the user.

The full set of model parameters for the 1-compartment model includes 'Vdist', 'kelim', 'kgutabs', 'Fgutabs', and 'Rblood2plasma'. Whether each one can be estimated from the data depends on what routes of administration are included in the data. However, in this version of the one-compartment model, we use the liver and glomerular flow rates ('Q_totli' and 'Q_gfr', respectively) provided by [httk] as well as intrisic clearance 'Clint' and fraction unbound in plasma, 'Fup'. These starting values are established and then are used to calculate the other parameters in the 1-compartment model.

The numerical optimizer requires starting guesses for the value of each parameter to be estimated from the data. Default starting guesses are derived from the available data.

These are intended to be *very* rough starting guesses, so the algorithm here is extremely naive. This function is not itself intended to produce valid estimates for any of the model parameters, and it is highly unlikely to do so.

The derivation process is as follows.

First, data are filtered to exclude any non-detects.

Then, data are split by route of administration, into an IV data set and an oral data set. (It is possible that either IV or oral data may not be available for a chemical.)

# Starting value for 'kelim'

If IV data exist, then only IV data are used to derive starting estimates for 'kelim', even if oral data also exist.

If only oral data exist, then the oral data are used to derive a starting estimate for 'kelim'.

Whichever data set is used (IV or oral), the starting value for 'kelim' is derived by assuming that the range of observed time values in the data set spans two elimination half-lives. This implies that the elimination half-life is equal to the midpoint of observed time values, and that the starting value for the elimination time constant 'kelim' is therefore 'log(2)' divided by the midpoint of observed time values.

Of course, this assumption is unlikely to be correct. However, we hope that it will yield a starting guess for 'kelim' that is at least on the right order of magnitude.

# Starting value for 'Vdist'

Using a calculated value for total clearance, 'Cl_tot', 'Vdist' is estimated by dividing this by the estimation of 'kelim'.

# Starting value for 'kgutabs'

If oral data exist (whether or not IV data also exist), then the oral data are used to derive a starting value for 'kgutabs'.

First, concentrations are dose-normalized by dividing them by their corresponding doses. Then the normalized concentrations are log10-transformed.

The time of peak concentration ('tmax'), and the median (normalized, log-transformed) peak concentration ('Cmax_log10'), are identified using [get_peak()].

As a very rough guess,'tmax' is assumed to occur at one absorption half-life. Under this assumption, 'kgutabs' is equal to 'log(2)/tmax', and this is taken as the starting value.

# Starting value for 'Fgutabs_Vdist'

If any oral data exist (whether or not IV data also exist), then the oral data are used to derive a starting value for 'Fgutabs_Vdist'.

If the kinetics obey a one-compartment model, then if concentrations are dose-normalized, log-transformed, and plotted vs. time, then at late time points (after concentration has peaked), the concentration vs. time relationship will approach a straight line with slope '-kelim'.

If this straight line is extrapolated back to time 0, then the resulting intercept (call it 'A'), expressed on the natural scale, is equal to 'Fgutabs_Vdist * kgutabs/(kgutabs-kelim)'. See https://www.boomer.org/c/p4/c09/c0902.php .

Roughly, we approximate 'A' on the log10 scale by extrapolating back from the peak along a straight line with slope '-kelim', using the previously-derived starting value for 'kelim'. So 'log10(A) = Cmax_log10 + kelim*tmax'.

Using the previously-derived starting values for 'kgutabs' and 'kelim', then, the starting value for 'Fgutabs_Vdist' can be derived as 'A * (kgutabs-kelim)/kgutabs'.

# Starting value for 'Fgutabs'

If both oral and IV data exist, then the derived starting values for 'Vdist' (from the IV data) and 'Fgutabs_Vdist' (from the oral data) are multiplied to yield a derived starting value for 'Fgutabs'.

#Starting value for 'Rblood2plasma'

The starting value for 'Rblood2plasma' is set to the value given by [httk::parameterize_gas_pbtk()].

Value

The same 'data.frame' as 'par_DF', with an additional variable 'starts' containing the derived starting value for each parameter. If a parameter cannot be estimated from the available data, then its starting value will be 'NA_real_'

Author(s)

Caroline Ring

See Also

Other 1-compartment model functions: auc_1comp(), auc_1comp_cl(), cp_1comp(), cp_1comp_cl(), get_params_1comp(), get_params_1comp_cl(), get_params_1comp_fup(), get_starts_1comp(), get_starts_1comp_fup()

Other get_starts functions: get_starts_1comp(), get_starts_1comp_fup(), get_starts_2comp(), get_starts_flat()

Other built-in model functions: auc_1comp(), auc_1comp_cl(), auc_2comp(), auc_flat(), cp_1comp(), cp_1comp_cl(), cp_2comp(), cp_2comp_dt(), cp_flat(), get_params_1comp(), get_params_1comp_cl(), get_params_1comp_fup(), get_params_2comp(), get_params_flat(), get_starts_1comp(), get_starts_1comp_fup(), get_starts_2comp(), get_starts_flat(), tkstats_2comp(), transformed_params_2comp()

Get starting values for 1-compartment model with specific clearance

Description

Derive starting values for 1-compartment model parameters from available data

Usage

get_starts_1comp_fup(data, par_DF)

Arguments

Details

This function is called internally by [get_params_1comp()] and should generally not be called directly by the user.

The full set of model parameters for the 1-compartment model includes 'Vdist', 'kelim', 'kgutabs', 'Fgutabs', and 'Rblood2plasma'. Whether each one can be estimated from the data depends on what routes of administration are included in the data. However, in this version of the one-compartment model, we use the liver and glomerular flow rates ('Q_totli' and 'Q_gfr', respectively) provided by [httk] as well as intrisic clearance 'Clint' and fraction unbound in plasma, 'Fup'. These starting values are established and then are used to calculate the other parameters in the 1-compartment model.

The numerical optimizer requires starting guesses for the value of each parameter to be estimated from the data. Default starting guesses are derived from the available data.

These are intended to be *very* rough starting guesses, so the algorithm here is extremely naive. This function is not itself intended to produce valid estimates for any of the model parameters, and it is highly unlikely to do so.

The derivation process is as follows.

First, data are filtered to exclude any non-detects.

Then, data are split by route of administration, into an IV data set and an oral data set. (It is possible that either IV or oral data may not be available for a chemical.)

# Starting value for 'kelim'

If IV data exist, then only IV data are used to derive starting estimates for 'kelim', even if oral data also exist.

If only oral data exist, then the oral data are used to derive a starting estimate for 'kelim'.

Whichever data set is used (IV or oral), the starting value for 'kelim' is derived by assuming that the range of observed time values in the data set spans two elimination half-lives. This implies that the elimination half-life is equal to the midpoint of observed time values, and that the starting value for the elimination time constant 'kelim' is therefore 'log(2)' divided by the midpoint of observed time values.

Of course, this assumption is unlikely to be correct. However, we hope that it will yield a starting guess for 'kelim' that is at least on the right order of magnitude.

# Starting value for 'Vdist'

Using a calculated value for total clearance, 'Cl_tot', 'Vdist' is estimated by dividing this by the estimation of 'kelim'.

# Starting value for 'kgutabs'

If oral data exist (whether or not IV data also exist), then the oral data are used to derive a starting value for 'kgutabs'.

First, concentrations are dose-normalized by dividing them by their corresponding doses. Then the normalized concentrations are log10-transformed.

The time of peak concentration ('tmax'), and the median (normalized, log-transformed) peak concentration ('Cmax_log10'), are identified using [get_peak()].

As a very rough guess,'tmax' is assumed to occur at one absorption half-life. Under this assumption, 'kgutabs' is equal to 'log(2)/tmax', and this is taken as the starting value.

# Starting value for 'Fgutabs_Vdist'

If any oral data exist (whether or not IV data also exist), then the oral data are used to derive a starting value for 'Fgutabs_Vdist'.

If the kinetics obey a one-compartment model, then if concentrations are dose-normalized, log-transformed, and plotted vs. time, then at late time points (after concentration has peaked), the concentration vs. time relationship will approach a straight line with slope '-kelim'.

If this straight line is extrapolated back to time 0, then the resulting intercept (call it 'A'), expressed on the natural scale, is equal to 'Fgutabs_Vdist * kgutabs/(kgutabs-kelim)'. See https://www.boomer.org/c/p4/c09/c0902.php .

Roughly, we approximate 'A' on the log10 scale by extrapolating back from the peak along a straight line with slope '-kelim', using the previously-derived starting value for 'kelim'. So 'log10(A) = Cmax_log10 + kelim*tmax'.

Using the previously-derived starting values for 'kgutabs' and 'kelim', then, the starting value for 'Fgutabs_Vdist' can be derived as 'A * (kgutabs-kelim)/kgutabs'.

# Starting value for 'Fgutabs'

If both oral and IV data exist, then the derived starting values for 'Vdist' (from the IV data) and 'Fgutabs_Vdist' (from the oral data) are multiplied to yield a derived starting value for 'Fgutabs'.

#Starting value for 'Rblood2plasma'

The starting value for 'Rblood2plasma' is set to the value given by [httk::parameterize_gas_pbtk()].

Value

The same 'data.frame' as 'par_DF', with an additional variable 'starts' containing the derived starting value for each parameter. If a parameter cannot be estimated from the available data, then its starting value will be 'NA_real_'

Author(s)

Caroline Ring

See Also

Other 1-compartment model functions: auc_1comp(), auc_1comp_cl(), cp_1comp(), cp_1comp_cl(), get_params_1comp(), get_params_1comp_cl(), get_params_1comp_fup(), get_starts_1comp(), get_starts_1comp_cl()

Other get_starts functions: get_starts_1comp(), get_starts_1comp_cl(), get_starts_2comp(), get_starts_flat()

Other built-in model functions: auc_1comp(), auc_1comp_cl(), auc_2comp(), auc_flat(), cp_1comp(), cp_1comp_cl(), cp_2comp(), cp_2comp_dt(), cp_flat(), get_params_1comp(), get_params_1comp_cl(), get_params_1comp_fup(), get_params_2comp(), get_params_flat(), get_starts_1comp(), get_starts_1comp_cl(), get_starts_2comp(), get_starts_flat(), tkstats_2comp(), transformed_params_2comp()

Get starting values for 2-compartment model

Description

Derive starting values for 2-compartment model parameters from available data

Usage

get_starts_2comp(data, par_DF)

Arguments

Details

This function is called internally by [get_params_2comp()] and should generally not be called directly by the user.

The full set of model parameters for the 2-compartment model includes 'V1', 'kelim', 'k12', 'k21', 'kgutabs', and 'Fgutabs'. Whether each one can be estimated from the data depends on what routes of administration are included in the data.

The numerical optimizer requires starting guesses for the value of each parameter to be estimated from the data. Default starting guesses are derived from the available data.

These are intended to be *very* rough starting guesses, so the algorithm here is extremely naive. This function is not itself intended to produce valid estimates for any of the model parameters, and it is highly unlikely to do so.

At present, the starting guesses for the 2-compartment model are derived in the same way as for the 1-compartment model, for the parameters that are common to both. That is, the data are assumed to obey a 1-compartment model to derive starting guesses for 'kelim', 'V1', 'kgutabs', 'Fgutabs_V1', and 'Fgutabs'.

Then, starting values for 'k12' and 'k21' are arbitrarily set to 0.1 and 0.5, respectively.

The following description of the derivation process is therefore identical to that for [get_starts_1comp()].

The derivation process

First, data are filtered to exclude any non-detects.

Then, data are split by route of administration, into an IV data set and an oral data set. (It is possible that either IV or oral data may not be available for a chemical.)

# Starting value for 'kelim'

If IV data exist, then only IV data are used to derive starting estimates for 'kelim', even if oral data also exist.

If only oral data exist, then the oral data are used to derive a starting estimate for 'kelim'.

Whichever data set is used (IV or oral), the starting value for 'kelim' is derived by assuming that the range of observed time values in the data set spans two elimination half-lives. This implies that the elimination half-life is equal to the midpoint of observed time values, and that the starting value for the elimination time constant 'kelim' is therefore 'log(2)' divided by the midpoint of observed time values.

Of course, this assumption is unlikely to be correct. However, we hope that it will yield a starting guess for 'kelim' that is at least on the right order of magnitude.

# Starting value for 'V1'

If IV data exist, then only IV data are used to derive a starting estimate for 'V1'.

This starting estimate is derived by assuming that the IV data obey a one-compartment model, which means that when concentrations are dose-normalized and log10-transformed and plotted against time, they will follow a straight line with slope '-kelim'.

First, concentrations are dose-normalized by dividing them by their corresponding doses. Then the normalized concentrations are log10-transformed.

From all observations at the earliest observed time point in the data set (call it 'tmin'), the median of the dose-normalized, log10-transformed concentrations is calculated; call it 'C_tmin'. (The median is used, rather than the mean, in an attempt to be more robust to outliers.)

If the earliest observed time point is not at time = 0, then the dose-normalized, log10-transformed concentration at time = 0 is extrapolated by drawing a straight line with slope '-kelim' back from 'C_tmin', where the value of 'kelim' is the starting value derived as in the previous section.

This extrapolated concentration at time t = 0 is called 'A_log10'. 'A_log10' represents the expected body concentration immediately after IV injection of a unit dose (under the assumption that TK obeys a one-compartment model).

Then, the volume of distribution 'V1' is derived as '1/(10^A_log10)'. In other words, 'V1' is the volume that would be required to produce a concentration equal to 'A_log10' after injecting a unit dose.

(No starting value for 'V1' can be derived with only oral data, but none is needed, because with only oral data, 'V1' will not be estimated from the data).

# Starting value for 'kgutabs'

If oral data exist (whether or not IV data also exist), then the oral data are used to derive a starting value for 'kgutabs'.

First, concentrations are dose-normalized by dividing them by their corresponding doses. Then the normalized concentrations are log10-transformed.

The time of peak concentration ('tmax'), and the median (normalized, log-transformed) peak concentration ('Cmax_log10'), are identified using [get_peak()].

As a very rough guess,'tmax' is assumed to occur at one absorption half-life. Under this assumption, 'kgutabs' is equal to 'log(2)/tmax', and this is taken as the starting value.

# Starting value for 'Fgutabs_V1'

If any oral data exist (whether or not IV data also exist), then the oral data are used to derive a starting value for 'Fgutabs_V1'.

If the kinetics obey a one-compartment model, then if concentrations are dose-normalized, log-transformed, and plotted vs. time, then at late time points (after concentration has peaked), the concentration vs. time relationship will approach a straight line with slope '-kelim'.

If this straight line is extrapolated back to time 0, then the resulting intercept (call it 'A'), expressed on the natural scale, is equal to 'Fgutabs_V1 * kgutabs/(kgutabs-kelim)'. See https://www.boomer.org/c/p4/c09/c0902.php .

Roughly, we approximate 'A' on the log10 scale by extrapolating back from the peak along a straight line with slope '-kelim', using the previously-derived starting value for 'kelim'. So 'log10(A) = Cmax_log10 + kelim*tmax'.

Using the previously-derived starting values for 'kgutabs' and 'kelim', then, the starting value for 'Fgutabs_V1' can be derived as 'A * (kgutabs-kelim)/kgutabs'.

# Starting value for 'Fgutabs'

If both oral and IV data exist, then the derived starting values for 'V1' (from the IV data) and 'Fgutabs_V1' (from the oral data) are multiplied to yield a derived starting value for 'Fgutabs'. #Starting value for 'Rblood2plasma'

The starting value for 'Rblood2plasma' is always set at a constant 1.

Value

The same 'data.frame' as 'par_DF', with an additional variable 'starts' containing the derived starting value for each parameter. If a parameter cannot be estimated from the available data, then its starting value will be 'NA_real_'

Author(s)

Caroline Ring

See Also

Other 2-compartment model functions: auc_2comp(), cp_2comp(), cp_2comp_dt(), get_params_2comp(), tkstats_2comp(), transformed_params_2comp()

Other get_starts functions: get_starts_1comp(), get_starts_1comp_cl(), get_starts_1comp_fup(), get_starts_flat()

Other built-in model functions: auc_1comp(), auc_1comp_cl(), auc_2comp(), auc_flat(), cp_1comp(), cp_1comp_cl(), cp_2comp(), cp_2comp_dt(), cp_flat(), get_params_1comp(), get_params_1comp_cl(), get_params_1comp_fup(), get_params_2comp(), get_params_flat(), get_starts_1comp(), get_starts_1comp_cl(), get_starts_1comp_fup(), get_starts_flat(), tkstats_2comp(), transformed_params_2comp()

Get starting values for flat model

Description

Derive starting values for flat model parameters from available data

Usage

get_starts_flat(data, par_DF)

Arguments

Details

This function is called internally by [get_params_1comp()] and should generally not be called directly by the user.

The full set of model parameters for the flat model includes 'Vdist','Fgutabs', and 'Rblood2plasma'. Whether each one can be estimated from the data depends on what routes of administration are included in the data.

The numerical optimizer requires starting guesses for the value of each parameter to be estimated from the data. Default starting guesses are derived from the available data.

These are intended to be *very* rough starting guesses, so the algorithm here is extremely naive. This function is not itself intended to produce valid estimates for any of the model parameters, and it is highly unlikely to do so.

The derivation process is as follows.

First, data are filtered to exclude any non-detects.

Then, data are split by route of administration, into an IV data set and an oral data set. (It is possible that either IV or oral data may not be available for a chemical.)

If IV data exist, then only IV data are used to derive a starting estimate for 'Vdist'. Concentrations are dose-normalized (divided by their corresponding dose) and log10-transformed. The mean dose-normalized, log10-transformed concentration is calculated (call it 'Cmean_log10'). 'Vdist' starting value is then derived as '1/(10^Cmean_log10)' .

If any oral data exist (whether or not IV data also exist), then the oral data are used to derive a starting value for 'Fgutabs_Vdist'. Concentrations are dose-normalized (divided by their corresponding dose) and log10-transformed. The mean dose-normalized, log10-transformed concentration is calculated (call it 'Cmean_log10'). 'Fgutabs_Vdist' starting value is then set equal to '10^Cmean_log10' .

#Starting value for 'Rblood2plasma'

If both blood and plasma data are available, then the starting value for 'Rblood2plasma' is derived as follows.

If IV data are available for both blood and plasma, then the starting value for 'Rblood2plasma' is derived as the ratio of 'Vdist' for blood data and 'Vdist' for plasma data.

If oral data, but not IV data, are available for both blood and plasma, then the starting value for 'Rblood2plasma' is derived as the ratio of 'Fgutabs_Vdist' for plasma data and 'Fgutabs_Vdist' for blood data.

If only blood data or only plasma data are available, then the starting value for 'Rblood2plasma' is set at a constant 1.

Value

The same 'data.frame' as 'par_DF', with an additional variable 'starts' containing the derived starting value for each parameter. If a parameter cannot be estimated from the available data, then its starting value will be 'NA_real_'

Author(s)

Caroline Ring

See Also

Other flat model functions: auc_flat(), cp_flat(), get_params_flat()

Other get_starts functions: get_starts_1comp(), get_starts_1comp_cl(), get_starts_1comp_fup(), get_starts_2comp()

Other built-in model functions: auc_1comp(), auc_1comp_cl(), auc_2comp(), auc_flat(), cp_1comp(), cp_1comp_cl(), cp_2comp(), cp_2comp_dt(), cp_flat(), get_params_1comp(), get_params_1comp_cl(), get_params_1comp_fup(), get_params_2comp(), get_params_flat(), get_starts_1comp(), get_starts_1comp_cl(), get_starts_1comp_fup(), get_starts_2comp(), tkstats_2comp(), transformed_params_2comp()

get_stat_error_model()

Description

This is the S3 method generic for get_stat_error_model()

Usage

get_stat_error_model(obj, ...)

Arguments

Value

A named list of the stat_error_model settings

See Also

[get_stat_error_model.pk()] for the method for class [pk()]

Default method for get_stat_error_model()

Description

Default method for get_stat_error_model()

Usage

## Default S3 method:
get_stat_error_model(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Get stat_error_model

Description

Get stat_error_model

Usage

## S3 method for class 'pk'
get_stat_error_model(obj, ...)

Arguments

Value

A named list of the stat_error_model settings

Author(s)

Caroline Ring

get_stat_model()

Description

This is the S3 method generic for get_stat_model()

Usage

get_stat_model(obj, ...)

Arguments

Value

A 'list' – the 'stat_model' element of 'obj'

See Also

[get_stat_model.pk()] for the method for class [pk()]

Default method for get_stat_model()

Description

Default method for get_stat_model()

Usage

## Default S3 method:
get_stat_model(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Get stat_model

Description

Get stat_model

Usage

## S3 method for class 'pk'
get_stat_model(obj, ...)

Arguments

Value

A 'list' – the 'stat_model' element of 'obj'

Author(s)

Caroline Ring

Get status

Description

This is the S3 method generic.

Usage

get_status(obj, ...)

Arguments

Value

The status of the 'pk' object as an integer.

See Also

[get_status.pk()] for the 'get_status' method for class [pk()]

Default method for getting status

Description

Default method for getting status

Usage

## Default S3 method:
get_status(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Check status of a 'pk' object

Description

Check status of a 'pk' object

Usage

## S3 method for class 'pk'
get_status(obj, suppress.messages = NULL, ...)

Arguments

Details

'pk' objects have integer statuses reflecting what stage of the analysis process they are at.

1. Object has been initialized 2. Data pre-processing complete 3. Model pre-fitting complete 4 . Model fitting complete

If a 'pk' object of status 2 or greater has its instructions modified with '+', then its status will be reset to 1, indicating that any analysis results contained in the object are now outdated and all steps of the analysis need to be re-run.

This function allows the user to check the status of a 'pk' object.

A message will be printed listing the analysis steps that have been completed for this 'pk' object, and the integer status will be returned.

Value

The status of the 'pk' object as an integer.

Author(s)

Caroline Ring

Get TK stats

Description

This is the S3 method generic for get_tkstats(0)

Usage

get_tkstats(obj, ...)

Arguments

Value

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'.)

See Also

[get_tkstats.pk()] for the method for class [pk()]

Default method for get_tkstats()

Description

Default method for get_tkstats()

Usage

## Default S3 method:
get_tkstats(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Get TK stats

Description

Extract derived TK statistics from a fitted [pk()] model object.

Usage

## S3 method for class 'pk'
get_tkstats(
  obj,
  newdata = NULL,
  tk_group = NULL,
  model = NULL,
  method = NULL,
  exclude = TRUE,
  vol_unit = "L",
  dose_norm = TRUE,
  suppress.messages = NULL,
  ...
)

Arguments

Details

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()]

Value

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'.)

Author(s)

Caroline Ring, Gilberto Padilla Mercado

See Also

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()

get_winning_model()

Description

This is the S3 method generic for get_winning_model()

Usage

get_winning_model(obj, ...)

Arguments

Value

A data.frame with one row for each 'data_group', 'model' and 'method' and The return value has attribute 'criterion' giving the name of the criterion function used to compare models.

See Also

[get_winning_model.pk()] for the method for class [pk()]

Default method for get_winning_model()

Description

Default method for get_winning_model()

Usage

## Default S3 method:
get_winning_model(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

Get winning model

Description

Get winning model for a fitted 'pk' object

Usage

## S3 method for class 'pk'
get_winning_model(obj, newdata = NULL, method = NULL, criterion = "AIC", ...)

Arguments

Details

Get the winning model (i.e. the model with the lowest value of the criterion specified in 'criterion') for a fitted 'pk' object, for a specified method, and optionally for a specified new dataset. When there are ties it will return the first encounter, where the priority is: model_1comp > model_2comp > model_flat.

Value

A data.frame with one row for each 'data_group', 'model' and 'method' and The return value has attribute 'criterion' giving the name of the criterion function used to compare models.

Author(s)

Caroline Ring, Gilberto Padilla Mercado

Inverse diagonal, method 1

Description

Get square root of diagonal of inverse matrix, first method

Usage

hess_sd1(m)

Arguments

Details

Invert a square numeric matrix 'm' of size n \times n using [solve()], then take the square root of the diagonal.

Value

A numeric vector of length 'n'.

Author(s)

Caroline Ring

Inverse diagonal, method 2

Description

Get square root of diagonal of inverse matrix, second method

Usage

hess_sd2(m)

Arguments

Details

Following the procedure outlined in Gill & King (2004): Calculate generalized inverse of a matrix 'm' using [MASS::ginv()]. Then perform a generalized Cholesky factorization of the generalized inverse using [Matrix::Cholesky()] with 'perm = TRUE'. Reconstruct the generalized inverse as

\left(m^{-1} + E\right) = P_1^{\prime} L L^{\prime} P_1

This should ensure positive semi-definiteness of the reconstruction.

Then, take the diagonal of \left(m^{-1} + E \right), and take the square root.

Value

A numeric vector of length n.

Author(s)

Caroline Ring

References

Gill J, King G. (2004) What to Do When Your Hessian is Not Invertible: Alternatives to Model Respecification in Nonlinear Estimation. Sociological Methods & Research 33(1):54-87. DOI: 10.1177/0049124103262681

Ignore unused imports

Description

Placeholder function to appease R CMD CHECK

Usage

ignore_unused_imports()

Details

This function does nothing and should be ignored by the user.

Why it exists: Whenever possible, 'invivopkfit' code calls functions from other packages using the syntax 'package::function()', which means that the whole package does not have to be loaded, nor does the function itself have to be loaded until it is used. The relevant packages are listed in the 'invivofit' package 'DESCRIPTION' file under 'Imports', because they must be installed to use 'invivopkfit'. But because the packages are not actually loaded, this creates a (spurious) NOTE from 'R CMD CHECK' about a declared Import not being used. This function is a workaround to suppress that NOTE. It does nothing except contain namespace-qualified references (not calls) to objects in the relevant packages.

Author(s)

Caroline Ring

References

https://r-pkgs.org/dependencies-in-practice.html#how-to-not-use-a-package-in-imports

Check whether an object is of class 'pk'

Description

Check whether an object is of class 'pk'

Usage

is.pk(obj)

Arguments

Value

TRUE if the object inherits from class 'pk', FALSE if it does not

Author(s)

Caroline Ring

Check whether an object is of class 'pk_faceted'

Description

Check whether an object is of class 'pk_faceted'

Usage

is.pk_faceted(obj)

Arguments

Value

TRUE if the object inherits from class 'pk', FALSE if it does not

Author(s)

Caroline Ring

Is an object class 'pk_scales'?

Description

Is an object class 'pk_scales'?

Usage

is.pk_scales(obj)

Arguments

Value

TRUE if 'obj' inherits from class 'pk_scales'; FALSE if not

Author(s)

Caroline Ring

Is an object pkproto?

Description

Is an object pkproto?

Usage

is.pkproto(obj)

Arguments

Value

TRUE if 'obj' inherits from class 'pkproto'; FALSE if not

Author(s)

Caroline Ring

Log-likelihood

Description

Extract log-likelihood(s) from a fitted 'pk' object

Usage

## S3 method for class 'pk'
logLik(
  object,
  newdata = NULL,
  model = NULL,
  method = NULL,
  negative = FALSE,
  force_finite = FALSE,
  exclude = TRUE,
  drop_obs = TRUE,
  ...
)

Arguments

Details

For details on how the log-likelihood is calculated, see [log_likelihood()].

# New levels in 'newdata'

The log-likelihood requires an error variance for each observation. Depending on the error model used for the model fit, each observation may have a different corresponding error variance, based on its unique combinations of levels of factor variables as specified in [stat_error_model()] when setting up the [pk()] object. (The error model specified in the 'pk' object can be viewed using [get_error_group()]).

If you are supplying new data in 'newdata', then the unique combinations of the factor levels for the new observations will be used to find the matching error hyperparameter. If the new data contains new combinations of factor levels not found in the data used to fit the model, then the following procedure will be used to calculate the log-likelihood for the observations with new levels:

If there are i = 1, 2, ... G groups with unique combinations of the factor levels in the original data, then there are corresponding error standard deviations \sigma_i = \sigma_1, \sigma_2, ..., \sigma_G.

Each observation with a new combination of factor levels will have G differerent log-likelihoods computed, as though it were part of each of the G existing groups. Then, the average of these G log-likelihoods will be taken and assigned to the observation. In effect, each observation with a new level is treated as though it is equally likely to belong to any of the existing groups.

# Scaling and transformation of concentration variables in 'newdata'

This function differs from some of the other methods for a fitted [pk()] object that accept 'newdata', in that there is no 'use_scale_conc' argument for [logLik.pk()]. You cannot specify a different scaling/transformation for concentration variables – you have to use the same scaling/transformation that was used to fit the model. This is because the log-likelihood depends on the fitted values of the error variance hyperparameters, and those are valid only for the transformation of the concentration data that was used to fit the model.

Value

A data.frame with coefficients and log-likelihood values calculated using 'newdata'. There is one row for each model in ‘obj'’s [stat_model()] element and each [optimx::optimx()] method (specified in [settings_optimx()]).

Author(s)

Caroline Ring, Gilberto Padilla Mercado

See Also

Other fit evaluation metrics: AAFE.pk(), AFE.pk(), AIC.pk(), BIC.pk(), rmse.pk(), rsq.pk()

Other log likelihood functions: AIC.pk(), BIC.pk()

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(), get_tkstats.pk(), predict.pk(), residuals.pk(), rmse.pk(), rsq.pk()

Log-likelihood

Description

The log-likelihood function (probability of data given model parameters).

Usage

log_likelihood(
  par,
  const_params = NULL,
  data = NULL,
  data_sigma_group = NULL,
  modelfun = NULL,
  dose_norm = FALSE,
  log10_trans = FALSE,
  negative = TRUE,
  force_finite = FALSE,
  max_multiplier = NULL,
  includes_preds = FALSE,
  suppress.messages = TRUE
)

Arguments

Details

The log-likelihood is formulated by assuming that residuals (transformed model-predicted concentrations minus transformed observed concentrations) are independent, and that groups of residuals obey zero-mean normal distributions where each group may have a separate error variance. Error groups are defined as unique combinations of variables in the harmonized data, by a command such as 'pk(data = ...) + stat_error_model(error_group = vars(...)'.

# Log-likelihood equations

For chemical-species combination i and study j, define the following quantities.

y_{ijk} is the k^{th} observation of concentration (which may be transformed, e.g. dose-normalized and/or log10-transformed), corresponding to dose d_{ijk} and time t_{ijk}. Each observation has a corresponding LOQ, \textrm{LOQ}_{ijk}.

For multiple-subject observations, y_{ijk} is the k^{th} *sample mean* observed concentration for chemical-species combination i and study j, corresponding to dose d_{ijk} and time t_{ijk}. It represents the mean of n_{ijk} individual measurements. It has a corresponding sample standard deviation, s_{ijk}. In the harmonized data, s_{ijk} is contained in variable 'Conc_SD'.

\bar{\theta}_i represents the vector of model parameters supplied in argument 'params' for chemical-species combination i.

\mu_{ijk} is the model-predicted concentration for dose d_{ijk} and time t_{ijk}. If f(d, t; \bar{ \theta}) is the model function evaluated at dose d and time t, with parameter vector \bar{\theta}, then

\mu_{ijk} = f \left(d_{ijk}, t_{ijk}; \bar{\theta}_i \right)

\sigma_{ij}^2 is the study- and chemical-specific residual variance. (It is a hyperparameter.)

## Single-subject observations above limit of quantification (detects)

This is the normal probability density function evaluated at the observed concentration, as implemented in [stats::dnorm()].

LL_{ijk} = \log \left( \frac{1}{\sqrt{\sigma_{ij} 2 \pi}} \exp \left[ \frac{-1}{2} \left( \frac{y_{ijk} - \mu_{ijk}}{\sigma_{ij}} \right)^2 \right] \right)

## Single-subject observations below limit of quantification (non-detects)

This is the normal cumulative density function evaluated at the LOQ, as implemented in [stats::pnorm()]. It is the total probability of observing a concentration anywhere between 0 and the LOQ.

LL_{ijk} = \log \left( \frac{1}{2} \left[ 1 + \textrm{erf} \left( \frac{\textrm{LOQ}_{ijk} - \mu_{ijk}}{\sigma_{ij} \sqrt{2}} \right) \right] \right)

## Multiple-subject observations above limit of quantification

This is the joint log-likelihood across the multiple subjects included in one observation, re-expressed in terms of the sample mean, sample SD, and number of subjects for that observation. It is implemented in [dnorm_summary()].

LL_{ijk} = n_{ijk} * \log \left[ \frac{1}{\sigma_{ij} \sqrt{2 \pi}} + \frac{-1}{2 \sigma_{ij}^2} \left( \left( n_{ijk} - 1 \right) s_{ijk}^2 + n_{ijk} \left( y_{ijk} - \mu_{ijk} \right)^2 \right) \right]

## Multiple-subject observations below limit of quantification

This case is not implemented. If sample mean concentration is reported below LOQ, then it is unclear what individual observed concentrations are represented, and how they were combined to produce the summary data in terms of sample mean and sample SD. Were all individual observations below LOQ? Or were below-LOQ observations replaced with 0, LOQ/2, etc. before sample mean and sample SD were computed? If the sample mean is reported below LOQ, what LOQ is reported? Did individual observations all have the same LOQ, or is an average or median LOQ being used? It is impossible to formulate the log-likelihood without knowing the answers to these questions. Therefore, multiple-subject observations below LOQ are excluded from analysis (they are marked as excluded in [preprocess_data()]).

# Joint log-likelihood for a chemical and species

The joint log-likelihood for a chemical and species is simply the sum of log-likelihoods across observations.

LL_{i} = \sum_{j=1}^{J_i} \sum_{k=1}^{K_{ij}} LL_{ijk}

This is the overall probability of the observed data, given the model and parameters.

Value

A log-likelihood value for the data given the parameter values in params

Author(s)

Caroline Ring, Gilberto Padilla Mercado

New mapping

Description

New mapping

Usage

mapping(
  mapping = ggplot2::aes(Chemical = analyte_dtxsid, Chemical_Name =
    analyte_name_original, DTXSID = analyte_dtxsid, CASRN = analyte_casrn, Species =
    species, Reference = document_id, Media = conc_medium_normalized, Route =
    administration_route_normalized, Dose = dose_level_corrected, Dose.Units = "mg/kg",
    Subject_ID = subject_id, Series_ID = series_id, Study_ID = study_id, ConcTime_ID =
    conc_time_id, N_Subjects = n_subjects_in_series, Weight = weight_kg, Weight.Units =
    "kg", Time = time_hr, Time.Units = "hours", 
     Value = conc, Value.Units = "mg/L",
    Value_SD = conc_sd_normalized, LOQ = loq),
  ...
)

Arguments

Value

An object of class 'uneval' containing the mapping – see [ggplot2::aes()] for details.

Author(s)

Caroline Ring

Log10-scaled midpoint

Description

Log10-scaled midpoint

Usage

midpt_log10(x)

Arguments

Value

The log10-scaled midpoint, calculated as 'log10(mean(range(x))'

1-compartment model

Description

The 'pk_model' object defining the 1-compartment model.

Usage

model_1comp

Format

An object of class list (inherits from pk_model) of length 10.

Details

A 'pk_model' object: under the hood, a 'list' object with named elements corresponding to the arguments of [pk_model()]. See that function documentation for the definition of each element.

See [cp_1comp()] for the function that predicts blood/plasma concentration for a bolus dose (oral or IV).

See [auc_1comp()] for the function that predicts area under the concentration-time curve.

See [tkstats_1comp()] for the function that calculates summary toxicokinetic statistics from 1-compartment model parameters.

See [params_1comp()] for the function that determines bounds and starting guesses for model parameters, based on the data.

1-compartment model that assumes non-restrictive clearance

Description

The 'pk_model' object defining the 1-compartment model.

Usage

model_1comp_cl_nonrest

Format

An object of class list (inherits from pk_model) of length 10.

Details

A 'pk_model' object: under the hood, a 'list' object with named elements corresponding to the arguments of [pk_model()]. See that function documentation for the definition of each element.

See [cp_1comp_cl()] for the function that predicts blood/plasma concentration for a bolus dose (oral or IV).

See [auc_1comp_cl()] for the function that predicts area under the concentration-time curve.

See [tkstats_1comp_cl()] for the function that calculates summary toxicokinetic statistics from 1-compartment model parameters.

See [params_1comp_cl()] for the function that determines bounds and starting guesses for model parameters, based on the data.

1-compartment model that assumes restrictive clearance

Description

The 'pk_model' object defining the 1-compartment model.

Usage

model_1comp_cl_rest

Format

An object of class list (inherits from pk_model) of length 10.

Details

A 'pk_model' object: under the hood, a 'list' object with named elements corresponding to the arguments of [pk_model()]. See that function documentation for the definition of each element.

See [cp_1comp_cl()] for the function that predicts blood/plasma concentration for a bolus dose (oral or IV).

See [auc_1comp_cl()] for the function that predicts area under the concentration-time curve.

See [tkstats_1comp_cl()] for the function that calculates summary toxicokinetic statistics from 1-compartment model parameters.

See [params_1comp_cl()] for the function that determines bounds and starting guesses for model parameters, based on the data.

1-compartment model that assumes restrictive clearance optimizes Fup

Description

The 'pk_model' object defining the 1-compartment model.

Usage

model_1comp_fup

Format

An object of class list (inherits from pk_model) of length 10.

Details

A 'pk_model' object: under the hood, a 'list' object with named elements corresponding to the arguments of [pk_model()]. See that function documentation for the definition of each element.

See [cp_1comp_cl()] for the function that predicts blood/plasma concentration for a bolus dose (oral or IV).

See [auc_1comp_cl()] for the function that predicts area under the concentration-time curve.

See [tkstats_1comp_cl()] for the function that calculates summary toxicokinetic statistics from 1-compartment model parameters.

See [params_1comp_cl()] for the function that determines bounds and starting guesses for model parameters, based on the data.

2-compartment model

Description

The 'pk_model' object defining the 2-compartment model.

Usage

model_2comp

Format

An object of class list (inherits from pk_model) of length 10.

Details

A 'pk_model' object: under the hood, a 'list' object with elements corresponding to the arguments of [pk_model()]. See that function documentation for the definition of each element.

See [cp_2comp()] for the function that predicts blood/plasma concentration for a bolus dose (oral or IV).

See [auc_2comp()] for the function that predicts area under the concentration-time curve.

See [tkstats_2comp()] for the function that calculates summary toxicokinetic statistics from 1-compartment model parameters.

See [params_2comp()] for the function that determines bounds and starting guesses for model parameters, based on the data.

Flat model

Description

The 'pk_model' object defining the flat model.

Usage

model_flat

Format

An object of class list (inherits from pk_model) of length 10.

Details

A 'pk_model' object: under the hood, a 'list' object with elements corresponding to the arguments of [pk_model()]. See that function documentation for the definition of each element.

See [cp_flat()] for the function that predicts blood/plasma concentration for a bolus dose (oral or IV).

See [auc_flat()] for the function that predicts area under the concentration-time curve.

See [tkstats_flat()] for the function that calculates summary toxicokinetic statistics from 1-compartment model parameters.

See [params_flat()] for the function that determines bounds and starting guesses for model parameters, based on the data.

nca()

Description

This is the S3 method generic for nca()

Usage

nca(obj, ...)

Arguments

Value

A 'data.frame' with variables including all the grouping variables in 'nca_group', 'nca_group_id'; 'design' (the auto-detected study design for this group); 'param_name' (the name of the NCA parameter); 'param_value' (the NCA parameter value); 'param_sd_z' (standard deviation of the estimated NCA parameter value, if available); 'param_units' (the units of the NCA parameter, derived from the units of the data).

See Also

[nca.pk()] for the method for class [pk()]

Default method for nca()

Description

Default method for nca()

Usage

## Default S3 method:
nca(obj, ...)

Arguments

Value

An error, when a non-pk object is used for the first argument.

NCA for a 'pk' object

Description

Non-compartmental analysis for a 'pk' object

Usage

## S3 method for class 'pk'
nca(
  obj,
  newdata = NULL,
  nca_group = NULL,
  exclude = TRUE,
  dose_norm = FALSE,
  suppress.messages = NULL,
  ...
)

Arguments

Details

Perform non-compartmental analysis of data in a 'pk' object (or optionally, new data), using data groupings defined by 'get_nca_group()' for the 'pk' object (or optionally, new groupings). If you provide both 'newdata' and 'nca_group', then everything in the 'pk' object will be ignored and you will simply be doing NCA *de novo* (which may be what you want).

Value

A 'data.frame' with variables including all the grouping variables in 'nca_group', 'nca_group_id'; 'design' (the auto-detected study design for this group); 'param_name' (the name of the NCA parameter); 'param_value' (the NCA parameter value); 'param_sd_z' (standard deviation of the estimated NCA parameter value, if available); 'param_units' (the units of the NCA parameter, derived from the units of the data).

Author(s)

Caroline Ring

Create a new 'pk' object

Description

[pk()] initializes a new 'pk' object.

Usage

pk(
  data = NULL,
  mapping = ggplot2::aes(Chemical = analyte_dtxsid, Chemical_Name =
    analyte_name_original, DTXSID = analyte_dtxsid, CASRN = analyte_casrn, Species =
    species, Reference = fk_extraction_document_id, Media = conc_medium_normalized, Route
    = administration_route_normalized, Dose = invivPK_dose_level, Dose.Units = "mg/kg",
    Subject_ID = fk_subject_id, Series_ID = fk_series_id, Study_ID = fk_study_id,
    ConcTime_ID = conc_time_id, N_Subjects = n_subjects_normalized, Weight = weight_kg,
    Weight.Units = "kg", Time = time_hr, 
     Time.Units = "hours", Value =
    invivPK_conc, Value.Units = "mg/L", Value_SD = invivPK_conc_sd, LOQ = invivPK_loq),
  settings_preprocess_args = list(),
  settings_data_info_args = list(),
  settings_optimx_args = list(),
  scale_conc_args = list(),
  scale_time_args = list(),
  stat_model_args = list(),
  stat_error_model_args = list(),
  facet_data_args = list()
)

Arguments

Details

[pk()] is used to construct the initial 'pk' object for analysis. It is almost always followed by '+' to add steps to the workflow. For example, you could use ‘pk(my_data) + stat_model(model = ’1comp')' to set up for fitting a 1-compartment model.

# The 'pk' object

A 'pk' object consists of a set of concentration-dose-time data to be fitted, and sets of instructions for steps in the analysis workflow:

- settings for how to pre-process the data (harmonizing variable names, imputing missing data, calculating derived variables) - scalings/transformations to be applied to the data - settings for the numerical optimization algorithm to be used to fit any model - optionally: which PK model(s) should be fitted to this dataset. (You do not have to fit any PK model if you don't want to; you can instead just set up the 'pk' object with data, and do non-compartmental analysis on it.)

No data processing, model fitting, or any other analysis is done until you explicitly request it. Until then, the 'pk' object remains just a set of data and instructions. This allows you to specify the instructions for each analysis step without regard for the actual order of the analysis steps, and to overwrite previous instructions, without having to re-do the model fitting each time you add or change a set of instructions. This is particularly useful if you are working in interactive mode at the R console.

# Mappings

Your input data can have any variable names you like. However, internally, 'invivopkfit' needs to use a set of "standard", harmonized variable names (e.g., it refers to the variable containing measured tissue concentrations as 'Conc'; the variable containing observed time points as 'Time'; and the variable containing administered doses as 'Dose'). In effect, 'invivopkfit' needs to rename the input data, and produce a new 'data.frame' that uses these internal harmonized variable names.

In order to know which variable names in the input data correspond to each of the internal harmonized variable names, we need to set up a mapping between the internal harmonized variable names and the original variable names.

The simplest, most flexible way to set up this mapping is by (ab)using a call to [ggplot2::aes()]. In the context of [ggplot2::ggplot2-package()], you would use [ggplot2::aes()] to set up mappings to ‘ggplot2'’s "aesthetics", internal harmonized variable names which it uses for plotting: *e.g.*, 'x', 'y', 'color', 'size', 'shape', and so on. In the context of [invivopkfit-package()], we are setting up mappings to ‘invivopkfit'’s internal harmonized variable names which it uses in model fitting. These "'invivopkfit' aesthetic" variables are as follows:

- 'Chemical': A 'character' variable containing the chemical identifier. All rows of 'data' should have the same value for 'Chemical'. - 'Species': A 'character' variable containing the name of the species for which the data was measured. All rows of 'data' should have the same value for 'Species'. - 'Reference': A 'character' variable containing a unique identifier for the data reference (e.g., a single publication). - 'Subject': A 'character' variable containing a unique identifier for the subject associated with each observation (an individual animal or group of animals). - 'N_Subjects': A 'numeric' variable; an integer giving the number of individual animals represented by this observation. (Some data sets report tissue concentrations for individual animals, in which case 'N_Subjects' will be 1; others report average tissue concentrations for groups of multiple animals, in which case 'N_Subjects' will be greater than 1.) - ‘Weight': A 'numeric' variable giving the subject’s body weight. - 'Weight.Units': A 'character' variable giving the units of body weight. - 'Route': A 'character' variable denoting the route of administration. Either 'po' (oral) or 'iv' (intravenous). Other routes are not currently supported. - 'Dose': A 'numeric' variable giving the dose administered. - 'Dose.Units': A 'character' variable giving the units of the administered doses. - 'Time': A 'numeric' variable giving the time of tissue collection. - 'Time.Units': A 'numeric' variable giving the units of 'Time'. - 'Media': A 'character' variable giving the tissue that was analyzed. Either 'blood' or 'plasma'. Other tissues are not currently supported. - 'Value': A 'numeric' variable giving the tissue concentration in units of mg/L. If 'N_Subjects > 1', 'Value' is assumed to represent the mean tissue concentration for this group of subjects. If the tissue concentration was below the limit of quantification (LOQ), this value may be 'NA_real_'. - 'Value_SD': A 'numeric' variable giving the standard deviation of the tissue concentration in units of mg/L, if available and relevant. If 'N_Subjects > 1', 'Value_SD' is assumed to represent the standard deviation of tissue concentrations for this group of subjects. If 'N_Subjects == 1', then 'Value_SD' may be 'NA_real_'. - 'LOQ': A 'numeric' variable giving the limit of quantification applicable to this tissue concentration in units of mg/L, if available. - 'Value.Units': A 'character' variable giving the units of 'Value', 'Value_SD', and 'LOQ'.

You may additionally include mappings to other variable names of your choice, which will appear in the 'pk' object in 'pk$data' after the analysis is done.

As with usual calls to [ggplot2::aes()], you should provide the variable names without quoting them. For example, use 'ggplot2::aes(Chemical = my_chem)'. Do * not* use 'ggplot2::aes("Chemical" = "my_chem")'.

Also, as with usual calls to [ggplot2::aes()], you may also specify that any of the "'invivopkfit' aesthetic" variables should be mapped to a constant value, rather than to a variable in 'data'. For example, imagine that you don't have a column in 'data' that encodes the units of body weight, but you know that all body weights are provided in units of kilograms. You could specify 'mapping = ggplot2::aes(Chemical = my_dtxsid, Species = my_species, Weight = my_weight, Weight.Units = "kg")' to map 'Weight.Units' to a fixed value of "kg".

Finally, as with usual calls to [ggplot2::aes()], you may specify mappings as expressions that use variable names in 'data'. For example, if the species-name variable in 'data' sometimes says "rat", sometimes "Rat", sometimes "RAT", you might want to harmonize the capitalization. You can do that easily by specifying 'mapping = ggplot2::aes(Chemical = my_dtxsid, Species = tolower(my_species)'.

The following "aesthetics" variable names are reserved for internal use (i.e., they are automatically assigned by [preprocess_data.pk()], and should *not* be included in 'mapping':

- 'Conc': This is assigned as the greater of 'Value' and 'LOQ', with NAs removed. - 'Conc_SD': This is set equal to 'Value_SD'. - 'Detect': This is a logical variable, 'TRUE' if 'Conc > LOQ' and 'FALSE' otherwise. - 'Conc_trans': This is 'Conc' with all scalings and transformations applied as specified in '+ scale_conc()'. - 'Conc_SD_trans': This is 'Conc_SD' with all scalings and transformations applied as specified in '+ scale_conc()'. - ‘Conc_trans.Units': Automatically-derived from 'Conc.Units' with any scalings and transformations applied. If dose normalization is requested, then 'Dose.Units' is also used to automatically derive the resulting 'Conc_trans.Units'. For example, if both dose-normalization and [log10()] transformation are requested, and 'Conc.Units = ’mg/L'‘ and 'Dose.Units = ’mg/kg', then 'Conc_trans.Units = log10((mg/L)/(mg/kg))'. - 'Time_trans': This is 'Time' with any rescaling specified in '+ scale_time()'. - 'Time_trans.Units': The new units of time after any rescaling (e.g. 'hours', 'days', 'weeks',...)

If you do assign any of these reserved variable names in 'mapping', your mapping will be ignored for those reserved variable names. WARNING: If you have any variables with these reserved names in your original data, those original variables will be dropped by [preprocess_data.pk()].

The default value of 'mapping' is the following (which refers to original variable names in the built-in dataset [cvt]):

“' ggplot2::aes( Chemical = chemicals_analyzed.dsstox_substance_id, DTXSID = chemicals_analyzed.dsstox_substance_id, CASRN = chemicals_analyzed.dsstox_casrn, Species = subjects.species, Reference = as.character(ifelse(is.na(documents_reference.id), documents_extraction.id, documents_reference.id)), Media = series.conc_medium_normalized, Route = studies.administration_route_normalized, Dose = studies.dose_level_normalized, Dose.Units = "mg/kg", Subject = subjects.id, N_Subjects = series.n_subjects_in_series, Weight = subjects.weight_kg, Weight.Units = "kg", Time = conc_time_values.time_hr, Time.Units = "hours", Value = conc_time_values.conc, Value.Units = "mg/L", LOQ = series.loq_normalized, Value_SD = conc_time_values.conc_sd_normalized ) “'

# Data

'Route' values should be either '"oral"' (oral bolus administration) or '"iv"' (IV bolus administration), and 'Media' values should be either '"blood"' or '"plasma"'.

If 'data' contains data for more than one 'Chemical' and 'Species', then you should use [facet_data()] to run a "faceted" analysis. A faceted analysis will group the data according to unique combinations of the faceting variables, and produce a 'pk' object for each group. The result is a [tibble::tibble()] grouped by the faceting variables, with a list column named 'pk' containing the 'pk' object for each group. This [tibble::tibble()] is an object of class 'pk_faceted'.

All methods for 'pk' objects have a corresponding version for a 'pk_faceted' object, which applies the method to each 'pk' object in turn and either returns the same 'pk_faceted' object with a modified 'pk' column (for methods that operate on a 'pk' object and return a modified version of the same 'pk' object like [preprocess_data()], [data_info()], [prefit()], [fit()]), or produces a [tibble::tibble()] grouped by the faceting variables, with a list column named after the 'pk' method containing the results of that method (for methods that operate on a 'pk' object but return something other than a modified 'pk' object, e.g. [summary.pk()], [coef.pk()], [coef_sd.pk()], [predict.pk()], [residuals.pk()], [nca.pk()]).

Value

An object of class 'pk'. The initial 'pk' object is a list with elements 'data_orig', 'data_settings', 'scales' and 'optimx_settings'. 'data_orig' is the original data set to be fitted, as supplied in the argument 'data'. 'data_settings' is a named list containing all the other input arguments: these provide settings that will be used when the data is pre-processed before fitting.

Author(s)

Caroline Ring

Add a 'pkproto' object to a 'pk' object

Description

This is the S3 generic method.

Usage

pk_add(pkproto_obj, pk_obj, objectname)

Arguments