calc_fup_red: Calculate Fraction Unbound in Plasma (Fup) from Rapid...

In invitroTKstats: In Vitro Toxicokinetic Data Processing and Analysis Pipeline

Calculate Fraction Unbound in Plasma (Fup) from Rapid Equilibrium Dialysis (RED) Data with Bayesian Modeling (Level-4)

Description

This function estimates the fraction unbound in plasma (Fup) with Bayesian modeling on Rapid Equilibrium Dialysis (RED) data \insertCitewaters2008validationinvitroTKstats. Both Fup and the credible interval 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_fup_red(
  FILENAME,
  data.in,
  TEMP.DIR = NULL,
  NUM.CHAINS = 5,
  NUM.CORES = 2,
  RANDOM.SEED = 1111,
  SEED.SET = NULL,
  good.col = "Verified",
  JAGS.PATH = NA,
  Physiological.Protein.Conc = 70/(66.5 * 1000) * 1e+06,
  save.MCMC = FALSE,
  sig.figs = 3,
  INPUT.DIR = NULL,
  OUTPUT.DIR = NULL,
  verbose = TRUE
)

Arguments

FILENAME	(Character) A string used to identify the input level-2 file, "<FILENAME>-fup-RED-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_fup_red 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	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.)
Physiological.Protein.Conc	(Numeric) The assumed physiological protein concentration for plasma protein binding calculations. (Defaults to 70/(66.5*1000)*1000000. According to \insertCiteberg2011pathology;textualinvitroTKstats: 60-80 mg/mL, albumin is 66.5 kDa, assume all protein is albumin to estimate default in uM.)
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.)

Details

The input to this function should be "level-2" data. Level-2 data is level-1 data, formatted with the format_fup_red 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/til/posts/2023-10-24-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 of these types:

No Plasma Blank (no chemical, no plasma)	NoPlasma.Blank
Plasma Blank (no chemical, just plasma)	Plasma.Blank
Time zero chemical and plasma	T0
Equilibrium chemical in phosphate-buffered well (no plasma)	PBS
Equilibrium chemical in plasma well	Plasma
Calibration Curve	CC

We currently require Plasma, PBS, and Plasma.Blank data. T0, CC, and NoPlasma.Blank data are optional.

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

Value

A list of two objects:

1. Results: A level-4 data frame with the Bayesian estimated fraction unbound in plasma (Fup) and credible interval 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, Fup.point - point estimate of Fup, Fup.Med - posterior median, Fup.Low - 2.5th quantile, and Fup.High - 97.5th quantile

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

Author(s)

John Wambaugh and Chantel Nicolas

References

\insertRef

waters2008validationinvitroTKstats

\insertRef

wambaugh2019assessinginvitroTKstats

\insertRef

berg2011pathologyinvitroTKstats

Examples

## Example 1: loading level-2 using data.in and export all files to the user's
## temporary directory
## Not run: 
level2 <- invitroTKstats::fup_red_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_fup_red(FILENAME = "Example1",
                       data.in = level2,
                       NUM.CORES=2,
                       JAGS.PATH=path.to.JAGS)

## End(Not run)

## Example 2: importing level-2 from a .tsv file and export all files to same 
## location as INPUT.DIR 
## Not run: 
# 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_fup_red(# e.g. replace with "Examples" from "Examples-fup-RED-Level2.tsv"
                       FILENAME="<level-2 FILENAME prefix>", 
                       NUM.CORES=2,
                       JAGS.PATH=path.to.JAGS,
                       INPUT.DIR = "<level-2 FILE LOCATION>")

## End(Not run)

invitroTKstats documentation built on Aug. 23, 2025, 9:08 a.m.