calc_fup_uc_point: Calculate Point Estimates of Fraction Unbound in Plasma (Fup)...

In invitroTKstats: In Vitro Toxicokinetic Data Processing and Analysis Pipeline

Calculate Point Estimates of Fraction Unbound in Plasma (Fup) with Ultracentrifugation (UC) Data (Level-3)

Description

This function calculates the point estimates for the fraction unbound in plasma (Fup) using mass spectrometry (MS) peak areas from samples collected as part of in vitro measurements of chemical Fup using ultracentrifugation \insertCiteredgrave1975separationinvitroTKstats. See the Details section for the equation(s) used in the point estimate.

Usage

calc_fup_uc_point(
  FILENAME,
  data.in,
  good.col = "Verified",
  output.res = 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" (if importing from a .tsv file), and/or used to identify the output level-3 file, "<FILENAME>-fup-UC-Level3.tsv" (if exporting).
data.in	(Data Frame) 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.
good.col	(Character) Column name indicating which rows have been verified, data rows valid for analysis are indicated with a "Y". (Defaults to "Verified".)
output.res	(Logical) When set to TRUE, the result table (level-3) will be exported to the user's per-session temporary directory or OUTPUT.DIR (if specified) as a .tsv file. (Defaults to FALSE.)
sig.figs	(Numeric) The number of significant figures to round the exported result table (level-3). (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.

The should be annotated according to of these types:

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

f_{up} is calculated from MS responses as:

f_{up} = \frac{\sum_{i = 1}^{n_A} (r_A * c_{DF}) / n_A}{\sum_{i = 1}^{n_{T5}} (r_{T5} * c_{DF}) / n_{T5}}

where r_A is Aqueous Fraction Response, c_{DF} is the corresponding Dilution Factor, r_{T5} is T5 Response, n_A is the number of Aqueous Fraction Responses, and n_{T5} is the number of T5 Responses.

If the output level-3 result table is chosen to be exported and an output directory is not specified, it will be exported to the user's R 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/.

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.

Value

A level-3 data frame with one row per chemical, contains chemical identifiers such as preferred compound name, compound name used by the laboratory, EPA's DSSTox Structure ID, calibration, and point estimates for the fraction unbound in plasma (Fup) for all chemicals in the input data frame.

Author(s)

John Wambaugh

References

\insertRef

redgrave1975separationinvitroTKstats

Examples

## Load example level-2 data
level2 <- invitroTKstats::fup_uc_L2

## scenario 1: 
## input level-2 data from the R session and do not export the result table
level3 <- calc_fup_uc_point(data.in = level2, output.res = FALSE)

## scenario 2: 
## import level-2 data from a 'tsv' file and export the result table
## Not run: 
## Refer to sample_verification help file for how to export level-2 data to a directory.
## Unless a different path is specified in OUTPUT.DIR,
## the result table will be saved to the directory specified in INPUT.DIR.
## Will need to replace FILENAME and INPUT.DIR with name prefix and location of level-2 'tsv'.
level3 <- calc_fup_uc_point(# e.g. replace with "Examples" from "Examples-fup-UC-Level2.tsv" 
                            FILENAME="<level-2 FILENAME prefix>", 
                            INPUT.DIR = "<level-2 FILE LOCATION>",
                            output.res = TRUE)

## End(Not run)

## scenario 3: 
## import level-2 data from the R session and export the result table to the
## user's temporary directory 
## Will need to replace FILENAME with desired level-2 filename prefix. 
## Not run: 
level3 <- calc_fup_uc_point(# e.g. replace with "MYDATA",
                             FILENAME = "<desired level-2 FILENAME prefix>",
                             data.in = level2,
                             output.res = TRUE)
# To delete, use the following code. For more details, see the link in the 
file.remove(list.files(tempdir(), full.names = TRUE, 
pattern = "<desired level-2 FILENAME prefix>-fup-UC-Level3.tsv"))  

## End(Not run)

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