calc_fup_uc: Calculate Fraction Unbound in Plasma (Fup) from...

In invitroTKstats: In Vitro Toxicokinetic Data Processing and Analysis Pipeline

Calculate Fraction Unbound in Plasma (Fup) from Ultracentrifugation (UC) Data with Bayesian Modeling (Level-4)

Description

This function estimates the fraction unbound in plasma (Fup) and credible intervals with a Bayesian modeling approach, via MCMC simulations. Data used in modeling is collected from Ultracentrifugation (UC) Fup assays \insertCiteredgrave1975separationinvitroTKstats. Fup and the credible interval are calculated from the MCMC posterior samples and the function returns a summary table (level-4) along with the full set of MCMC results.

Usage

calc_fup_uc(
  FILENAME,
  data.in,
  TEMP.DIR = NULL,
  NUM.CHAINS = 5,
  NUM.CORES = 2,
  RANDOM.SEED = 1111,
  SEED.SET = NULL,
  good.col = "Verified",
  JAGS.PATH = NA,
  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-UC-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	A level-2 data frame generated from the format_fup_uc 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'.)
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_uc 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 exportef 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:

Calibration Curve	CC
Ultracentrifugation Aqueous Fraction	AF
Whole Plasma T1h Sample	T1
Whole Plasma T5h Sample	T5

We currently require CC, AF, and T5 data. T1 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 Bayesian estimated fraction unbound in plasma (Fup) 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, Fup.point - point estimate of Fup, Fup.Med - posterior median, Fup.Low - 2.5th quantile, Fup.High - 97.5th quantile, Fstable.Med - posterior median of stability fraction, Fstable.Low - 2.5th quantile, Fstable.High - 97.5th quantile.

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

Author(s)

John Wambaugh and Chantel Nicolas

References

\insertRef

redgrave1975separationinvitroTKstats

Examples

## Example 1: loading level-2 using data.in and export all files to the user's
## temporary directory
## Not run: 
level2 <- invitroTKstats::fup_uc_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_uc(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_uc(# e.g. replace with "Examples" from "Examples-fup-UC-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.