invitroTKstats (version 0.0.14)

calc_caco2_point: Calculate a Point Estimate of Apparent Membrane Permeability (Papp) from Caco-2 data (Level-3)

Description

This function calculates a point estimate of apparent membrane permeability (Papp) using mass spectrometry (MS) peak areas from samples collected as part of in vitro measurements of membrane permeability using Caco-2 cells hubatsch2007determinationinvitroTKstats.

Usage

calc_caco2_point(
  FILENAME,
  data.in,
  good.col = "Verified",
  output.res = FALSE,
  sig.figs = 3,
  INPUT.DIR = NULL,
  OUTPUT.DIR = NULL,
  verbose = TRUE
)

Value

data.frame

A level-3 data.frame in standardized format

C0_A2B	Time zero donor concentration	Mass Spec Response Ratio (RR)
dQdt_A2B	Estimated rate of mass movement through membrane	RR*cm^3/s
Papp_A2B	Apparent membrane permeability	10^-6 cm/s
C0_B2A	Time zero donor concentration	Mass Spec Response Ratio (RR)
dQdt_B2A	Estimated rate of mass movement through membrane	RR*cm^3/s
Papp_B2A	Apparent membrane permeability	10^-6 cm/s
Refflux	Efflux ratio	unitless
Frec_A2B.vec	Fraction recovered for the apical-basolateral direction, calculated as the fraction of the initial donor amount recovered in the receiver compartment (collapsed numeric vector, values for replicates separated by a "|")	unitless
Frec_A2B.mean	Mean of the fraction recovered for the apical-basolateral direction	unitless
Frec_B2A.vec	Fraction recovered for the basolateral-apical direction, calculated in the same way as Frec_A2B.vec but in the opposite transport direction (collapsed numeric vector, values for replicates separated by a "|")	unitless
Frec_B2A.mean	Mean of the fraction recovered for the basolateral-apical direction	unitless
Recovery_Class_A2B.vec	Recovery classification for apical-to-basolateral permeability("Low Recovery" if Frec_A2B.vec < 0.4 or "High Recovery" if Frec_A2B.vec > 2.0) (collapsed character vector, values for replicates separated by a "|")	qualitative category
Recovery_Class_A2B.mean	Recovery classification for the mean apical-to-basolateral permeability("Low Recovery" if Frec_A2B.mean < 0.4 or "High Recovery" if Frec_A2B.mean > 2.0)	qualitative category
Recovery_Class_B2A.vec	Recovery classification for basolateral-to-apical permeability("Low Recovery" if Frec_B2A.vec < 0.4 or "High Recovery" if Frec_B2A.vec > 2.0) (collapsed character vector, values for replicates separated by a "|")	qualitative category
Recovery_Class_B2A.mean	Recovery classification for the mean basolateral-to-apical permeability("Low Recovery" if Frec_B2A.mean < 0.4 or "High Recovery" if Frec_B2A.mean > 2.0)	qualitative category

Arguments

FILENAME

(Character) A string used to identify the input level-2 file, "<FILENAME>-Caco-2-Level2.tsv" (if importing from a .tsv file), and/or used to identify the output level-3 file, "<FILENAME>-Caco-2-Level3.tsv" (if exporting).

data.in

(Data Frame) A level-2 data frame generated from the format_caco2 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.)

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_caco2 function, and curated with a verification column. "Y" in the verification column indicates the data row is valid for analysis.

The data frame of observations should be annotated according to direction (either apical to basolateral -- "AtoB" -- or basolateral to apical -- "BtoA") and type of concentration measured:

Blank with no chemical added	Blank
Target concentration added to donor compartment at time 0 (C0)	D0
Donor compartment at end of experiment	D2
Receiver compartment at end of experiment	R2

Apparent membrane permeability (\(P_{app}\)) is calculated from MS responses as:

\(P_{app} = \frac{dQ/dt}{c_0*A}\)

The rate of permeation, \(\frac{dQ}{dt}\)\(\left(\frac{\text{peak area}}{\text{time (s)}} \right)\) is calculated as:

\(\frac{dQ}{dt} = \max\left(0, \frac{\sum_{i=1}^{n_{R2}} (r_{R2} * c_{DF})}{n_{R2}} - \frac{\sum_{i=1}^{n_{BL}} (r_{BL} * c_{DF})}{n_{BL}}\right)\)

where \(r_{R2}\) is Receiver Response, \(c_{DF}\) is the corresponding Dilution Factor, \(r_{BL}\) is Blank Response, \(n_{R2}\) is the number of Receiver Responses, and \(n_{BL}\) is the number of Blank 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/blog/posts/2023-10-24-til-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.

References

hubatsch2007determinationinvitroTKstats

Examples

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

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

## scenario 2: 
## import level-2 data from a 'tsv' file and export the result table to 
## same location as INPUT.DIR 
if (FALSE) {
## 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_caco2_point(# e.g. replace with "Examples" from "Examples-Caco-2-Level2.tsv" 
                           FILENAME="", 
                           INPUT.DIR = "",
                           output.res = TRUE)
}

## scenario 3: 
## input 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. 
if (FALSE) {
level3 <- calc_caco2_point(# e.g. replace with "MYDATA"
                           FILENAME = "",
                           data.in = level2,
                           output.res = TRUE)
# To delete, use the following code. For more details, see the link in the 
# "Details" section. 
file.remove(list.files(tempdir(), full.names = TRUE, 
pattern = "-Caco-2-Level3.tsv"))
}