invitroTKstats (version 0.0.14)

calc_clint: Calculate Intrinsic Hepatic Clearance (Clint) with Bayesian Modeling (Level-4)

Description

This function estimates the intrinsic hepatic clearance (Clint) with Bayesian modeling on Hepatocyte Incubation data shibata2002predictioninvitroTKstats. Clint and the credible intervals, at both 1 and 10 uM (if tested), are estimated from posterior samples of the MCMC. A summary table (level-4) along with the full set of MCMC results is returned from the function.

Usage

calc_clint(
  FILENAME,
  data.in,
  TEMP.DIR = NULL,
  NUM.CHAINS = 5,
  NUM.CORES = 2,
  RANDOM.SEED = 1111,
  SEED.SET = NULL,
  good.col = "Verified",
  JAGS.PATH = NA,
  decrease.prob = 0.5,
  saturate.prob = 0.25,
  degrade.prob = 0.05,
  save.MCMC = FALSE,
  sig.figs = 3,
  INPUT.DIR = NULL,
  OUTPUT.DIR = NULL,
  verbose = TRUE
)

Value

A list of two objects:

1. Results: A level-4 data frame with the Bayesian estimated intrinsic hepatic clearance (Clint) for 1 and 10 uM and credible intervals for all compounds in the input file. Column includes: Compound.Name - compound name, Lab.Compound.Name - compound name used by the laboratory, DTXSID - EPA's DSSTox Structure ID, Clint.1.Med/Clint.10.Med - posterior median, Clint.1.Low/Clint.10.Low - 2.5th quantile, Clint.1.High/Clint.10.High - 97.5th quantile, Clint.pValue, Sat.pValue, degrades.pValue - "p-values" estimated from the probabilities of observing decreases, saturations, and abiotic degradations in all posterior samples.

2. coda: A runjags-class object containing results from JAGS model.

Arguments

FILENAME

(Character) A string used to identify the input level-2 file, "<FILENAME>-Clint-Level2.tsv", and to name the exported model results. This argument is required no matter which method of specifying input data is used. (Defaults to NULL.)

data.in

(Data Frame) A level-2 data frame generated from the format_clint function with a verification column added by sample_verification. Complement with manual verification if needed.

TEMP.DIR

(Character) Temporary directory to save intermediate files. If NULL, all files will be written to the user's per-session temporary directory. (Defaults to NULL.)

NUM.CHAINS

(Numeric) The number of Markov Chains to use. (Defaults to 5.)

NUM.CORES

(Numeric) The number of processors to use for parallel computing. (Defaults to 2.)

RANDOM.SEED

(Numeric) The seed used by the random number generator. (Defaults to 1111.)

SEED.SET

(Numeric Vector) A set of seeds used by the random number generator for each chain. Should be unique for each chain and vector length should equal the total number of chains. (Default is NULL.)

good.col

(Character) Column name indicating which rows have been verified for analysis, valid data rows are indicated with "Y". (Defaults to "Verified".)

JAGS.PATH

(Character) Computer specific file path to JAGS software. (Defaults to NA.)

decrease.prob

(Numeric) Prior probability that a chemical will decrease in the assay. (Defaults to 0.5.)

saturate.prob

(Numeric) Prior probability that a chemicals rate of metabolism will decrease between 1 and 10 uM. (Defaults to 0.25.)

degrade.prob

(Numeric) Prior probability that a chemical will be unstable (that is, degrade abiotically) in the assay. (defaults to 0.05.)

save.MCMC

(Logical) When set to TRUE, will export the MCMC results as an .RData file. (Defaults to FALSE.)

sig.figs

(Numeric) The number of significant figures to round the exported unverified data (level-2). The exported result table (level-4) is left unrounded for reproducibility. (Note: console print statements are also rounded to specified significant figures.) (Defaults to 3.)

INPUT.DIR

(Character) Path to the directory where the input level-2 file exists. If NULL, looking for the input level-2 file in the current working directory. (Defaults to NULL.)

OUTPUT.DIR

(Character) Path to the directory to save the output file. If NULL, the output file will be saved to the user's per-session temporary directory or INPUT.DIR if specified. (Defaults to NULL.)

verbose

(logical) Indicate whether printed statements should be shown. (Default is TRUE.)

Author

John Wambaugh

Details

The input to this function should be "level-2" data. Level-2 data is level-1, data formatted with the format_clint function, and curated with a verification column. "Y" in the verification column indicates the data row is valid for analysis.

Note: By default, this function writes files to the user's per-session temporary directory. This temporary directory is a per-session directory whose path can be found with the following code: tempdir(). For more details, see https://www.collinberke.com/blog/posts/2023-10-24-til-temp-directories/.

Users must specify an alternative path with the TEMP.DIR argument if they want the intermediate files exported to another path. Exported intermediate files include the summary results table (.tsv), JAGS model (.RData), and any "unverified" data excluded from the analysis (.tsv). Users must specify an alternative path with the OUTPUT.DIR argument if they want the final output file exported to another path. The exported final output file is the summary results table (.RData).

As a best practice, INPUT.DIR (when importing a .tsv file) and/or OUTPUT.DIR should be specified to simplify the process of importing and exporting files. This practice ensures that the exported files can easily be found and will not be exported to a temporary directory.

The data frame of observations should be annotated according to these types:

Blank	Cell free blank with media
CC	Cell free calibration curve
Cvst	Hepatocyte incubation concentration vs. time
Inactive	Concentration vs. time data with inactivated hepatocytes

We currently require Cvst data. Blank, CC, and Inactive data are optional.

Clint is calculated using lm to perform a linear regression of MS response as a function of time.

Additional User Notification(s):

• runjags::findjags() may not work as JAGS.PATH argument. Instead, may need to manually remove the trailing path such that JAGS.PATH only contains path information through "/x64" (e.g. JAGS.PATH = "/Program Files/JAGS/JAGS-4.3.1/x64").

References

shibata2002predictioninvitroTKstats

Examples

## Example 1: loading level-2 using data.in and export all files to the user's
## temporary directory
if (FALSE) {
level2 <- invitroTKstats::clint_L2

# JAGS.PATH should be changed to user's specific computer file path to JAGS software.
# findJAGS() from runjags package is a handy function to find JAGS path automatically.
# In certain circumstances or cases, one may need to provide the absolute path to JAGS.
path.to.JAGS <- runjags::findJAGS()
level4 <- calc_clint(FILENAME = "Example1",
                     data.in = level2,
                     NUM.CORES=2,
                     JAGS.PATH=path.to.JAGS)
}

## Example 2: importing level-2 from a .tsv file and export all files to same 
## location as INPUT.DIR 
if (FALSE) {
# Refer to sample_verification help file for how to export level-2 data to a directory.
# JAGS.PATH should be changed to user's specific computer file path to JAGS software.
# findJAGS() from runjags package is a handy function to find JAGS path automatically.
# In certain circumstances or cases, one may need to provide the absolute path to JAGS.
# Will need to replace FILENAME and INPUT.DIR with name prefix and location of level-2 'tsv'.
path.to.JAGS <- runjags::findJAGS()
level4 <- calc_clint(# e.g. replace with "Examples" from "Examples-Clint-Level2.tsv"
                     FILENAME="",
                     NUM.CORES=2,
                     JAGS.PATH=path.to.JAGS,
                     INPUT.DIR = "")
}