httk (version 2.5.0)

solve_model: Solve_model

Description

solve_model is designed to accept systematized metadata (provided by the model.list defined in the modelinfo files) for a given toxicokinetic model, including names of variables, parameterization functions, and key units, and use it along with chemical information to prepare an ode system for numerical solution over time of the amounts or concentrations of chemical in different bodily compartments of a given species (either "Rat", "Rabbit", "Dog", "Mouse", or default "Human").

Usage

solve_model(
  chem.name = NULL,
  chem.cas = NULL,
  dtxsid = NULL,
  times = NULL,
  parameters = NULL,
  model = NULL,
  route = "oral",
  dosing = NULL,
  days = 10,
  tsteps = 4,
  initial.values = NULL,
  initial.value.units = NULL,
  plots = FALSE,
  monitor.vars = NULL,
  suppress.messages = FALSE,
  species = "Human",
  input.units = "mg/kg",
  output.units = NULL,
  method = NULL,
  rtol = 1e-06,
  atol = 1e-06,
  recalc.blood2plasma = FALSE,
  recalc.clearance = FALSE,
  restrictive.clearance = TRUE,
  adjusted.Funbound.plasma = TRUE,
  minimum.Funbound.plasma = 1e-04,
  parameterize.arg.list = list(),
  small.time = 1e-04,
  ...
)

Value

A matrix of class deSolve with a column for time(in days), each compartment, the area under the curve, and plasma concentration and a row for each time point.

Arguments

chem.name

Either the chemical name, CAS number, or the parameters must be specified.

chem.cas

Either the chemical name, CAS number, or the parameters must be specified.

dtxsid

EPA's DSSTox Structure ID (https://comptox.epa.gov/dashboard) the chemical must be identified by either CAS, name, or DTXSIDs

times

Optional time sequence for specified number of output times (in days) to be returned by the function. The model is solved explicitly at the time sequence specified. Dosing sequence begins at the first time provided.

parameters

List of chemical parameters, as output by parameterize_pbtk function. Overrides chem.name and chem.cas.

model

Specified model to use in simulation: "pbtk", "3compartment", "3compartmentss", "1compartment", "schmitt", ...

route

String specification of route of exposure for simulation: "oral", "iv", "inhalation", ...

dosing

List of dosing metrics used in simulation, which includes the namesake entries of a model's associated dosing.params. In the case of most httk models, these should include "initial.dose", "doses.per.day", "daily.dose", and "dosing.matrix". The "dosing.matrix" is used for more precise dose regimen specification, and is a matrix consisting of two columns or rows named "time" and "dose" containing the time and amount of each dose. If none of the namesake entries of the dosing list is set to a non-NULL value, solve_model uses a default initial dose of 1 mg/kg BW along with the dose type (add/multiply) specified for a given route (for example, add the dose to gut lumen for oral route)

days

Simulated period. Default 10 days.

tsteps

The number of time steps per hour. Default of 4.

initial.values

Vector of numeric values containing the initial concentrations or amounts of the chemical in specified tissues with units corresponding to those specified for the model outputs. Default values are zero.

initial.value.units

Vector of character strings containing the units corresponding to 'initial.values' specified for the model outputs. Default is assuming the units match expected compartment units for the model.

plots

Plots all outputs if true.

monitor.vars

Which variables are returned as a function of time. Default values of NULL looks up variables specified in modelinfo_MODEL.R

suppress.messages

Whether or not the output messages are suppressed.

species

Species desired (models have been designed to be parameterized for some subset of the following species: "Rat", "Rabbit", "Dog", "Mouse", or default "Human").

input.units

Input units of interest assigned to dosing. Defaults to mg/kg BW, in line with the default dosing scheme of a one-time dose of 1 mg/kg in which no other dosing parameters are specified.

output.units

Output units of interest for the compiled components. Defaults to NULL, and will provide values in model units if unspecified.

method

Method used by integrator (deSolve).

rtol

Relative tolerance used by integrator (deSolve) to determine numerical precision -- defaults to 1e-6.

atol

Absolute tolerance used by integrator (deSolve) to determine

