solve_model: Solve_model

In httk: High-Throughput Toxicokinetics

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

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 parameterized passed to the model parameterization function.
small.time	A tiny amount of time used to provide predictions on either side of an instaneous event (like an iv injection). This helps ensure that abrupt changes plot well. Defaults to 1e-4.
...	Additional arguments passed to the integrator.

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
	c	Parameter is proportional to body weight	1 / kg for volumes and 1/kg^(3/4) for flows

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.

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.

Author(s)

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

References

\insertRef

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


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

httk documentation built on Sept. 11, 2024, 9:32 p.m.