View source: R/create_mc_samples.R
create_mc_samples | R Documentation |
This is the HTTK master function for creating a data table for
use with Monte Carlo methods to simulate parameter uncertainty and
variabilit. Each column of the output table corresponds to an HTTK model
parameter and each row corresponds to a different random draw (for example,
different individuals when considering biological variability). This
function call three different key functions to simulate parameter parameter
uncertainty and/or variability in one of three ways. First parameters can
be varied in an uncorrelated manner using truncated normal distributions by
the function monte_carlo
. Then, physiological parameters can
be varied in a correlated manner according to the
\insertCitering2017identifying;textualhttk
(\Sexpr[results=rd]{tools:::Rd_expr_doi("10.1016/j.envint.2017.06.004")}) httk-pop approach by the
function httkpop_mc
. Next, both uncertainty and variability
of in vitro HTTK parameters can be simulated by the function
invitro_mc
as described by
\insertCitewambaugh2019assessing;textualhttk
(\Sexpr[results=rd]{tools:::Rd_expr_doi("10.1093/toxsci/kfz205")}). Finally, tissue-specific partition
coefficients are predicted for each draw using the
\insertCiteschmitt2008general;textualhttk
(\Sexpr[results=rd]{tools:::Rd_expr_doi("10.1016/j.tiv.2007.09.010")}) method as calibrated to in vivo
data by \insertCitepearce2017evaluation;textualhttk
(\Sexpr[results=rd]{tools:::Rd_expr_doi("10.1007/s10928-017-9548-7")}) and implemented in
predict_partitioning_schmitt
.
create_mc_samples(
chem.cas = NULL,
chem.name = NULL,
dtxsid = NULL,
parameters = NULL,
samples = 1000,
species = "Human",
suppress.messages = FALSE,
model = "3compartmentss",
httkpop = TRUE,
invitrouv = TRUE,
calcrb2p = TRUE,
censored.params = list(),
vary.params = list(),
return.samples = FALSE,
tissue = NULL,
httkpop.dt = NULL,
invitro.mc.arg.list = NULL,
adjusted.Funbound.plasma = NA,
adjusted.Clint = NA,
httkpop.generate.arg.list = list(method = "direct resampling"),
convert.httkpop.arg.list = NULL,
propagate.invitrouv.arg.list = NULL,
parameterize.args.list = NULL,
Caco2.options = NULL
)
chem.cas |
Chemical Abstract Services Registry Number (CAS-RN) – if parameters is not specified then the chemical must be identified by either CAS, name, or DTXISD |
chem.name |
Chemical name (spaces and capitalization ignored) – if parameters is not specified then the chemical must be identified by either CAS, name, or DTXISD |
dtxsid |
EPA's DSSTox Structure ID (https://comptox.epa.gov/dashboard) – if parameters is not specified then the chemical must be identified by either CAS, name, or DTXSIDs |
parameters |
Parameters from the appropriate parameterization function for the model indicated by argument model |
samples |
Number of samples generated in calculating quantiles. |
species |
Species desired (either "Rat", "Rabbit", "Dog", "Mouse", or default "Human"). Species must be set to "Human" to run httkpop model. |
suppress.messages |
Whether or not to suppress output message. |
model |
Model used in calculation: 'pbtk' for the multiple compartment model,'3compartment' for the three compartment model, '3compartmentss' for the three compartment steady state model, and '1compartment' for one compartment model. This only applies when httkpop=TRUE and species="Human", otherwise '3compartmentss' is used. |
httkpop |
Whether or not to use the \insertCitering2017identifying;textualhttk "httkpop" population generator. Species must be 'Human'. |
invitrouv |
Logical to indicate whether to include in vitro parameters such as intrinsic hepatic clearance rate and fraction unbound in plasma in uncertainty and variability analysis |
calcrb2p |
Logical determining whether or not to recalculate the chemical ratio of blood to plasma |
censored.params |
The parameters listed in censored.params are sampled from a normal distribution that is censored for values less than the limit of detection (specified separately for each parameter). This argument should be a list of sub-lists. Each sublist is named for a parameter in "parameters" and contains two elements: "CV" (coefficient of variation) and "LOD" (limit of detection, below which parameter values are censored. New values are sampled with mean equal to the value in "parameters" and standard deviation equal to the mean times the CV. Censored values are sampled on a uniform distribution between 0 and the limit of detection. Not used with httkpop model. |
vary.params |
The parameters listed in vary.params are sampled from a normal distribution that is truncated at zero. This argument should be a list of coefficients of variation (CV) for the normal distribution. Each entry in the list is named for a parameter in "parameters". New values are sampled with mean equal to the value in "parameters" and standard deviation equal to the mean times the CV. Not used with httkpop model. |
return.samples |
Whether or not to return the vector containing the samples from the simulation instead of the selected quantile. |
tissue |
Desired steady state tissue conentration. |
httkpop.dt |
A data table generated by |
invitro.mc.arg.list |
Additional parameters passed to
|
adjusted.Funbound.plasma |
Deprecated argument – use parameterize.args.list |
adjusted.Clint |
Deprecated argument – use parameterize.args.list |
httkpop.generate.arg.list |
Additional parameters passed to
|
convert.httkpop.arg.list |
Additional parameters passed to the convert_httkpop_* function for the model. |
propagate.invitrouv.arg.list |
Additional parameters passed to model's associated in vitro uncertainty and variability propagation function |
parameterize.args.list |
Additional parameters passed to the parameterize_* function for the model. |
Caco2.options |
Arguments describing how to handle Caco2 absorption data
that are passed to |
The Monte Carlo methods used here were recently updated and described by \insertCitebreen2022simulating;textualhttk.
We aim to make any function that uses chemical identifiers (name, CAS, DTXSID) also work if passed a complete vector of parameters (that is, a row from the table generated by this function). This allows the use of Monte Carlo to vary the parameters and therefore vary the function output. Depending on the type of parameters (for example, physiological vs. in vitro measurements) we vary the parameters in different ways with different functions.
NOTE: This function calculates oral bioavailability parameters based on Caco2 data. If you are comparing the output of this function to the output of a model-parameterization function 'parameterize_MODEL()', you will need to to ensure that 'parameterize_MODEL()' also uses Caco2 data. The built-in model parameterization functions default to using *in vivo* oral bioavailability data when available. To force them to use Caco2 data instead, please pass the following argument to 'parameterize_MODEL()': 'Caco2.options = list(overwrite.invivo = TRUE'.
A data table where each column corresponds to parameters needed for the specified model and each row represents a different Monte Carlo sample of parameter values.
Caroline Ring, Robert Pearce, and John Wambaugh
# We can use the Monte Carlo functions by passing a table
# where each row represents a different Monte Carlo draw of parameters:
p <- create_mc_samples(chem.cas="80-05-7")
# Use data.table for steady-state plasma concentration (Css) Monte Carlo:
calc_mc_css(parameters=p)
# Using the same table gives the same answer:
calc_mc_css(parameters=p)
# Use Css for 1 mg/kg/day for simple reverse toxicokinetics
# in Vitro-In Vivo Extrapolation to convert 15 uM to mg/kg/day:
15/calc_mc_css(parameters=p, output.units="uM")
# Can do the same with calc_mc_oral_equiv:
calc_mc_oral_equiv(15, parameters=p)
#Generate a population using the virtual-individuals method,
#including 80 females and 20 males,
#including only ages 20-65,
#including only Mexican American and
#Non-Hispanic Black individuals,
#including only non-obese individuals
set.seed(42)
mypop <- httkpop_generate(method = 'virtual individuals',
gendernum=list(Female=80,
Male=20),
agelim_years=c(20,65),
reths=c('Mexican American',
'Non-Hispanic Black'),
weight_category=c('Underweight',
'Normal',
'Overweight'))
# Including a httkpop.dt argument will overwrite the number of sample and
# the httkpop on/off logical switch:
samps1 <- create_mc_samples(chem.name="bisphenola",
httkpop=FALSE,
httkpop.dt=mypop)
samps2 <- create_mc_samples(chem.name="bisphenola",
httkpop.dt=mypop)
# But we can turn httkpop off altogether if desired:
samps3 <- create_mc_samples(chem.name="bisphenola",
httkpop=FALSE)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.