recalc.blood2plasma

Recalculates the ratio of the amount of chemical in the blood to plasma using the input parameters, calculated with hematocrit, Funbound.plasma, and Krbc2pu.

recalc.clearance

Recalculates the the hepatic clearance (Clmetabolism) with new million.cells.per.gliver parameter.

restrictive.clearance

Protein binding not taken into account (set to 1) in liver clearance if FALSE.

adjusted.Funbound.plasma

Uses adjusted Funbound.plasma when set to TRUE along with partition coefficients calculated with this value.

minimum.Funbound.plasma

Monte Carlo draws less than this value are set equal to this value (default is 0.0001 -- half the lowest measured Fup in our dataset)

parameterize.arg.list

Additional parameters passed to the model parameterization function (other than chemical identifier, `species`, `suppress.messages`, `restrictive.clearance`, `adjusted.Funbound.plasma`, and `minimum.Funbound.plasma`)

small.time

A tiny amount of time used to provide predictions on either side of an instantaneous event (like an iv injection). This helps ensure that abrupt changes plot well. Defaults to 1e-4.

...

Additional arguments passed to the integrator.

Author

John Wambaugh, Robert Pearce, Miyuki Breen, Mark Sfeir, and Sarah E. Davidson

Details

Dosing values with certain acceptable associated input.units (like mg/kg BW) are configured to undergo a unit conversion. All model simulations are intended to run with units as specifed by "compartment.units" in the model.list (as defined by the modelinfo files).

The 'dosing' argument includes all parameters needed to describe exposure in terms of route of administration, frequency, and quantity short of scenarios that require use of a more precise forcing function. If the dosing argument's namesake entries are left NULL, solve_model defaults to a single-time dose of 1 mg/kg BW according to the given dosing route and associated type (either add/multiply, for example we typically add a dose to gut lumen when oral route is specified).

AUC is the area under the curve of the plasma concentration.

Model parameters are named according to the following convention:

prefix	suffix	Meaning	units	K
	Partition coefficient for tissue to free plasma \ tab unitless	V		Volume
L	Q		Flow	L/h
k		Rate	1/h

When species is specified but chemical-specific in vitro data are not available, the function uses the appropriate physiological data (volumes and flows) but default.to.human = TRUE must be used to substitute human fraction unbound, partition coefficients, and intrinsic hepatic clearance. (NOTE: The 'default.to.human' specification should be included as part of the arguments listed in 'parameterize.arg.list'.)

For both plotting purposes and helping the numerical equation solver, it is helpful to specify that time points shortly before and after dosing are included. This function automatically add these points, and they are returned to the user unless the times argument is used, in which case only the time points specified by that argument are provided.

References

pearce2017httkhttk

Examples

# The various "solve_x" functions are wrappers for solve_model:
head(solve_pbtk(chem.name="Terbufos", days=1))

head(solve_model(chem.name="Terbufos",model="pbtk",
                 days=1,
                 dosing=list(
                   initial.dose = 1, # Assume dose is in mg/kg BW/day  
                   doses.per.day=NULL,
                   dosing.matrix = NULL,
                   daily.dose = NULL)))

# \donttest{
# A dose matrix specifies times and magnitudes of doses:
dm <- matrix(c(0,1,2,5,5,5),nrow=3)
colnames(dm) <- c("time","dose")

solve_pbtk(chem.name="Methenamine",
           dosing.matrix=dm,
           dose=NULL,
           days=2.5,
           daily.dose=NULL)

solve_model(chem.name="Methenamine",
            model="pbtk",
            days=2.5,
            dosing=list(
              initial.dose =NULL,
              doses.per.day=NULL,
              daily.dose=NULL,
              dosing.matrix=dm))

solve_model(chem.name="Besonprodil",
            model="pbtk",
            days=2.5,
            dosing=list(
              initial.dose=NULL,
              doses.per.day=4,
              daily.dose=1,
              dosing.matrix=NULL))
  
solve_pbtk(chem.name="Besonprodil",
           daily.dose=1,
           dose=NULL,
           doses.per.day=4,
           days=2.5)
# }