Package 'invivoPKfit'

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

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

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

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.

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

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.

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

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

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

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.

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

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

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

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

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.

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

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.

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

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

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

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

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

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

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

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

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.

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

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.

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

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

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

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

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.

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

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

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.

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

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

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.

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

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

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.

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

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

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.

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 = NULL,
  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()

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

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

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

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

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

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)

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

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.

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

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

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

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.

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

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

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.

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

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

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.

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

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

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.

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

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

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.

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.

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

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

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

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.

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

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

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.

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

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

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.

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

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

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.

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

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

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.

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

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'