| solve_model {httk} | R Documentation |
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 = "lsoda",
rtol = 1e-08,
atol = 1e-12,
recalc.blood2plasma = FALSE,
recalc.clearance = FALSE,
restrictive.clearance = TRUE,
adjusted.Funbound.plasma = TRUE,
minimum.Funbound.plasma = 1e-04,
parameterize.arg.list = list(),
...
)
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 dose of 1 mg/kg BW along with the dose type (add/multiply) specified for a given route (e.g. 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 |
Argument passed to integrator (deSolve). |
atol |
Argument passed to integrator (deSolve). |
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. |
... |
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
Pearce RG, Setzer RW, Strope CL, Wambaugh JF, Sipes NS (2017). “Httk: R package for high-throughput toxicokinetics.” Journal of Statistical Software, 79(4), 1.
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)